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