1# Usage
2##  Two options to use the uinput command:
3### 1. Interactive through stdin:
4type `uinput -` 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 uinput events.
8For an example, see the cts test case at: [InputTestCase.java][2]
9
10When using another program to control uinput 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 behavior.
16
17### 2. Using a file as an input:
18type `uinput <filename>`, and the file will be used an an input to the binary.
19You must add a sufficient delay after a "register" command to ensure device
20is ready. The interactive mode is the recommended method of communicating
21with the uinput binary.
22
23All of the input commands should be in pseudo-JSON format as documented below.
24See examples [here][3].
25
26The file can have multiple commands one after the other (which is not strictly
27legal JSON format, as this would imply multiple root elements).
28
29## Command description
30
311. `register`
32Register a new uinput device
33
34| Field         | Type          | Description                |
35|:-------------:|:-------------:|:-------------------------- |
36| id            | integer       | Device id                  |
37| command       | string        | Must be set to "register"  |
38| name          | string        | Device name                |
39| vid           | 16-bit integer| Vendor id                  |
40| pid           | 16-bit integer| Product id                 |
41| bus           | string        | Bus that device should use |
42| configuration | int array     | uinput device configuration|
43| ff_effects_max| integer       | ff_effects_max value       |
44| abs_info      | array         | ABS axes information       |
45
46Device ID is used for matching the subsequent commands to a specific device
47to avoid ambiguity when multiple devices are registered.
48
49Device bus is used to determine how the uinput device is connected to the host.
50The options are "usb" and "bluetooth".
51
52Device configuration is used to configure uinput device.  "type" field provides the UI_SET_*
53control code, and data is a vector of control values to be sent to uinput device, depends on
54the control code.
55
56| Field         | Type          | Description                |
57|:-------------:|:-------------:|:-------------------------- |
58| type          | integer       | UI_SET_ control type       |
59| data          | int array     | control values             |
60
61Device ff_effects_max must be provided if FFBIT is set.
62
63Device abs_info fields are provided to set the device axes information. It is an array of below
64objects:
65| Field         | Type          | Description                |
66|:-------------:|:-------------:|:-------------------------- |
67| code          | integer       | Axis code                  |
68| info          | object        | ABS information object     |
69
70ABS information object is defined as below:
71| Field         | Type          | Description                |
72|:-------------:|:-------------:|:-------------------------- |
73| value         | integer       | Latest reported value      |
74| minimum       | integer       | Minimum value for the axis |
75| maximum       | integer       | Maximum value for the axis |
76| fuzz          | integer       | fuzz value for noise filter|
77| flat          | integer       | values to be discarded     |
78| resolution    | integer       | resolution of axis         |
79
80See [struct input_absinfo][4]) definitions.
81
82Example:
83```json
84
85{
86  "id": 1,
87  "command": "register",
88  "name": "Keyboard (Test)",
89  "vid": 0x18d2,
90  "pid": 0x2c42,
91  "bus": "usb",
92  "configuration":[
93        {"type":100, "data":[1, 21]},  // UI_SET_EVBIT : EV_KEY and EV_FF
94        {"type":101, "data":[11, 2, 3, 4]},   // UI_SET_KEYBIT : KEY_0 KEY_1 KEY_2 KEY_3
95        {"type":107, "data":[80]}    //  UI_SET_FFBIT : FF_RUMBLE
96  ],
97  "ff_effects_max" : 1,
98  "abs_info": [
99        {"code":1, "info": {"value":20, "minimum":-255,
100                            "maximum":255, "fuzz":0, "flat":0, "resolution":1}
101        },
102        {"code":8, "info": {"value":-50, "minimum":-255,
103                            "maximum":255, "fuzz":0, "flat":0, "resolution":1}
104        }
105  ]
106}
107
108```
1092. `delay`
110Add a delay to command processing
111
112| Field         | Type          | Description                |
113|:-------------:|:-------------:|:-------------------------- |
114| id            | integer       | Device id                  |
115| command       | string        | Must be set to "delay"     |
116| duration      | integer       | Delay in milliseconds      |
117
118Example:
119```json
120{
121  "id": 1,
122  "command": "delay",
123  "duration": 10
124}
125```
126
1273. `inject`
128Send an array of uinput event packets [type, code, value] to the uinput device
129
130| Field         | Type          | Description                |
131|:-------------:|:-------------:|:-------------------------- |
132| id            | integer       | Device id                  |
133| command       | string        | Must be set to "inject"    |
134| events        | integer array | events to inject           |
135
136The "events" parameter is an array of integers, encapsulates evdev input_event type, code and value,
137see the example below.
138
139Example:
140```json
141{
142  "id": 1,
143  "command": "inject",
144  "events": [0x01, 0xb,  0x1,   // EV_KEY, KEY_0, DOWN
145             0x00, 0x00, 0x00,  // EV_SYN, SYN_REPORT, 0
146             0x01, 0x0b, 0x00,  // EV_KEY, KEY_0, UP
147             0x00, 0x00, 0x00,  // EV_SYN, SYN_REPORT, 0
148             0x01, 0x2,  0x1,   // EV_KEY, KEY_1, DOWN
149             0x00, 0x00, 0x01,  // EV_SYN, SYN_REPORT, 0
150             0x01, 0x02, 0x00,  // EV_KEY, KEY_1, UP
151             0x00, 0x00, 0x01   // EV_SYN, SYN_REPORT, 0
152            ]
153}
154```
155
1564. `sync`
157
158A command used to get a response once the command is processed. When several `inject` and `delay`
159commands are used in a row, the `sync` command can be used to track the progress of the command
160queue.
161
162|    Field    |  Type   | Description                                  |
163|:-----------:|:-------:|:---------------------------------------------|
164|    `id`     | integer | Device ID                                    |
165|  `command`  | string  | Must be set to "sync"                        |
166| `syncToken` | string  | The token used to identify this sync command |
167
168Example:
169
170```json5
171{
172  "id": 1,
173  "command": "syncToken",
174  "syncToken": "finished_injecting_events"
175}
176```
177
178This command will result in the following response when it is processed:
179
180```json5
181{
182  "id": 1,
183  "result": "sync",
184  "syncToken": "finished_injecting_events"
185}
186```
187
188### Notes
1891. As soon as EOF is reached (either in interactive mode, or in file mode),
190the device that was created will be unregistered. There is no
191explicit command for unregistering a device.
1922. The `getevent` utility can used to print out the key events
193for debugging purposes.
194
195[1]: https://developer.android.com/reference/android/hardware/input/InputManager.InputDeviceListener.html
196[2]: ../../../../cts/tests/tests/hardware/src/android/hardware/input/cts/tests/InputTestCase.java
197[3]: ../../../../cts/tests/tests/hardware/res/raw/
198[4]: ../../../../bionic/libc/kernel/uapi/linux/input.h
199