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.