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| descriptor    | byte array    | USB HID report descriptor  |
48
49Device ID is used for matching the subsequent commands to a specific device
50to avoid ambiguity when multiple devices are registered.
51
52USB HID report descriptor should be generated according the the USB HID spec
53and can be checked by reverse parsing using a variety of tools, for example
54[usbdescreqparser][5].
55
56Example:
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```
792. `delay`
80Add 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
88Example:
89```json
90{
91  "id": 1,
92  "command": "delay",
93  "duration": 10
94}
95```
96
973. `report`
98Send 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
106Example:
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
116To send a button press event on a joystick device:
1171. Register the joystick device
1182. Send button down event with coordinates ABS_X, ABS_Y, ABS_Z, and ABS_RZ
119at the center of the range. If the coordinates are not centered, this event
120will generate a motion event within the input framework, in addition to the
121button press event. The range can be determined from the uhid report descriptor.
1223. Send the button up event with the same coordinates as in 2.
1234. Check that the button press event was received.
124
125### Notes
1261. As soon as EOF is reached (either in interactive mode, or in file mode),
127the device that was created will be unregistered. There is no
128explicit command for unregistering a device.
1292. The linux input subsystem does not generate events for those values
130that remain unchanged. For example, if there are two events sent to the driver,
131and both events have the same value of ABS_X, then ABS_X coordinate
132will not be reported.
1333. The description of joystick actions is available [here][6].
1344. Joysticks are split axes. When an analog stick is in a resting state,
135the reported coordinates are at the center of the range.
1365. The `getevent` utility can used to print out the key events
137for 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