Debian Codegraph @

doc/user/tools.rst

raw
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.