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