1.. _udev_config:
2
3==============================================================================
4Static device configuration via udev
5==============================================================================
6
7libinput supports some static configuration through udev properties.
8These properties are read when the device is initially added
9to libinput's device list, i.e. before the
10**LIBINPUT_EVENT_DEVICE_ADDED** event is generated.
11
12The following udev properties are supported:
13
14LIBINPUT_CALIBRATION_MATRIX
15    Sets the calibration matrix, see
16    **libinput_device_config_calibration_get_default_matrix()**. If unset,
17    defaults to the identity matrix.
18
19    The udev property is parsed as 6 floating point numbers separated by a
20    single space each (scanf(3) format ``"%f %f %f %f %f %f"``).
21    The 6 values represent the first two rows of the calibration matrix as
22    described in **libinput_device_config_calibration_set_matrix()**.
23
24    Example values are: ::
25
26          ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
27          ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
28          ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
29          ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
30          ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis
31
32
33LIBINPUT_DEVICE_GROUP
34    A string identifying the **libinput_device_group** for this device. Two
35    devices with the same property value are grouped into the same device group,
36    the value itself is irrelevant otherwise.
37
38LIBINPUT_IGNORE_DEVICE
39    If set to anything other than "0", the device is ignored by libinput.
40    See :ref:`ignoring_devices` for more details.
41
42ID_SEAT
43    Assigns the physical :ref:`seat <seats>` for this device. See
44    **libinput_seat_get_physical_name()**. Defaults to "seat0".
45
46ID_INPUT
47    If this property is set, the device is considered an input device. Any
48    device with this property missing will be ignored, see :ref:`udev_device_type`.
49
50ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, ID_INPUT_ACCELEROMETER
51    If any of the above is set, libinput initializes the device as the given
52    type, see :ref:`udev_device_type`. Note that for historical reasons more than
53    one of these may be set at any time, libinput will select only one of these
54    to determine the device type. To ensure libinput selects the correct device
55    type, only set one of them.
56
57WL_SEAT
58    Assigns the logical :ref:`seat <seats>` for this device. See
59    **libinput_seat_get_logical_name()** context. Defaults to "default".
60
61MOUSE_DPI
62    HW resolution and sampling frequency of a relative pointer device.
63    See :ref:`motion_normalization` for details.
64
65MOUSE_WHEEL_CLICK_ANGLE
66    The angle in degrees for each click on a mouse wheel. See
67    **libinput_pointer_get_axis_source()** for details.
68
69
70Below is an example udev rule to assign "seat1" to a device from vendor
71``0x012a`` with the model ID of ``0x034b``. ::
72
73   $ cat /etc/udev/rules.d/99-my-device-is-on-seat1.rules
74     ACTION!="remove", KERNEL=="event[0-9]*", \
75     ENV{ID_VENDOR_ID}=="012a", \
76     ENV{ID_MODEL_ID}=="034b", \
77     ENV{ID_SEAT}="seat1"
78
79
80
81.. _udev_device_type:
82
83------------------------------------------------------------------------------
84Device type assignment via udev
85------------------------------------------------------------------------------
86
87libinput requires the **ID_INPUT** property to be set on a device,
88otherwise the device will be ignored. In addition, one of
89**ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
90ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
91ID_INPUT_ACCELEROMETER** must be set on the device to determine the
92device type. The usual error handling applies within libinput and a device
93type label does not guarantee that the device is initialized by libinput.
94If a device fails to meet the requirements for a device type (e.g. a keyboard
95labelled as touchpad) the device will not be available through libinput.
96
97Only one device type should be set per device at a type, though libinput can
98handle some combinations for historical reasons.
99
100Below is an example udev rule  to remove an **ID_INPUT_TOUCHPAD** setting
101and change it into an **ID_INPUT_TABLET** setting. This rule would apply
102for a device with the vendor/model ID of ``012a``/``034b``. ::
103
104   $ cat /etc/udev/rules.d/99-my-device-is-a-tablet.rules
105     ACTION!="remove", KERNEL=="event[0-9]*", \
106     ENV{ID_VENDOR_ID}=="012a", \
107     ENV{ID_MODEL_ID}=="034b", \
108     ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"
109
110
111.. _model_specific_configuration:
112
113------------------------------------------------------------------------------
114Model-specific configuration
115------------------------------------------------------------------------------
116
117As of libinput 1.12, model-specific configuration is stored in the
118:ref:`device-quirks` and not in the hwdb anymore. Please see
119:ref:`device-quirks` for
120details.
121
122.. _model_specific_configuration_x220fw81:
123
124..............................................................................
125Lenovo x220 with touchpad firmware v8.1
126..............................................................................
127
128The property **LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81** may be set by a
129user in a local hwdb file. This property designates the touchpad on a Lenovo
130x220 with a touchpad firmware version 8.1. When this firmware version is
131installed, the touchpad is imprecise. The touchpad device does not send
132continuous x/y axis position updates, a behavior also observed on its
133successor model, the Lenovo x230 which has the same firmware version. If the
134above property is set, libinput adjusts its behavior to better suit this
135particular model.
136
137The touchpad firmware version cannot be detected automatically by libinput,
138local configuration is required to set this property. Refer to the libinput
139model quirks hwdb for instructions.
140
141This property must not be used for any other purpose, no specific behavior
142is guaranteed.
143
144
145.. _hwdb:
146
147------------------------------------------------------------------------------
148Configuring the hwdb
149------------------------------------------------------------------------------
150
151This section outlines how to query the
152`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
153and reload properties so they are available to libinput.
154
155The hwdb contains a set of match rules that assign udev properties that are
156available to libinput when the device is connected and/or libinput is
157initialized. This section only describes the hwdb in relation to libinput,
158it is not a full documentation on how the hwdb works.
159
160libinput's use of the hwdb is limited to properties systemd and custom
161rules files (where available) provide. Hardware-specific quirks as used by
162libinput are in the :ref:`device-quirks` system.
163
164.. _hwdb_querying:
165
166..............................................................................
167Querying the hwdb
168..............................................................................
169
170libinput only uses device nodes in the form of ``/dev/input/eventX`` where X
171is the number of the specific device. Running ``libinput debug-events`` lists
172all devices currently available to libinput and their event node name: ::
173
174    $> sudo libinput debug-events
175    -event2   DEVICE_ADDED     Power Button                      seat0 default group1  cap:k
176    -event5   DEVICE_ADDED     Video Bus                         seat0 default group2  cap:k
177    -event0   DEVICE_ADDED     Lid Switch                        seat0 default group3  cap:S
178
179    ...
180
181Note the event node name for your device and translate it into a syspath in
182the form of ``/sys/class/input/eventX``. This path can be supplied to ``udevadm
183info`` ::
184
185    $> udevadm info
186    P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
187    N: input/event0
188    E: DEVNAME=/dev/input/event0
189    E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
190    E: ID_INPUT=1
191    E: ID_INPUT_SWITCH=1
192    E: MAJOR=13
193    E: MINOR=64
194    E: SUBSYSTEM=input
195    E: TAGS=:power-switch:
196    E: USEC_INITIALIZED=7167898
197
198Lines starting with ``E:`` are udev properties available to libinput. For
199example, the above device's ``ID_INPUT_SWITCH`` property will cause libinput
200to treat this device as switch device.
201
202
203.. _hwdb_reloading:
204
205..............................................................................
206Reloading the hwdb
207..............................................................................
208
209The actual hwdb is stored in binary file on-disk and must be updated
210manually whenever a ``.hwdb`` file changes. This is required both when a user
211manually edits the ``.hwdb`` file but also when the git tree is updated (and
212that update causes a hwdb change).
213
214To update the binary file on-disk, run: ::
215
216    sudo systemd-hwdb update
217
218Then, to trigger a reload of all properties on your device, run: ::
219
220    sudo udevadm trigger /sys/class/input/eventX
221
222Then check with ``udevadm info`` whether the properties were updated, see
223:ref:`hwdb_querying`. If a new property does not appear on the device, use ``udevadm
224test`` to check for error messages by udev and the hwdb (e.g. syntax errors
225in the udev rules files). ::
226
227    sudo udevadm test /sys/class/input/eventX
228
229.. warning::  ``udevadm test`` does not run commands specified in ``RUN``
230	      directives. This affects the udev properties relying on e.g.
231	      the udev keyboard builtin such as the :ref:`touchpad_jitter`
232	      workarounds.
233
234.. _hwdb_modifying:
235
236..............................................................................
237Modifying the hwdb
238..............................................................................
239
240.. warning:: This section has been removed as it no longer applies in libinput 1.12
241             and later. libinput users should not need to modify the hwdb, any
242             device-specific quirks must go in to the :ref:`device-quirks` system.
243
244For information about older libinput versions, please see the documentation
245for your version available in: https://wayland.freedesktop.org/libinput/doc/
246