Moto Z Software: Mod HID

HID support over greybus

The HID (Human Interface Device) protocol is supported over the Greybus Moto Mod interface. HID supports HID buttons, keyboard and mouse and trackpad devices. Any device type currently supported by Android’s USB HID implementation is supported over the Moto Mod Greybus HID interface, this includes buttons, keyboards and keypads, gamepads and touch devices.

Events generated on a HID class compliant Moto Mod are routed to, and available for consumption, your Android phone, as input or motion events.

Moto Mod HIDs leverage Android’s existing USB HID implementation.  A developer interested in developing a Moto Mod which embeds human interface controls should have knowledge of Android’s input subsystem as documented in the Android PDK.

There are no new or proprietary APIs in the Moto Mod SDK for HID support. 


Moto Mod HID support

A class compliant Moto Mod HID will pass its USB HID PID/VID in to the Moto Z in HID descriptors. This PID/VID combination will be used by Android to transform a HID event into an Android event.

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;
};

The VID/PID generated in these report descriptors will be used by Android’s input pipeline to locate the appropriate Key Layout, Keymap and Input Device Configuration files and translate these into Android Keycodes, using the same heuristic as is used for other USB HID devices and detailed in the Android Input subsystem overview document.


Android HID Integration

Events generated by an attached HID compliant Moto Mod are routed to Android’s EventHub by the Greybus HID kernel driver. As in standard Android HID support, the InputReader will decode the input events and produce Android input events. Android will either use the Input Device configuration, Keyboard Layout and Keymap files associated with the input device or use the  system defaults to decode the input events into Android input events.

By default, to decode events from your input device, Android will use the same logic it uses for USB HID devices:

  • The Input Device configuration file associated with your input device, as documented in the Android SDK. Similarly, Android will use the VID/PID passed in your HID report descriptor to determine the IDC file to use.
     
  • The Key-layout file associated with your HID device, as documented in the Android SDK. Please note: The VID/PID passed in your HID report descriptor will determine the key layout file to use, not the VID/PID advertised in the Moto Mod hardware manifest.
     
  • The Key-map file associated with your HID device, as documented in the Android SDK. Similarly, Android with use the VID/PID passed in via your HID report descriptor.

HID Usage and Keycodes

Android supports a variety of keyboard devices including special function keypads (volume and power controls), compact embedded QWERTY keyboards, and fully featured PC-style external keyboards. For a complete list of the HID mappings and their corresponding Linux and Android Keycodes, please refer to the HID section of the Android PDK. When an HID Moto Mod is attached to the Moto Z, and active, Android application will receive input event with the Android KEYCODE_ corresponding to the HID usage value generated by your Moto Mod.


Detecting whether a Moto Mod supports HID

If your Moto Mod embeds a HID compliant device, the Moto Mod platform will make the HID available to the Moto Z immediately when attached. If your application needs to determine whether the moto mod currently attached to your phone support the HID protocol, it can use the hasDeclaredProtocol() function to determine whether the attached ModDevice supports the HID protocol as illustrated below.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.HID) {
    // This Mod declares USB in its manifest
  }

Receiving HID events

If your Moto Mod embeds a HID compliant device, the Moto Mod platform will make the HID devices available to the Moto Z immediately when attached and fully enumerated. As soon as the HID protocol device has been successfully brought up, as indicated by the ACTION_MOD_ENUMERATION_DONE, the HID events generated by the connected Moto Mod will be routed to the Android input subsystem.