1# Usage
2
3There are two ways to use the `uinput` command:
4
5* **Recommended:** `uinput -` reads commands from standard input until End-of-File (Ctrl+D) is sent.
6  This mode can be used interactively from a terminal or used to control uinput from another program
7  or app (such as the CTS tests via [`UinputDevice`][UinputDevice]).
8* `uinput <filename>` reads commands from a file instead of standard input.
9
10There are also two supported input formats, described in the sections below. The tool will
11automatically detect which format is being used.
12
13[UinputDevice]: https://cs.android.com/android/platform/superproject/main/+/main:cts/libs/input/src/com/android/cts/input/UinputDevice.java
14
15## evemu recording format (recommended)
16
17`uinput` supports the evemu format, as used by the [FreeDesktop project's evemu suite][FreeDesktop].
18This is a simple text-based format compatible with recording and replay tools on other platforms.
19However, it only supports playback of events from one device from a single recording. Recordings can
20be made using the `evemu-record` command on Android or other Linux-based OSes.
21
22[FreeDesktop]: https://gitlab.freedesktop.org/libevdev/evemu
23
24## JSON-like format
25
26The other supported format is JSON-based, though the parser is in [lenient mode] to allow comments,
27and integers can be specified in hexadecimal (e.g. `0xABCD`). The input file (or standard input) can
28contain multiple commands, which will be executed in sequence. Simply add multiple JSON objects to
29the file, one after the other without separators:
30
31```json5
32{
33  "id": 1,
34  "command": "register",
35  // ...
36}
37{
38  "id": 1,
39  "command": "delay",
40  // ...
41}
42```
43
44Many examples of command files can be found [in the CTS tests][cts-example-jsons].
45
46[lenient mode]: https://developer.android.com/reference/android/util/JsonReader#setLenient(boolean)
47[cts-example-jsons]: https://cs.android.com/android/platform/superproject/main/+/main:cts/tests/tests/hardware/res/raw/
48
49### Command reference
50
51#### `register`
52
53Register a new uinput device
54
55| Field            | Type           | Description                |
56|:----------------:|:--------------:|:-------------------------- |
57| `id`             | integer        | Device ID                  |
58| `command`        | string         | Must be set to "register"  |
59| `name`           | string         | Device name                |
60| `vid`            | 16-bit integer | Vendor ID                  |
61| `pid`            | 16-bit integer | Product ID                 |
62| `bus`            | string         | Bus that device should use |
63| `port`           | string         | `phys` value to report     |
64| `configuration`  | object array   | uinput device configuration|
65| `ff_effects_max` | integer        | `ff_effects_max` value     |
66| `abs_info`       | array          | Absolute axes information  |
67
68`id` is used for matching the subsequent commands to a specific device to avoid ambiguity when
69multiple devices are registered.
70
71`bus` is used to determine how the uinput device is connected to the host. The options are `"usb"`
72and `"bluetooth"`.
73
74Device configuration is used to configure the uinput device. The `type` field provides a `UI_SET_*`
75control code as an integer value or a string label (e.g. `"UI_SET_EVBIT"`), and data is a vector of
76control values to be sent to the uinput device, which depends on the control code.
77
78| Field         |         Type          | Description            |
79|:-------------:|:---------------------:|:-----------------------|
80| `type`        |    integer\|string    | `UI_SET_` control type |
81| `data`        | integer\|string array | control values         |
82
83Due to the sequential nature in which this is parsed, the `type` field must be specified before
84the `data` field in this JSON Object.
85
86`ff_effects_max` must be provided if `UI_SET_FFBIT` is used in `configuration`.
87
88`abs_info` fields are provided to set the device axes information. It is an array of below objects:
89
90| Field         |      Type       | Description             |
91|:-------------:|:---------------:|:------------------------|
92| `code`        | integer\|string | Axis code or label      |
93| `info`        |     object      | Axis information object |
94
95The axis information object is defined as below, with the fields having the same meaning as those
96Linux's [`struct input_absinfo`][struct input_absinfo]:
97
98| Field         | Type          | Description                |
99|:-------------:|:-------------:|:-------------------------- |
100| `value`       | integer       | Latest reported value      |
101| `minimum`     | integer       | Minimum value for the axis |
102| `maximum`     | integer       | Maximum value for the axis |
103| `fuzz`        | integer       | fuzz value for noise filter|
104| `flat`        | integer       | values to be discarded     |
105| `resolution`  | integer       | resolution of axis         |
106
107Example:
108
109```json5
110{
111  "id": 1,
112  "command": "register",
113  "name": "Keyboard (Test)",
114  "vid": 0x18d2,
115  "pid": 0x2c42,
116  "bus": "usb",
117  "configuration":[
118        {"type":"UI_SET_EVBIT", "data":["EV_KEY", "EV_FF"]},
119        {"type":"UI_SET_KEYBIT", "data":["KEY_0", "KEY_1", "KEY_2", "KEY_3"]},
120        {"type":"UI_SET_ABSBIT", "data":["ABS_Y", "ABS_WHEEL"]},
121        {"type":"UI_SET_FFBIT", "data":["FF_RUMBLE"]}
122  ],
123  "ff_effects_max" : 1,
124  "abs_info": [
125        {"code":"ABS_Y", "info": {"value":20, "minimum":-255,
126                            "maximum":255, "fuzz":0, "flat":0, "resolution":1}
127        },
128        {"code":"ABS_WHEEL", "info": {"value":-50, "minimum":-255,
129                            "maximum":255, "fuzz":0, "flat":0, "resolution":1}
130        }
131  ]
132}
133```
134
135[struct input_absinfo]: https://cs.android.com/android/platform/superproject/main/+/main:bionic/libc/kernel/uapi/linux/input.h?q=%22struct%20input_absinfo%22
136
137##### Waiting for registration
138
139After the command is sent, there will be a delay before the device is set up by the Android input
140stack, and `uinput` does not wait for that process to finish. Any commands sent to the device during
141that time will be dropped. If you are controlling `uinput` by sending commands through standard
142input from an app, you need to wait for [`onInputDeviceAdded`][onInputDeviceAdded] to be called on
143an `InputDeviceListener` before issuing commands to the device. If you are passing a file to
144`uinput`, add a `delay` after the `register` command to let registration complete. You can add a
145`sync` in certain positions, like at the end of the file to get a response when all commands have
146finished processing.
147
148[onInputDeviceAdded]: https://developer.android.com/reference/android/hardware/input/InputManager.InputDeviceListener.html
149
150##### Unregistering the device
151
152As soon as EOF is reached (either in interactive mode, or in file mode), the device that was created
153will be unregistered. There is no explicit command for unregistering a device.
154
155#### `delay`
156
157Add a delay between the processing of commands.
158
159The delay will be timed relative to the time base, a reference time which is set when the device is
160registered or by the `updateTimeBase` command. Take the following set of example commands:
161
1621. `register` device
1632. `delay` 500ms
1643. `inject` some events
1654. `delay` 10ms
1665. `inject` more events
167
168If the `register` command is executed at time _X_, the injection at step 3 will be scheduled for
169time _X_+500ms. Since scheduling isn't precise, they might actually be injected a few milliseconds
170later, but regardless of that the injection at step 5 will always be scheduled for _X_+510ms. This
171prevents scheduling delays from building up over time and slowing down the playback of recordings.
172However, it does mean that when you expect to wait for an indeterminate period of time, you should
173send `updateTimeBase` afterwards to prevent following events being scheduled in the past — see that
174command's section for an example.
175
176| Field         | Type          | Description                |
177|:-------------:|:-------------:|:-------------------------- |
178| `id`          | integer       | Device ID                  |
179| `command`     | string        | Must be set to "delay"     |
180| `duration`    | integer       | Delay in milliseconds      |
181
182Example:
183
184```json5
185{
186  "id": 1,
187  "command": "delay",
188  "duration": 10
189}
190```
191
192#### `updateTimeBase`
193
194Update the time base from which the following events are scheduled to the current time. When
195controlling `uinput` over standard input, you should send this command if you want following events
196to be scheduled relative to now, rather than the last injection. See the following example set of
197commands and the times they will be scheduled to run at:
198
1991. `register` (say this occurs at time _X_)
2002. `delay` 500ms
2013. `inject`: scheduled for _X_+500ms
2024. `delay` 10ms
2035. `inject`: scheduled for _X_+510ms
2046. (wait a few seconds)
2057. `updateTimeBase` (say this occurs at time _Y_)
2068. `delay` 10ms
2079. `inject`: scheduled for _Y_+10ms
208
209Without the `updateTimeBase` command, the final injection would be scheduled for _X_+520ms, which
210would be in the past.
211
212This is useful if you are issuing commands in multiple stages with long or unknown delays in between
213them. For example, say you have a test that does the following:
214
2151. `register` a device
2162. `inject` a few events that should launch an app
2173. Wait for the app to launch (an indeterminate amount of time, possibly seconds)
2184. 1000 `inject` commands separated by `delay` commands of 10ms
219
220Without `updateTimeBase`, the `inject` commands of step 4 will be scheduled to start immediately
221after the events from step 2. That time is probably in the past, so many of the 1000 injections will
222be sent immediately. This will likely fill the kernel's event buffers, causing events to be dropped.
223Sending `updateTimeBase` before the `inject` commands in step 4 will schedule them relative to the
224current time, meaning that they will be all injected with the intended 10ms delays between them.
225
226| Field         | Type          | Description                     |
227|:-------------:|:-------------:|:------------------------------- |
228| `id`          | integer       | Device ID                       |
229| `command`     | string        | Must be set to "updateTimeBase" |
230
231#### `inject`
232
233Send an array of uinput event packets to the uinput device
234
235| Field         |         Type          | Description                |
236|:-------------:|:---------------------:|:-------------------------- |
237| `id`          |        integer        | Device ID                  |
238| `command`     |        string         | Must be set to "inject"    |
239| `events`      | integer\|string array | events to inject           |
240
241The `events` parameter is an array of integers in sets of three: a type, an axis code, and an axis
242value, like you'd find in Linux's `struct input_event`. For example, sending presses of the 0 and 1
243keys would look like this:
244
245```json5
246{
247  "id": 1,
248  "command": "inject",
249  "events": ["EV_KEY", "KEY_0", 1,
250             "EV_SYN", "SYN_REPORT", 0,
251             "EV_KEY", "KEY_0", 0,
252             "EV_SYN", "SYN_REPORT", 0,
253             "EV_KEY", "KEY_1", 1,
254             "EV_SYN", "SYN_REPORT", 0,
255             "EV_KEY", "KEY_1", 0,
256             "EV_SYN", "SYN_REPORT", 0
257            ]
258}
259```
260
261#### `sync`
262
263A command used to get a response once the command is processed. When several `inject` and `delay`
264commands are used in a row, the `sync` command can be used to track the progress of the command
265queue.
266
267|    Field    |  Type   | Description                                  |
268|:-----------:|:-------:|:---------------------------------------------|
269|    `id`     | integer | Device ID                                    |
270|  `command`  | string  | Must be set to "sync"                        |
271| `syncToken` | string  | The token used to identify this sync command |
272
273Example:
274
275```json5
276{
277  "id": 1,
278  "command": "syncToken",
279  "syncToken": "finished_injecting_events"
280}
281```
282
283This command will result in the following response when it is processed:
284
285```json5
286{
287  "id": 1,
288  "result": "sync",
289  "syncToken": "finished_injecting_events"
290}
291```
292
293## Notes
294
295The `getevent` utility can used to print out the key events for debugging purposes.
296