Moto Mods Firmware: HID Protocol¶

Overview¶

The HID protocol provides a means for the Moto Mod to send Human Interface Device (HID) events to the Moto Z. These standard events as outlined in the USB org HID Protocol are processed by Android on the Moto Z as native HID.

See Moto Z Software: Mod HID for details of the Android usage of the HID protocol.

Hardware Manifest¶

; HID interface on CPort XX
[cport-descriptor XX]
bundle = YY
protocol = 0x05

; HID Bundle YY
[bundle-descriptor YY]
class = 0x05

XX is a unique integer (within your hardware manifest) defining which CPort is used for the HID Interface.

YY is a unique integer (within your hardware manifest) which Bundle the HID CPort is a member of.

Implementation¶

Files¶

nuttx/include/nuttx/device_hid.h

Structures¶

hid_descriptor¶

struct hid_descriptor {
    uint8_t length;
    uint16_t report_desc_length;
    uint16_t hid_version;
    uint16_t product_id;
    uint16_t vendor_id;
    uint8_t country_code;
};

Callback Methods¶

The following types and methods provide a means for the driver implementing the HID device to send events to the Moto Z.

hid_event_callback¶

The hid_event_callback method sends a HID report to the Moto Z.

typedef int hid_event_callback(struct device *dev, uint8_t report_type,
                                  uint8_t *report, uint16_t len);

Parameters
`dev`	Matches dev passed to the probe function.
`report_type`	HID report_type.
`report`	HID report data follows the HID specification http://www.usb.org/developers/hidpage.
`len`	Length of the report.
Return
`int`	0 on success, negative errno on error.

register_callback¶

register_callback is called when the greybus interface provides the method to send HID events to the Moto Z. If the driver needs to send HID events (which seems likely) the method should be stored so that it can be invoked for sending events.

int (*register_callback)(struct device *dev, hid_event_callback callback);

Parameters
`dev`	Matches dev passed to the probe function.
`callback`	hid_event_callback
Return
`int`	0 on success, negative errno on error.

unregister_callback¶

Once the unregister_callback is called, the callee should assume the method provided in register_callback is now invalid.

int (*unregister_callback)(struct device *dev);

Parameters
`dev`	Matches dev passed to the probe function.
`callback`	hid_event_callback
Return
`int`	0 on success, negative errno on error.

Methods¶

power_on¶

Sent by the Moto Z to the Moto Mod to tell the device to turn on.

int (*power_on)(struct device *dev);

Parameters
`dev`	Matches dev passed to the probe function.
Return
`int`	0 on success, negative errno on error.

power_off¶

Sent by the Moto Z to the Moto Mod to tell the device to turn off.

int (*power_off)(struct device *dev);

Parameters
`dev`	Matches dev passed to the probe function.
Return
`int`	0 on success, negative errno on error.

get_descriptor¶

get_descriptor returns the HID descriptor.

int (*get_descriptor)(struct device *dev, struct hid_descriptor *desc);

Parameters
`dev`	Matches dev passed to the probe function.
`desc`	Returns the descriptor associated with the the device functionality provided.
Return
`int`	0 on success, negative errno on error.

get_report_descriptor¶

get_report_descriptor returns the HID report descriptor.

int (*get_report_descriptor)(struct device *dev, uint8_t *desc);

Parameters
`dev`	Matches dev passed to the probe function.
`desc`	Returns the report descriptor as described by http://www.usb.org/developers/hidpage/.
Return
`int`	0 on success, negative errno on error.

get_report_length¶

get_report_length returns the length of the report.

int (*get_report_length)(struct device *dev, uint8_t report_type,
                             uint8_t report_id);

Parameters
`dev`	Matches dev passed to the probe function.
`report_type`	The type of report (Input, Output, or Feature).
Return
`int`	0 on success, negative errno on error.

get_maximum_report_length¶

get_maximum_report_length returns the maximum length of a report for the given type.

int (*get_maximum_report_length)(struct device *dev, uint8_t report_type);

Parameters
`dev`	Matches dev passed to the probe function.
`report_type`	The type of report (Input, Output, or Feature).
Return
`int`	0 on success, negative errno on error.

get_report¶

get_report returns the HID report.

int (*get_report)(struct device *dev, uint8_t report_type,
                      uint8_t report_id, uint8_t *data, uint16_t len);

Parameters
`dev`	Matches dev passed to the probe function.
`report_type`	The type of the report (Input, Output, or Feature).
`report_id`	The specific report id from the descriptor.
`data`	The report data.
`len`	The length of the report data.
Return
`int`	0 on success, negative errno on error.

set_report¶

set_report sends the HID report from Moto Z to the Moto Mod. Sends a report as documented at http://www.usb.org/developers/hidpage/

int (*set_report)(struct device *dev, uint8_t report_type,
                      uint8_t report_id, uint8_t *data, uint16_t len);

Parameters
`dev`	Matches dev passed to the probe function.
`report_type`	The type of the report (Input, Output, or Feature).
`report_id`	The specific report id from the descriptor.
`data`	The report data.
`len`	The length of the report data.
Return
`int`	0 on success, negative errno on error.

< Previous Page Audio Protocol

Next Page > USB-Ext Protocol