1.. _tools: 2 3============================================================================== 4Helper tools 5============================================================================== 6 7libinput provides a ``libinput`` tool to query state and events. This tool 8takes a subcommand as argument, similar to the **git** command. A full 9explanation of the various commands available in the libinput tool is 10available in the **libinput(1)** man page. 11 12The 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 31Most 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------------------------------------------------------------------------------ 37libinput list-devices 38------------------------------------------------------------------------------ 39 40The ``libinput list-devices`` command shows information about devices 41recognized by libinput and can help identifying why a device behaves 42different than expected. For example, if a device does not show up in the 43output, 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 69The 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 73default configuration for this device, for options that have more than a 74binary state all available options are listed, with the default one prefixed 75with an asterisk (``*``). In the example above, the default click method is 76button-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------------------------------------------------------------------------------ 84libinput list-kernel-devices 85------------------------------------------------------------------------------ 86 87The ``libinput list-kernel-devices`` command shows the devices known by **the 88kernel**. This command can help identify issues when a device is not handled by 89libinput. 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 102In some cases, knowing about the HID devices behind the kernel's event nodes 103can 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------------------------------------------------------------------------------ 133libinput debug-events 134------------------------------------------------------------------------------ 135The ``libinput debug-events`` command prints events from devices and can help 136to identify why a device behaves different than expected. :: 137 138 $ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger 139 140All configuration options (enable/disable tapping, 141etc.) are available as commandline arguments. To reproduce the event 142sequence as your desktop session sees it, ensure that all options are turned 143on 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 149An 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------------------------------------------------------------------------------ 183libinput debug-gui 184------------------------------------------------------------------------------ 185 186A simple GTK-based graphical tool that shows the behavior and location of 187touch events, pointer motion, scroll axes and gestures. Since this tool 188gathers data directly from libinput, it is thus suitable for 189pointer-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 199As with :ref:`libinput-debug-events`, all options must be specified on the 200commandline to emulate the correct behavior. 201See the **libinput-debug-gui(1)** man page or the ``--help`` output for information about 202the available options. 203 204.. _libinput-record: 205 206------------------------------------------------------------------------------ 207libinput record and libinput replay 208------------------------------------------------------------------------------ 209 210.. note:: For libinput versions 1.10 and older, use :ref:`evemu`. 211 212The ``libinput record`` command records the **kernel** events from a specific 213device node. The recorded sequence can be replayed with the ``libinput 214replay`` command. This pair of tools is crucial to capturing bugs and 215reproducing them on a developer's machine. 216 217.. graphviz:: libinput-record.gv 218 :align: center 219 220The recorded events are **kernel events** and independent of the 221libinput context. libinput does not need to be running, it does 222not matter whether a user is running X.Org or Wayland or even what 223version of libinput is currently running. 224 225The use of the tools is straightforward, just run without arguments, piping 226the 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 252Without arguments, ``libinput record`` displays the available devices and lets 253the user select one. Supply the number (17 in this case for 254``/dev/input/event17``) and the tool will print the device information and 255events to the file it is redirected to. More arguments are available, see 256the **libinput-record(1)** man page. 257 258.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or 259 ``tmux``. 260 261Reproduce the bug, ctrl+c and attach the output file to a bug report. 262For data protection, ``libinput record`` obscures key codes by default, any 263alphanumeric 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 269The 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 277the log file. Hitting enter replays the event sequence once and the tool 278stops once all events have been replayed. Hitting enter again replays the 279sequence again, Ctrl+C stops it and removes the virtual device. 280 281Users are advised to always replay a recorded event sequence to ensure they 282have captured the bug. 283 284More arguments are available, see the **libinput-record(1)** and 285**libinput-replay(1)** man pages. 286 287.. _libinput-record-autorestart: 288 289.............................................................................. 290libinput record's autorestart feature 291.............................................................................. 292 293``libinput record`` often collects thousands of events per minute. However, 294the output of ``libinput record`` usually needs to be visually inspected 295or replayed in realtime on a developer machine. It is thus imperative that 296the event log is kept as short as possible. 297 298For bugs that are difficult to reproduce use 299``libinput record --autorestart=2 --output-file=recording.yml``. 300All events will be recorded to a file named 301``recording.yml.<current-date-and-time>`` and whenever the device does not 302send events for 2 seconds, a new file is created. This helps to keep 303individual recordings short. 304 305To 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 316If you have to use the recorded device to stop ``libinput record`` (e.g. to 317switch windows), remember that this will cause a new recording to be 318created. Thus, attach the **second-to-last recording** to the bug report 319because this one contains the bug trigger. 320 321.. _libinput-record-multiple: 322 323.............................................................................. 324Recording multiple devices at once 325.............................................................................. 326 327In some cases, an interaction between multiple devices is the cause for a 328specific bug. For example, a touchpad may not work in response to keyboard 329events. To accurately reproduce this sequence, the timing between multiple 330devices 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 333once. 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 338As seen above, a user must specify ``--multiple`` and the ``--output-file``. 339Finally, all devices to be recorded must be specified on the commandline as 340well. 341 342Replaying events is the same as for a single recording: :: 343 344 $ sudo libinput replay touchpad-bug.yml 345 346.. _libinput-measure: 347 348------------------------------------------------------------------------------ 349Measuring device properties with libinput measure 350------------------------------------------------------------------------------ 351 352The ``libinput measure`` tool is a multiplexer for various sub-tools that can 353measure specific properties on the device. These tools generally measure one 354thing and one thing only and their usage is highly specific to the tool. 355Please see the **libinput-measure(1)** man page for information about what 356tools are available and the man page for each respective tool. 357 358.. _libinput-analyze: 359 360------------------------------------------------------------------------------ 361Analyzing device events with libinput analyze 362------------------------------------------------------------------------------ 363 364The ``libinput analyze`` tool is a multiplexer for various sub-tools that 365can analyze input events previously recorded from a device. 366 367Please see the **libinput-analyze(1)** man page for information about what 368tools are available and the man page for each respective too. 369 370 371.. _libinput-quirks: 372 373------------------------------------------------------------------------------ 374Listing quirks assigned to a device 375------------------------------------------------------------------------------ 376 377The ``libinput quirks`` tool can show quirks applied for any given device. :: 378 379 $ libinput quirks list /dev/input/event0 380 AttrLidSwitchReliability=unreliable 381 382If the tool's output is empty, no quirk is applied. See :ref:`device-quirks` 383for more information. 384