| 1 |
.. _tools: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Helper tools |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
libinput provides a ``libinput`` tool to query state and events. This tool |
| 8 |
takes a subcommand as argument, similar to the **git** command. A full |
| 9 |
explanation of the various commands available in the libinput tool is |
| 10 |
available in the **libinput(1)** man page. |
| 11 |
|
| 12 |
The most common tools used are: |
| 13 |
|
| 14 |
- ``libinput list-devices``: to list locally available devices as seen by libinput, |
| 15 |
see :ref:`here <libinput-list-devices>` |
| 16 |
- ``libinput list-kernel-devices``: to list locally available devices as seen by the kernel, |
| 17 |
see :ref:`here <libinput-list-kernel-devices>` |
| 18 |
- ``libinput debug-events``: to monitor and debug events, |
| 19 |
see :ref:`here <libinput-debug-events>` |
| 20 |
- ``libinput debug-gui``: to visualize events, |
| 21 |
see :ref:`here <libinput-debug-gui>` |
| 22 |
- ``libinput record``: to record an event sequence for replaying, |
| 23 |
see :ref:`here <libinput-record>` |
| 24 |
- ``libinput measure``: measure properties on a kernel device, |
| 25 |
see :ref:`here <libinput-measure>` |
| 26 |
- ``libinput analyze``: analyse event recordings from a kernel device, |
| 27 |
see :ref:`here <libinput-analyze>` |
| 28 |
- ``libinput quirks``: show quirks assigned to a device, see |
| 29 |
:ref:`here <libinput-quirks>` |
| 30 |
|
| 31 |
Most of the tools must be run as root to have access to the kernel's |
| 32 |
``/dev/input/event*`` device files. |
| 33 |
|
| 34 |
.. _libinput-list-devices: |
| 35 |
|
| 36 |
------------------------------------------------------------------------------ |
| 37 |
libinput list-devices |
| 38 |
------------------------------------------------------------------------------ |
| 39 |
|
| 40 |
The ``libinput list-devices`` command shows information about devices |
| 41 |
recognized by libinput and can help identifying why a device behaves |
| 42 |
different than expected. For example, if a device does not show up in the |
| 43 |
output, it is not a supported input device. |
| 44 |
|
| 45 |
.. note:: This tool does **not** show your desktop's configuration, just the |
| 46 |
libinput built-in defaults. |
| 47 |
|
| 48 |
:: |
| 49 |
|
| 50 |
$ sudo libinput list-devices |
| 51 |
[...] |
| 52 |
Device: SynPS/2 Synaptics TouchPad |
| 53 |
Kernel: /dev/input/event4 |
| 54 |
Group: 9 |
| 55 |
Seat: seat0, default |
| 56 |
Size: 97.33x66.86mm |
| 57 |
Capabilities: pointer |
| 58 |
Tap-to-click: disabled |
| 59 |
Tap drag lock: disabled |
| 60 |
Left-handed: disabled |
| 61 |
Nat.scrolling: disabled |
| 62 |
Middle emulation: n/a |
| 63 |
Calibration: n/a |
| 64 |
Scroll methods: *two-finger |
| 65 |
Click methods: *button-areas clickfinger |
| 66 |
[...] |
| 67 |
|
| 68 |
|
| 69 |
The above listing shows example output for a touchpad. The |
| 70 |
``libinput list-devices`` command lists general information about the device |
| 71 |
(the kernel event node) but also the configuration options. If an option is |
| 72 |
``n/a`` it does not exist on this device. Otherwise, the tool will show the |
| 73 |
default configuration for this device, for options that have more than a |
| 74 |
binary state all available options are listed, with the default one prefixed |
| 75 |
with an asterisk (``*``). In the example above, the default click method is |
| 76 |
button-areas but clickfinger is available. |
| 77 |
|
| 78 |
.. note:: This tool is intended for human-consumption and may change its output |
| 79 |
at any time. |
| 80 |
|
| 81 |
.. _libinput-list-kernel-devices: |
| 82 |
|
| 83 |
------------------------------------------------------------------------------ |
| 84 |
libinput list-kernel-devices |
| 85 |
------------------------------------------------------------------------------ |
| 86 |
|
| 87 |
The ``libinput list-kernel-devices`` command shows the devices known by **the |
| 88 |
kernel**. This command can help identify issues when a device is not handled by |
| 89 |
libinput. |
| 90 |
|
| 91 |
:: |
| 92 |
|
| 93 |
$ libinput list-kernel-devices |
| 94 |
/dev/input/event0: Sleep Button |
| 95 |
/dev/input/event1: Power Button |
| 96 |
/dev/input/event2: Power Button |
| 97 |
/dev/input/event3: Microsoft Microsoft® 2.4GHz Transceiver v9.0 |
| 98 |
/dev/input/event4: Microsoft Microsoft® 2.4GHz Transceiver v9.0 Mouse |
| 99 |
[...] |
| 100 |
|
| 101 |
|
| 102 |
In some cases, knowing about the HID devices behind the kernel's event nodes |
| 103 |
can be useful. To list HID devices, supply the ``--hid`` commandline flag: |
| 104 |
|
| 105 |
:: |
| 106 |
|
| 107 |
$ libinput list-kernel-devices --hid |
| 108 |
hid: |
| 109 |
- name: 'Logitech Gaming Mouse G303' |
| 110 |
id: '046d:c080' |
| 111 |
driver: 'hid-generic' |
| 112 |
hidraw: ['/dev/hidraw6'] |
| 113 |
evdev: ['/dev/input/event13'] |
| 114 |
|
| 115 |
- name: 'Logitech Gaming Mouse G303' |
| 116 |
id: '046d:c080' |
| 117 |
driver: 'hid-generic' |
| 118 |
hidraw: ['/dev/hidraw7'] |
| 119 |
evdev: ['/dev/input/event14'] |
| 120 |
|
| 121 |
- name: 'Microsoft Microsoft® 2.4GHz Transceiver v9.0' |
| 122 |
id: '045e:07a5' |
| 123 |
driver: 'hid-generic' |
| 124 |
hidraw: ['/dev/hidraw0'] |
| 125 |
evdev: ['/dev/input/event3'] |
| 126 |
|
| 127 |
.. note:: This tool is intended for human-consumption and may change its output |
| 128 |
at any time. |
| 129 |
|
| 130 |
.. _libinput-debug-events: |
| 131 |
|
| 132 |
------------------------------------------------------------------------------ |
| 133 |
libinput debug-events |
| 134 |
------------------------------------------------------------------------------ |
| 135 |
The ``libinput debug-events`` command prints events from devices and can help |
| 136 |
to identify why a device behaves different than expected. :: |
| 137 |
|
| 138 |
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger |
| 139 |
|
| 140 |
All configuration options (enable/disable tapping, |
| 141 |
etc.) are available as commandline arguments. To reproduce the event |
| 142 |
sequence as your desktop session sees it, ensure that all options are turned |
| 143 |
on or off as required. See the **libinput-debug-events(1)** man page or the |
| 144 |
``--help`` output for information about the available options. |
| 145 |
|
| 146 |
.. note:: When submitting a bug report, always use the ``--verbose`` flag to get |
| 147 |
additional information: ``libinput debug-events --verbose <other options>`` |
| 148 |
|
| 149 |
An example output from this tool may look like the snippet below. :: |
| 150 |
|
| 151 |
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger |
| 152 |
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k |
| 153 |
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k |
| 154 |
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S |
| 155 |
-event1 DEVICE_ADDED Sleep Button seat0 default group4 cap:k |
| 156 |
-event4 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=3 seat0 default group5 cap: |
| 157 |
-event11 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=7 seat0 default group6 cap: |
| 158 |
-event12 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=8 seat0 default group7 cap: |
| 159 |
-event13 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=9 seat0 default group8 cap: |
| 160 |
-event14 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=10 seat0 default group9 cap: |
| 161 |
-event19 DEVICE_ADDED Integrated Camera: Integrated C seat0 default group10 cap:k |
| 162 |
-event15 DEVICE_ADDED HDA Intel PCH Dock Mic seat0 default group11 cap: |
| 163 |
-event16 DEVICE_ADDED HDA Intel PCH Mic seat0 default group12 cap: |
| 164 |
-event17 DEVICE_ADDED HDA Intel PCH Dock Headphone seat0 default group13 cap: |
| 165 |
-event18 DEVICE_ADDED HDA Intel PCH Headphone seat0 default group14 cap: |
| 166 |
-event6 DEVICE_ADDED ELAN Touchscreen seat0 default group15 cap:t size 305x172mm ntouches 10 calib |
| 167 |
-event3 DEVICE_ADDED AT Translated Set 2 keyboard seat0 default group16 cap:k |
| 168 |
-event20 DEVICE_ADDED SynPS/2 Synaptics TouchPad seat0 default group17 cap:pg size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on |
| 169 |
-event21 DEVICE_ADDED TPPS/2 IBM TrackPoint seat0 default group18 cap:p left scroll-nat scroll-button |
| 170 |
-event7 DEVICE_ADDED ThinkPad Extra Buttons seat0 default group19 cap:k |
| 171 |
-event20 POINTER_MOTION +3.62s 2.72/ -0.93 |
| 172 |
event20 POINTER_MOTION +3.63s 1.80/ -1.42 |
| 173 |
event20 POINTER_MOTION +3.65s 6.16/ -2.28 |
| 174 |
event20 POINTER_MOTION +3.66s 6.42/ -1.99 |
| 175 |
event20 POINTER_MOTION +3.67s 8.99/ -1.42 |
| 176 |
event20 POINTER_MOTION +3.68s 11.30/ 0.00 |
| 177 |
event20 POINTER_MOTION +3.69s 21.32/ 1.42 |
| 178 |
|
| 179 |
|
| 180 |
.. _libinput-debug-gui: |
| 181 |
|
| 182 |
------------------------------------------------------------------------------ |
| 183 |
libinput debug-gui |
| 184 |
------------------------------------------------------------------------------ |
| 185 |
|
| 186 |
A simple GTK-based graphical tool that shows the behavior and location of |
| 187 |
touch events, pointer motion, scroll axes and gestures. Since this tool |
| 188 |
gathers data directly from libinput, it is thus suitable for |
| 189 |
pointer-acceleration testing. |
| 190 |
|
| 191 |
.. note:: This tool does **not** use your desktop's configuration, just the |
| 192 |
libinput built-in defaults. |
| 193 |
|
| 194 |
:: |
| 195 |
|
| 196 |
$ sudo libinput debug-gui --enable-tapping |
| 197 |
|
| 198 |
|
| 199 |
As with :ref:`libinput-debug-events`, all options must be specified on the |
| 200 |
commandline to emulate the correct behavior. |
| 201 |
See the **libinput-debug-gui(1)** man page or the ``--help`` output for information about |
| 202 |
the available options. |
| 203 |
|
| 204 |
.. _libinput-record: |
| 205 |
|
| 206 |
------------------------------------------------------------------------------ |
| 207 |
libinput record and libinput replay |
| 208 |
------------------------------------------------------------------------------ |
| 209 |
|
| 210 |
.. note:: For libinput versions 1.10 and older, use :ref:`evemu`. |
| 211 |
|
| 212 |
The ``libinput record`` command records the **kernel** events from a specific |
| 213 |
device node. The recorded sequence can be replayed with the ``libinput |
| 214 |
replay`` command. This pair of tools is crucial to capturing bugs and |
| 215 |
reproducing them on a developer's machine. |
| 216 |
|
| 217 |
.. graphviz:: libinput-record.gv |
| 218 |
:align: center |
| 219 |
|
| 220 |
The recorded events are **kernel events** and independent of the |
| 221 |
libinput context. libinput does not need to be running, it does |
| 222 |
not matter whether a user is running X.Org or Wayland or even what |
| 223 |
version of libinput is currently running. |
| 224 |
|
| 225 |
The use of the tools is straightforward, just run without arguments, piping |
| 226 |
the output into a file: :: |
| 227 |
|
| 228 |
$ sudo libinput record > touchpad.yml |
| 229 |
Available devices: |
| 230 |
/dev/input/event0: Lid Switch |
| 231 |
/dev/input/event1: Sleep Button |
| 232 |
/dev/input/event2: Power Button |
| 233 |
/dev/input/event3: AT Translated Set 2 keyboard |
| 234 |
/dev/input/event4: ThinkPad Extra Buttons |
| 235 |
/dev/input/event5: ELAN Touchscreen |
| 236 |
/dev/input/event6: Video Bus |
| 237 |
/dev/input/event7: HDA Intel HDMI HDMI/DP,pcm=3 |
| 238 |
/dev/input/event8: HDA Intel HDMI HDMI/DP,pcm=7 |
| 239 |
/dev/input/event9: HDA Intel HDMI HDMI/DP,pcm=8 |
| 240 |
/dev/input/event10: HDA Intel HDMI HDMI/DP,pcm=9 |
| 241 |
/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=10 |
| 242 |
/dev/input/event12: HDA Intel PCH Dock Mic |
| 243 |
/dev/input/event13: HDA Intel PCH Mic |
| 244 |
/dev/input/event14: HDA Intel PCH Dock Headphone |
| 245 |
/dev/input/event15: HDA Intel PCH Headphone |
| 246 |
/dev/input/event16: Integrated Camera: Integrated C |
| 247 |
/dev/input/event17: SynPS/2 Synaptics TouchPad |
| 248 |
/dev/input/event18: TPPS/2 IBM TrackPoint |
| 249 |
Select the device event number: 17 |
| 250 |
/dev/input/event17 recording to stdout |
| 251 |
|
| 252 |
Without arguments, ``libinput record`` displays the available devices and lets |
| 253 |
the user select one. Supply the number (17 in this case for |
| 254 |
``/dev/input/event17``) and the tool will print the device information and |
| 255 |
events to the file it is redirected to. More arguments are available, see |
| 256 |
the **libinput-record(1)** man page. |
| 257 |
|
| 258 |
.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or |
| 259 |
``tmux``. |
| 260 |
|
| 261 |
Reproduce the bug, ctrl+c and attach the output file to a bug report. |
| 262 |
For data protection, ``libinput record`` obscures key codes by default, any |
| 263 |
alphanumeric key shows up as letter "a". |
| 264 |
|
| 265 |
.. warning:: The longer the recording, the harder it is to identify the event |
| 266 |
sequence triggering the bug. Please keep the event sequence as |
| 267 |
short as possible. |
| 268 |
|
| 269 |
The recording can be replayed with the ``libinput replay`` command: :: |
| 270 |
|
| 271 |
$ sudo libinput replay touchpad.yml |
| 272 |
SynPS/2 Synaptics TouchPad: /dev/input/event19 |
| 273 |
Hit enter to start replaying |
| 274 |
|
| 275 |
|
| 276 |
``libinput replay`` creates a new virtual device based on the description in |
| 277 |
the log file. Hitting enter replays the event sequence once and the tool |
| 278 |
stops once all events have been replayed. Hitting enter again replays the |
| 279 |
sequence again, Ctrl+C stops it and removes the virtual device. |
| 280 |
|
| 281 |
Users are advised to always replay a recorded event sequence to ensure they |
| 282 |
have captured the bug. |
| 283 |
|
| 284 |
More arguments are available, see the **libinput-record(1)** and |
| 285 |
**libinput-replay(1)** man pages. |
| 286 |
|
| 287 |
.. _libinput-record-autorestart: |
| 288 |
|
| 289 |
.............................................................................. |
| 290 |
libinput record's autorestart feature |
| 291 |
.............................................................................. |
| 292 |
|
| 293 |
``libinput record`` often collects thousands of events per minute. However, |
| 294 |
the output of ``libinput record`` usually needs to be visually inspected |
| 295 |
or replayed in realtime on a developer machine. It is thus imperative that |
| 296 |
the event log is kept as short as possible. |
| 297 |
|
| 298 |
For bugs that are difficult to reproduce use |
| 299 |
``libinput record --autorestart=2 --output-file=recording.yml``. |
| 300 |
All events will be recorded to a file named |
| 301 |
``recording.yml.<current-date-and-time>`` and whenever the device does not |
| 302 |
send events for 2 seconds, a new file is created. This helps to keep |
| 303 |
individual recordings short. |
| 304 |
|
| 305 |
To use the ``--autorestart`` option correctly: |
| 306 |
|
| 307 |
- run ``libinput record --autorestart=2 --output-file=<somefilename>.yml``. |
| 308 |
You may provide a timeout other than 2 if needed. |
| 309 |
- use the device to reproduce the bug, pausing frequently for 2s and longer |
| 310 |
to rotate the logs |
| 311 |
- when the bug triggers, **immediately stop using the device** and wait |
| 312 |
several seconds for the log to rotate |
| 313 |
- Ctrl+C the ``libinput record`` process without using the device |
| 314 |
again. Attach the **last recording** to the bug report. |
| 315 |
|
| 316 |
If you have to use the recorded device to stop ``libinput record`` (e.g. to |
| 317 |
switch windows), remember that this will cause a new recording to be |
| 318 |
created. Thus, attach the **second-to-last recording** to the bug report |
| 319 |
because this one contains the bug trigger. |
| 320 |
|
| 321 |
.. _libinput-record-multiple: |
| 322 |
|
| 323 |
.............................................................................. |
| 324 |
Recording multiple devices at once |
| 325 |
.............................................................................. |
| 326 |
|
| 327 |
In some cases, an interaction between multiple devices is the cause for a |
| 328 |
specific bug. For example, a touchpad may not work in response to keyboard |
| 329 |
events. To accurately reproduce this sequence, the timing between multiple |
| 330 |
devices must be correct and we need to record the events in one go. |
| 331 |
|
| 332 |
``libinput record`` has a ``--multiple`` argument to record multiple devices at |
| 333 |
once. Unlike the normal invocation, this one requires a number of arguments: :: |
| 334 |
|
| 335 |
$ sudo libinput record --multiple --output-file=touchpad-bug.yml /dev/input/event17 /dev/input/event3 |
| 336 |
recording to 'touchpad-bug.yml' |
| 337 |
|
| 338 |
As seen above, a user must specify ``--multiple`` and the ``--output-file``. |
| 339 |
Finally, all devices to be recorded must be specified on the commandline as |
| 340 |
well. |
| 341 |
|
| 342 |
Replaying events is the same as for a single recording: :: |
| 343 |
|
| 344 |
$ sudo libinput replay touchpad-bug.yml |
| 345 |
|
| 346 |
.. _libinput-measure: |
| 347 |
|
| 348 |
------------------------------------------------------------------------------ |
| 349 |
Measuring device properties with libinput measure |
| 350 |
------------------------------------------------------------------------------ |
| 351 |
|
| 352 |
The ``libinput measure`` tool is a multiplexer for various sub-tools that can |
| 353 |
measure specific properties on the device. These tools generally measure one |
| 354 |
thing and one thing only and their usage is highly specific to the tool. |
| 355 |
Please see the **libinput-measure(1)** man page for information about what |
| 356 |
tools are available and the man page for each respective tool. |
| 357 |
|
| 358 |
.. _libinput-analyze: |
| 359 |
|
| 360 |
------------------------------------------------------------------------------ |
| 361 |
Analyzing device events with libinput analyze |
| 362 |
------------------------------------------------------------------------------ |
| 363 |
|
| 364 |
The ``libinput analyze`` tool is a multiplexer for various sub-tools that |
| 365 |
can analyze input events previously recorded from a device. |
| 366 |
|
| 367 |
Please see the **libinput-analyze(1)** man page for information about what |
| 368 |
tools are available and the man page for each respective too. |
| 369 |
|
| 370 |
|
| 371 |
.. _libinput-quirks: |
| 372 |
|
| 373 |
------------------------------------------------------------------------------ |
| 374 |
Listing quirks assigned to a device |
| 375 |
------------------------------------------------------------------------------ |
| 376 |
|
| 377 |
The ``libinput quirks`` tool can show quirks applied for any given device. :: |
| 378 |
|
| 379 |
$ libinput quirks list /dev/input/event0 |
| 380 |
AttrLidSwitchReliability=unreliable |
| 381 |
|
| 382 |
If the tool's output is empty, no quirk is applied. See :ref:`device-quirks` |
| 383 |
for more information. |