1# Usage 2## Two options to use the hid command: 3### 1. Interactive through stdin: 4type `hid -` into the terminal, then type/paste commands to send to the binary. 5Use Ctrl+D to signal end of stream to the binary (EOF). 6 7This mode can be also used from an app to send HID events. 8For an example, see the cts test case at: [InputTestCase.java][2] 9 10When using another program to control hid in interactive mode, registering a 11new input device (for example, a bluetooth joystick) should be the first step. 12After the device is added, you need to wait for the _onInputDeviceAdded_ 13(see [InputDeviceListener][1]) notification before issuing commands 14to the device. 15Failure to do so will cause missed events and inconsistent behaviour. 16In the current implementation of the hid command, the hid binary will wait 17for the file descriptor to the uhid node to send the UHID_START and UHID_OPEN 18signals before returning. However, this is not sufficient. These signals 19only notify the readiness of the kernel driver, 20but do not take into account the inputflinger framework. 21 22 23### 2. Using a file as an input: 24type `hid <filename>`, and the file will be used an an input to the binary. 25You must add a sufficient delay after a "register" command to ensure device 26is ready. The interactive mode is the recommended method of communicating 27with the hid binary. 28 29All of the input commands should be in pseudo-JSON format as documented below. 30See examples [here][3]. 31 32The file can have multiple commands one after the other (which is not strictly 33legal JSON format, as this would imply multiple root elements). 34 35## Command description 36 371. `register` 38Register a new uhid device 39 40| Field | Type | Description | 41|:-------------:|:-------------:|:-------------------------- | 42| id | integer | Device id | 43| command | string | Must be set to "register" | 44| name | string | Device name | 45| vid | 16-bit integer| Vendor id | 46| pid | 16-bit integer| Product id | 47| bus | string | Bus that device should use | 48| descriptor | byte array | USB HID report descriptor | 49 50Device ID is used for matching the subsequent commands to a specific device 51to avoid ambiguity when multiple devices are registered. 52 53Device bus is used to determine how the uhid device is connected to the host. 54The options are "usb" and "bluetooth". 55 56USB HID report descriptor should be generated according the the USB HID spec 57and can be checked by reverse parsing using a variety of tools, for example 58[usbdescreqparser][5]. 59 60Example: 61```json 62{ 63 "id": 1, 64 "command": "register", 65 "name": "Odie (Test)", 66 "vid": 0x18d1, 67 "pid": 0x2c40, 68 "bus": "usb", 69 "descriptor": [0x05, 0x01, 0x09, 0x05, 0xa1, 0x01, 0x85, 0x01, 0x05, 0x09, 0x0a, 0x01, 0x00, 70 0x0a, 0x02, 0x00, 0x0a, 0x04, 0x00, 0x0a, 0x05, 0x00, 0x0a, 0x07, 0x00, 0x0a, 0x08, 0x00, 71 0x0a, 0x0e, 0x00, 0x0a, 0x0f, 0x00, 0x0a, 0x0d, 0x00, 0x05, 0x0c, 0x0a, 0x24, 0x02, 0x0a, 72 0x23, 0x02, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x0b, 0x81, 0x02, 0x75, 0x01, 0x95, 73 0x01, 0x81, 0x03, 0x05, 0x01, 0x75, 0x04, 0x95, 0x01, 0x25, 0x07, 0x46, 0x3b, 0x01, 0x66, 74 0x14, 0x00, 0x09, 0x39, 0x81, 0x42, 0x66, 0x00, 0x00, 0x09, 0x01, 0xa1, 0x00, 0x09, 0x30, 75 0x09, 0x31, 0x09, 0x32, 0x09, 0x35, 0x05, 0x02, 0x09, 0xc5, 0x09, 0xc4, 0x15, 0x00, 0x26, 76 0xff, 0x00, 0x35, 0x00, 0x46, 0xff, 0x00, 0x75, 0x08, 0x95, 0x06, 0x81, 0x02, 0xc0, 0x85, 77 0x02, 0x05, 0x08, 0x0a, 0x01, 0x00, 0x0a, 0x02, 0x00, 0x0a, 0x03, 0x00, 0x0a, 0x04, 0x00, 78 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x04, 0x91, 0x02, 0x75, 0x04, 0x95, 0x01, 0x91, 79 0x03, 0xc0, 0x05, 0x0c, 0x09, 0x01, 0xa1, 0x01, 0x85, 0x03, 0x05, 0x01, 0x09, 0x06, 0xa1, 80 0x02, 0x05, 0x06, 0x09, 0x20, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 0x08, 0x95, 0x01, 0x81, 81 0x02, 0x06, 0xbc, 0xff, 0x0a, 0xad, 0xbd, 0x75, 0x08, 0x95, 0x06, 0x81, 0x02, 0xc0, 0xc0] 82} 83``` 842. `delay` 85Add a delay to command processing 86 87| Field | Type | Description | 88|:-------------:|:-------------:|:-------------------------- | 89| id | integer | Device id | 90| command | string | Must be set to "delay" | 91| duration | integer | Delay in milliseconds | 92 93Example: 94```json 95{ 96 "id": 1, 97 "command": "delay", 98 "duration": 10 99} 100``` 101 1023. `report` 103Send a report to the HID device 104 105| Field | Type | Description | 106|:-------------:|:-------------:|:-------------------------- | 107| id | integer | Device id | 108| command | string | Must be set to "report" | 109| report | byte array | Report data to send | 110 111Example: 112```json 113{ 114 "id": 1, 115 "command": "report", 116 "report": [0x01, 0x01, 0x80, 0x7f, 0x7f, 0x7f, 0x7f, 0x00, 0x00] 117} 118``` 119 120### Sending a joystick button press event 121To send a button press event on a joystick device: 1221. Register the joystick device 1232. Send button down event with coordinates ABS_X, ABS_Y, ABS_Z, and ABS_RZ 124at the center of the range. If the coordinates are not centered, this event 125will generate a motion event within the input framework, in addition to the 126button press event. The range can be determined from the uhid report descriptor. 1273. Send the button up event with the same coordinates as in 2. 1284. Check that the button press event was received. 129 130### Notes 1311. As soon as EOF is reached (either in interactive mode, or in file mode), 132the device that was created will be unregistered. There is no 133explicit command for unregistering a device. 1342. The linux input subsystem does not generate events for those values 135that remain unchanged. For example, if there are two events sent to the driver, 136and both events have the same value of ABS_X, then ABS_X coordinate 137will not be reported. 1383. The description of joystick actions is available [here][6]. 1394. Joysticks are split axes. When an analog stick is in a resting state, 140the reported coordinates are at the center of the range. 1415. The `getevent` utility can used to print out the key events 142for debugging purposes. 143 144 145[1]: https://developer.android.com/reference/android/hardware/input/InputManager.InputDeviceListener.html 146[2]: ../../../../cts/tests/tests/hardware/src/android/hardware/input/cts/tests/InputTestCase.java 147[3]: ../../../../cts/tests/tests/hardware/res/raw/ 148[4]: https://developer.android.com/training/game-controllers/controller-input.html#button 149[5]: http://eleccelerator.com/usbdescreqparser/ 150[6]: https://developer.android.com/training/game-controllers/controller-input.html 151