Debian Codegraph @

doc/user/lua-plugins.rst

raw
1 .. _lua_plugins:
2
3 ==============================================================================
4 Lua Plugins
5 ==============================================================================
6
7 libinput provides a plugin system that allows users to modify the behavior
8 of devices. For example, a plugin may add or remove axes and/or buttons on a
9 device and/or modify the event stream seen by this device before it is passed
10 to libinput.
11
12 Plugins are implemented in `Lua <https://www.lua.org/>`_ (version 5.4)
13 and are typically loaded from the following paths:
14
15 - ``/etc/libinput/plugins/*.lua``, and
16 - ``/usr/lib{64}/libinput/plugins/*.lua``
17
18 Plugins are loaded in alphabetical order and where
19 multiple plugins share the same file name, the one in the highest precedence
20 directory is used. Plugins in ``/etc`` take precedence over
21 plugins in ``/usr``.
22
23 .. note:: Plugins lookup paths and their order are decided by the compositor.
24 Some compositors may support more/fewer/other lookup paths than the
25 above defaults.
26
27 Plugins are run sequentially in ascending sort-order (i.e. ``00-foo.lua`` runs
28 before ``10-bar.lua``) and each plugin sees the state left by any previous
29 plugins. For example if ``00-foo.lua`` changes all left button events to right
30 button events, ``10-bar.lua`` only ever sees right button events.
31
32 See the `Lua Reference manual <https://www.lua.org/manual/5.4/manual.html>`_ for
33 details on the Lua language.
34
35 .. note:: Plugins are **not** loaded by default, it is up to the compositor
36 whether to allow plugins. An explicit call to
37 ``libinput_plugin_system_load_plugins()`` is required.
38
39 ------------------------------------------------------------------------------
40 Limitations
41 ------------------------------------------------------------------------------
42
43 Each script runs in its own sandbox and cannot communicate or share state with
44 other scripts.
45
46 Tables that hold API methods are not writable, i.e. it is not possible
47 to overwrite the default functionality of those APIs.
48
49 The Lua API available to plugins is limited to the following calls::
50
51 assert error ipairs next pairs tonumber
52 pcall select print tostring type xpcall
53 table string math _VERSION
54
55 It is not possible to e.g. use the ``io`` module from a script.
56
57 To use methods on instantiated objects, the ``object:method`` method call
58 syntax must be used. For example:
59
60 .. code-block:: lua
61
62 libinput:register()
63 libinput.register() -- this will fail
64
65 ------------------------------------------------------------------------------
66 When to use plugins
67 ------------------------------------------------------------------------------
68
69 libinput plugins are a relatively niche use-case that typically need to
70 address either once-off issues (e.g. those caused by worn-out hardware) or
71 user preferences that libinput does not and will not cater for.
72
73 Plugins should not be used for issues that can be fixed generically, for
74 example via :ref:`device-quirks`.
75
76 As a rule of thumb: a plugin should be a once-off that only works for one
77 user's hardware. If a plugin can be shared with many users then the plugin
78 implements functionality that should be integrated into libinput proper.
79
80 ------------------------------------------------------------------------------
81 Testing plugins
82 ------------------------------------------------------------------------------
83
84 Our :ref:`tools` support plugins if passed the ``--enable-plugins`` commandline
85 option. For implementing and testing plugins the easiest commands to test are
86
87 - ``libinput debug-events --enable-plugins`` (see :ref:`libinput-debug-events` docs)
88 - ``libinput debug-gui --enable-plugins`` (see :ref:`libinput-debug-gui` docs)
89
90 Where libinput is built and run from git, the tools will also look for plugins
91 in the meson build directory. See the ``plugins/meson.build`` file for details.
92
93 .. _plugins_api_lua:
94
95 --------------------------------------------------------------------------------
96 Lua Plugin API
97 --------------------------------------------------------------------------------
98
99 Lua plugins sit effectively below libinput and the API is not a
100 representation of the libinput API. Plugins modify the evdev event stream
101 received from the kernel.
102
103 .. graphviz:: plugin-stack.gv
104
105 The API revolves around two types: ``libinput`` and ``EvdevDevice``. The
106 ``libinput`` type is used to register a plugin from a script, the
107 ``EvdevDevice`` represents one device that is present in the system (but may
108 not have yet been added by libinput).
109
110 Typically a script does the following steps:
111
112 - register with libinput via ``libinput:register({versions})``
113 - connect to the ``"new-evdev-device"`` event
114 - receive an ``EvdevDevice`` object in the ``"new-evdev-device"`` callback
115
116 - check and/or modify the evdev event codes on the device
117 - connect to the device's ``"evdev-frame"`` event
118
119 - receive an :ref:`evdev frame <plugins_api_evdev_frame>` in the device's
120 ``"evdev-frame"`` callback
121
122 - check and/or modify the events in that frame
123
124 Where multiple plugins are active, the evdev frame passed to the callback is
125 the combined frame as processed by all previous plugins in ascending sort order.
126 For example, if one plugin discards all button events subsequent plugins will
127 never see those button events in the frame.
128
129 .. _plugins_api_version_stability:
130
131 ..............................................................................
132 Plugin version stability
133 ..............................................................................
134
135 Plugin API version stability is provided on a best effort basis. We aim to provide
136 stable plugin versions for as long as feasible but may need to retire some older
137 versions over time. For this reason a plugin can select multiple versions it
138 implements, libinput will pick one supported version and adjust the plugin
139 behavior to match that version. See the ``libinput:register()`` call for details.
140
141 --------------------------------------------------------------------------------
142 Lua Plugin API Reference
143 --------------------------------------------------------------------------------
144
145
146 libinput provides the following globals and types:
147
148 .. _plugins_api_evdev_usage:
149
150 ................................................................................
151 Evdev Usages
152 ................................................................................
153
154 Evdev usages are a libinput-specific wrapper around the ``linux/input-event-codes.h``
155 evdev types and codes. They are used by libinput internally and are a 32-bit
156 combination of ``type << 16 | code``. Each usage carries the type and code and
157 is thus simpler to pass around and less prone to type confusion.
158
159 The :ref:`evdev global <plugins_api_evdev_global>` attempts to provide all
160 available usages but for the niche cases where it does not provide a named constant
161 the value can be crafted manually:
162
163 .. code-block:: lua
164
165 evdev_type = 0x3 -- EV_REL
166 evdev_code = 0x1 -- REL_Y
167 evdev_usage = (evdev_type << 16) | evdev_code
168
169 assert(usage == evdev.REL_Y)
170
171 .. _plugins_api_evdev_global:
172
173 ................................................................................
174 The ``evdev`` global
175 ................................................................................
176
177 The ``evdev`` global represents all known :ref:`plugins_api_evdev_usage`,
178 effectively in the form:
179
180 .. code-block:: lua
181
182 evdev = {
183 ABS_X = (3 << 16) | 0,
184 ABS_Y = (3 << 16) | 1,
185 ...
186 REL_X = (2 << 16) | 0,
187 REL_Y = (2 << 16) | 1,
188 ...
189 }
190
191
192 This global is provided for convenience to improve readability in the code.
193 Note that the name uses the event code name only (e.g. ``evdev.ABS_Y``) but the
194 value is an :ref:`Evdev Usage <plugins_api_evdev_usage>` (type and code).
195
196 See the ``linux/input-event-codes.h`` header file provided by your kernel
197 for a list of all evdev types and codes.
198
199 The evdev global also provides the bus type constants, e.g. ``evdev.BUS_USB``.
200 See the ``linux/input.h`` header file provided by your kernel
201 for a list of bus types.
202
203
204 .. _plugins_api_evdev_frame:
205
206 ................................................................................
207 Evdev frames
208 ................................................................................
209
210 Evdev frames represent a single frame of evdev events for a device. A frame
211 is a group of events that occurred at the same time. The frame usually only
212 contains state that has changed compared to the previous frame.
213
214 In our API a frame is exposed as a nested table with the following structure:
215
216 .. code-block:: lua
217
218 frame1 = {
219 { usage = evdev.ABS_X, value = 123 },
220 { usage = evdev.ABS_Y, value = 456 },
221 { usage = evdev.BTN_LEFT, value = 1 },
222 }
223 frame2 = {
224 { usage = evdev.ABS_Y, value = 457 },
225 }
226 frame3 = {
227 { usage = evdev.ABS_X, value = 124 },
228 { usage = evdev.BTN_LEFT, value = 0 },
229 }
230
231 .. note:: This API does not use ``SYN_REPORT`` events, it is implied at the
232 end of the table. Where a plugin writes a ``SYN_REPORT`` into the
233 list of events, that ``SYN_REPORT`` terminates the event frame
234 (similar to writing a ``\0`` into the middle of a C string).
235 A frame containing only a ``SYN_REPORT`` is functionally equivalent
236 to an empty frame.
237
238 Events or frames do not have a timestamp. Where a timestamp is required, that
239 timestamp is passed as additional argument to the function or return value.
240
241 See :ref:`plugins_api_evdev_global` for a list of known usages.
242
243 .. warning:: Evdev frames have an implementation-defined size limit of how many
244 events can be added to a single frame. This limit should never be
245 hit by valid plugins.
246
247 .. _plugins_api_libinputglobal:
248
249 ................................................................................
250 The ``libinput`` global object
251 ................................................................................
252
253 The core of our plugin API is the ``libinput`` global object. A script must
254 immediately ``register()`` to be active, otherwise it is unloaded immediately.
255
256 All libinput-specific APIs can be accessed through the ``libinput`` object.
257
258 .. function:: libinput:register({1, 2, ...})
259
260 Register this plugin with the given table of supported version numbers and
261 returns the version number selected by libinput for this plugin. See
262 :ref:`plugins_api_version_stability` for details.
263
264 .. code-block:: lua
265
266 -- this plugin can support versions 1, 4 and 5
267 version = libinput:register({1, 4, 5})
268 if version == 1 then
269 ...
270
271 This function must be the first function called.
272 If the plugin calls any other functions before ``register()``, those functions
273 return the default zero value for the return type (``nil``, ``0``, an empty
274 table, etc.).
275
276 If the plugin does not call ``register()`` it will be removed immediately.
277 Once registered, any connected callbacks will be invoked whenever libinput
278 detects new devices, removes devices, etc.
279
280 This function must only be called once.
281
282 .. function:: libinput:unregister()
283
284 Unregister this plugin. This removes the plugin from libinput and releases
285 any resources associated with this plugin. This call must be the last call
286 in your plugin, it is effectively equivalent to Lua's
287 `os.exit() <https://www.lua.org/manual/5.4/manual.html#pdf-os.exit>`_.
288
289 .. function:: libinput:log_debug(message)
290
291 Log a message at the libinput debug log priority. See
292 ``libinput:log_error()`` for details.
293
294 .. function:: libinput:log_info(message)
295
296 Log a message at the libinput info log priority. See
297 ``libinput:log_error()`` for details.
298
299 .. function:: libinput:log_error(message)
300
301 Log a message at the libinput error log priority. Whether a message is
302 displayed in the log depends on libinput's log priority, set by the caller.
303
304 A compositor may disable stdout and stderr. Log messages should be preferred
305 over Lua's ``print()`` function to ensure the messages end up in the same
306 location as other libinput log messages and are not discarded.
307
308 .. function:: libinput:now()
309
310 Returns the current time in microseconds in ``CLOCK_MONOTONIC``. This is
311 the timestamp libinput uses internally. This timestamp cannot be mapped
312 to any particular time of day, see the
313 `clock_gettime() man page <https://man7.org/linux/man-pages/man3/clock_gettime.3.html>`_
314 for details.
315
316 .. function:: libinput:version()
317
318 Returns the agreed-on version of the plugin, see ``libinput:register()``.
319 If called before ``libinput:register()`` this function returns ``0``.
320
321 .. function:: libinput:connect(name, function)
322
323 Set the callback to the given event name. Only one callback
324 may be set for an event name at any time, subsequent callbacks
325 will replace any earlier callbacks for the same name.
326
327 Version 1 of the plugin API supports the following events and callback arguments:
328
329 - ``"new-evdev-device"``: A new :ref:`EvdevDevice <plugins_api_evdevdevice>`
330 has been seen by libinput but not yet added.
331
332 .. code-block:: lua
333
334 libinput:connect("new-evdev-device", function (device) ... end)
335
336 - ``"timer-expired"``: The timer for this plugin has expired. This event is
337 only sent if the plugin has set a timer with ``timer_set()``.
338
339 .. code-block:: lua
340
341 libinput:connect("timer-expired", function (now) ... end)
342
343 The ``now`` argument is the current time in microseconds in
344 ``CLOCK_MONOTONIC`` (see ``libinput:now()``).
345
346 .. function:: libinput:timer_cancel()
347
348 Cancel the timer for this plugin. This is a no-op if the timer
349 has not been set or has already expired.
350
351 .. function:: libinput:timer_set_absolute(time)
352
353 Set a timer for this plugin, with the given time in microseconds.
354 The timeout specifies an absolute time in microseconds (see
355 ``libinput:now()``) The timer will expire once and then call the
356 ``"timer-expired"`` event handler (if any).
357
358 See ``libinput:timer_set_relative()`` for a relative timer.
359
360 The following two lines of code are equivalent:
361
362 .. code-block:: lua
363
364 libinput:timer_set_relative(1000000) -- 1 second from now
365 libinput:timer_set_absolute(libinput:now() + 1000000) -- 1 second from now
366
367 Calling this function will cancel any existing (relative or absolute) timer.
368
369 .. function:: libinput:timer_set_relative(timeout)
370
371 Set a timer for this plugin, with the given timeout in microseconds from
372 the current time. The timer will expire once and then call the
373 ``"timer-expired"`` event handler (if any).
374
375 See ``libinput:timer_set_absolute()`` for an absolute timer.
376
377 The following two lines of code are equivalent:
378
379 .. code-block:: lua
380
381 libinput:timer_set_relative(1000000) -- 1 second from now
382 libinput:timer_set_absolute(libinput:now() + 1000000) -- 1 second from now
383
384 Calling this function will cancel any existing (relative or absolute) timer.
385
386 .. _plugins_api_evdevdevice:
387
388 ................................................................................
389 The ``EvdevDevice`` type
390 ................................................................................
391
392 The ``EvdevDevice`` type represents a device available in the system
393 but not (yet) added by libinput. This device may be used to modify
394 a device's capabilities before the device is processed by libinput.
395
396 A plugin should always ``connect()`` to the ``"device-removed"`` callback
397 to be notified when a device is removed. If the plugin keeps a reference
398 to this device but the device is discarded by libinput, the device's query
399 methods will return zero values (e.g. ``nil``, ``0``, an empty table) and
400 methods will be noops.
401
402 .. function:: EvdevDevice:info()
403
404 A table containing static information about the device, e.g.
405
406 .. code-block:: lua
407
408 {
409 bustype = evdev.BUS_USB,
410 vid = 0x1234,
411 pid = 0x5678,
412 }
413
414 A plugin must ignore keys it does not know about.
415
416 Version 1 of the plugin API supports the following keys and values:
417
418 - ``bustype``: The numeric bustype of the device. See the
419 ``BUS_*`` defines in ``linux/input.h`` for the list of possible values.
420 - ``vid``: The 16-bit vendor ID of the device
421 - ``pid``: The 16-bit product ID of the device
422
423 If the device has since been discarded by libinput, this function returns an
424 empty table.
425
426 .. function:: EvdevDevice:name()
427
428 The device name as set by the kernel
429
430 .. function:: EvdevDevice:usages()
431
432 Returns a table of all usages that are currently enabled for this
433 device. Any type that exists on the device has a table assigned and in this
434 table any code that exists on the device is a boolean true.
435 For example:
436
437 .. code-block:: lua
438
439 {
440 evdev.REL_X = true,
441 evdev.REL_Y = true,
442 evdev.BTN_LEFT = true,
443 }
444
445 All other usages are ``nil``, so that the following code is possible:
446
447 .. code-block:: lua
448
449 local usages = device:usages()
450 if usages[evdev.REL_X] then
451 -- do something
452 end
453
454
455 If the device has since been discarded by libinput, this function returns an
456 empty table.
457
458 .. function:: EvdevDevice:absinfos()
459
460 Returns a table of all ``EV_ABS`` codes that are currently enabled for this device.
461 The event code is the key, each value is a table containing the following keys:
462 ``minimum``, ``maximum``, ``fuzz``, ``flat``, ``resolution``.
463
464 .. code-block:: lua
465
466 {
467 evdev.ABS_X = {
468 minimum = 0,
469 maximum = 1234,
470 fuzz = 0,
471 flat = 0,
472 resolution = 45,
473 },
474 }
475
476 If the device has since been discarded by libinput, this function returns an
477 empty table.
478
479 .. function:: EvdevDevice:udev_properties()
480
481 Returns a table containing a filtered list of udev properties available on this device
482 in the form ``{ property_name = property_value, ... }``.
483 udev properties used as a boolean (e.g. ``ID_INPUT``) are only present if their
484 value is a logical true.
485
486 Version 1 of the plugin API supports the following udev properties:
487
488 - ``ID_INPUT`` and all of ``ID_INPUT_*`` that denote the device type as assigned
489 by udev. This information is usually used by libinput to determine a
490 device type. Note that for historical reasons these properties have
491 varying rules - some properties may be mutually exclusive, others are
492 independent, others may only be set if another property is set. Refer to
493 the udev documentation (if any) for details. ``ID_INPUT_WIDTH_MM`` and
494 ``ID_INPUT_HEIGHT_MM`` are excluded from this set.
495
496 If the device has since been discarded by libinput, this function returns an
497 empty table.
498
499 .. function:: EvdevDevice:enable_evdev_usage(usage)
500
501 Enable the given :ref:`evdev usage <plugins_api_evdev_usage>` for this device.
502 Use :ref:`plugins_api_evdev_global` for better readability,
503 e.g. ``device:enable_evdev_usage(evdev.REL_X)``.
504 This function must not be used for ``ABS_*`` events, use ``set_absinfo()``
505 instead.
506
507 Once a usage is enabled, events for that usage may be added to a device's
508 frame.
509
510 If the device has since been discarded by libinput, this function does nothing.
511
512 .. function:: EvdevDevice:disable_evdev_usage(usage)
513
514 Disable the given :ref:`evdev usage <plugins_api_evdev_usage>` for this device.
515 Use :ref:`plugins_api_evdev_global` for better readability,
516 e.g. ``device:disable_evdev_usage(evdev.REL_X)``.
517
518 Once a usage is disabled, events for that usage are discarded from any
519 device frame.
520
521 If the device has since been discarded by libinput, this function does nothing.
522
523 .. function:: EvdevDevice:set_absinfo(usage, absinfo)
524
525 Set the absolute axis information for the given :ref:`evdev usage <plugins_api_evdev_usage>`
526 and enable it if it does not yet exist on the device. The ``absinfo`` argument is a table
527 containing zero or more of the following keys: ``minimum``, ``maximum``, ``fuzz``,
528 ``flat``, ``resolution``. Any missing key defaults the corresponding
529 value from the device if the device already has this event usage or zero otherwise.
530 For example, the following code changes the resolution but leaves everything
531 else as-is:
532
533 .. code-block:: lua
534
535 local absinfo = {
536 resolution = 40,
537 }
538 device:set_absinfo(evdev.ABS_X, absinfo)
539 device:set_absinfo(evdev.ABS_Y, absinfo)
540
541 Use :ref:`plugins_api_evdev_global` for better readability as shown in the
542 example above.
543
544 If the device has since been discarded by libinput, this function does nothing.
545
546 .. note:: Overriding the absinfo values often indicates buggy firmware. This should
547 typically be fixed with an entry in the
548 `60-evdev.hwdb <https://github.com/systemd/systemd/blob/main/hwdb.d/60-evdev.hwdb>`_
549 or :ref:`device-quirks` instead of a plugin so all users of that
550 device can benefit from the fix.
551
552 .. function:: EvdevDevice:connect(name, function)
553
554 Set the callback to the given event name. Only one callback
555 may be set for an event name at any time, subsequent callbacks
556 will overwrite any earlier callbacks for the same name.
557
558 If the device has since been discarded by libinput, this function does nothing.
559
560 Version 1 of the plugin API supports the following events and callback arguments:
561
562 - ``"evdev-frame"``: A new :ref:`evdev frame <plugins_api_evdev_frame>` has
563 started for this device. If the callback returns a value other than
564 ``nil``, that value is the frame with any modified events.
565 An empty frame (``{}``) causes libinput to drop the current event frame.
566
567 .. code-block:: lua
568
569 device:connect("evdev-frame", function (device, frame, timestamp)
570 -- change any event into a movement left by 1 pixel
571 move_left = {
572 { usage = evdev.REL_X, value = -1, },
573 }
574 return move_left
575 end
576
577 The timestamp of an event frame is in microseconds in ``CLOCK_MONOTONIC``, see
578 ``libinput:now()`` for details.
579
580 For performance reasons plugins that do not modify the event frame should
581 return ``nil`` (or nothing) instead of the event frame that was passed
582 as argument.
583
584 - ``"device-removed"``: This device was removed by libinput. This may happen
585 without the device ever becoming a libinput device as seen by libinput's
586 public API (e.g. if the device does not meet the requirements to be
587 added). Once this callback is invoked, the plugin should remove any
588 references to this device and stop using it.
589
590 .. code-block:: lua
591
592 device:connect("device-removed", function (device) ... end)
593
594 Functions to query the device's capabilities (e.g. ``usages()``) will
595 return an empty table.
596
597 .. function:: EvdevDevice:disconnect(name)
598
599 Disconnect the existing callback (if any) for the given event name. See
600 ``EvdevDevice:connect()`` for a list of supported names.
601
602 .. function:: EvdevDevice:prepend_frame(frame)
603
604 Prepend an :ref:`evdev frame <plugins_api_evdev_frame>` for this device
605 **before** the current frame (if any). The **next** plugin will see the
606 prepended frame first followed by the current frame.
607
608 This function can only be called from within a device's ``"evdev-frame"``
609 handler or from within the plugin's timer callback function.
610
611 For example, to change a single event into a drag, prepend a button
612 down and append a button up before each event:
613
614 .. code:: lua
615
616 function frame_handler(device, frame, timestamp)
617 device:prepend_frame({
618 { usage = evdev.BTN_LEFT, value = 1}
619 })
620 device:append_frame({
621 { usage = evdev.BTN_LEFT, value = 0}
622 })
623 return nil -- return the current frame unmodified
624
625 -- The next plugin sees the event sequence:
626 -- button down, frame, button up
627 end
628
629 If called from within the plugin's timer there is no current frame and this
630 function is identical to ``append_frame()``.
631
632 .. function:: EvdevDevice:append_frame(frame)
633
634 Appends an :ref:`evdev frame <plugins_api_evdev_frame>` for this device
635 **after** the current frame (if any). This function can only be called from
636 within a device's ``"evdev-frame"`` handler or from within the plugin's timer
637 callback function.
638
639 If called from within the plugin's timer there is no current frame and this
640 function is identical to ``prepend_frame()``.
641
642 See ``prepend_frame()`` for more details.
643
644 .. function:: EvdevDevice:disable_feature(feature_name)
645
646 Disable the given libinput-internal feature for this device. This should be used
647 by plugins that replace that feature with a custom implementation for this device.
648
649 libinput may have multiple internal implementations for any given feature, disabling
650 it via this API disables any and all of those implementations, causing the feature to
651 no longer work at all. It is up to the plugin implementation to re-implement that
652 feature to match the user's expectation.
653
654 Version 1 of the plugin API supports the following features:
655
656 - ``"button-debouncing"``: see :ref:`button_debouncing`
657 - ``"touchpad-hysteresis"``: see :ref:`touchpad_jitter`
658 - ``"touchpad-jump-detection"``: see :ref:`touchpad_jumping_cursor`
659 - ``"touchpad-palm-detection"``: see :ref:`palm_detection`
660 - ``"wheel-debouncing"``: some high-resolution mouse wheel movements inside libinput
661 are delayed and/or modified