Debian Codegraph @

doc/user/device-configuration-via-udev.rst

raw
1 .. _udev_config:
2
3 ==============================================================================
4 Static device configuration via udev
5 ==============================================================================
6
7 libinput supports some static configuration through udev properties.
8 These properties are read when the device is initially added
9 to libinput's device list, i.e. before the
10 **LIBINPUT_EVENT_DEVICE_ADDED** event is generated.
11
12 The following udev properties are supported:
13
14 LIBINPUT_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
33 LIBINPUT_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
38 LIBINPUT_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
42 ID_SEAT
43 Assigns the physical :ref:`seat <seats>` for this device. See
44 **libinput_seat_get_physical_name()**. Defaults to "seat0".
45
46 ID_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
50 ID_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
57 WL_SEAT
58 Assigns the logical :ref:`seat <seats>` for this device. See
59 **libinput_seat_get_logical_name()** context. Defaults to "default".
60
61 MOUSE_DPI
62 HW resolution and sampling frequency of a relative pointer device.
63 See :ref:`motion_normalization` for details.
64
65 MOUSE_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
70 Below 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 ------------------------------------------------------------------------------
84 Device type assignment via udev
85 ------------------------------------------------------------------------------
86
87 libinput requires the **ID_INPUT** property to be set on a device,
88 otherwise the device will be ignored. In addition, one of
89 **ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
90 ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
91 ID_INPUT_ACCELEROMETER** must be set on the device to determine the
92 device type. The usual error handling applies within libinput and a device
93 type label does not guarantee that the device is initialized by libinput.
94 If a device fails to meet the requirements for a device type (e.g. a keyboard
95 labelled as touchpad) the device will not be available through libinput.
96
97 Only one device type should be set per device at a type, though libinput can
98 handle some combinations for historical reasons.
99
100 Below is an example udev rule to remove an **ID_INPUT_TOUCHPAD** setting
101 and change it into an **ID_INPUT_TABLET** setting. This rule would apply
102 for 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 ------------------------------------------------------------------------------
114 Model-specific configuration
115 ------------------------------------------------------------------------------
116
117 As 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
120 details.
121
122 .. _model_specific_configuration_x220fw81:
123
124 ..............................................................................
125 Lenovo x220 with touchpad firmware v8.1
126 ..............................................................................
127
128 The property **LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81** may be set by a
129 user in a local hwdb file. This property designates the touchpad on a Lenovo
130 x220 with a touchpad firmware version 8.1. When this firmware version is
131 installed, the touchpad is imprecise. The touchpad device does not send
132 continuous x/y axis position updates, a behavior also observed on its
133 successor model, the Lenovo x230 which has the same firmware version. If the
134 above property is set, libinput adjusts its behavior to better suit this
135 particular model.
136
137 The touchpad firmware version cannot be detected automatically by libinput,
138 local configuration is required to set this property. Refer to the libinput
139 model quirks hwdb for instructions.
140
141 This property must not be used for any other purpose, no specific behavior
142 is guaranteed.
143
144
145 .. _hwdb:
146
147 ------------------------------------------------------------------------------
148 Configuring the hwdb
149 ------------------------------------------------------------------------------
150
151 This section outlines how to query the
152 `udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
153 and reload properties so they are available to libinput.
154
155 The hwdb contains a set of match rules that assign udev properties that are
156 available to libinput when the device is connected and/or libinput is
157 initialized. This section only describes the hwdb in relation to libinput,
158 it is not a full documentation on how the hwdb works.
159
160 libinput's use of the hwdb is limited to properties systemd and custom
161 rules files (where available) provide. Hardware-specific quirks as used by
162 libinput are in the :ref:`device-quirks` system.
163
164 .. _hwdb_querying:
165
166 ..............................................................................
167 Querying the hwdb
168 ..............................................................................
169
170 libinput only uses device nodes in the form of ``/dev/input/eventX`` where X
171 is the number of the specific device. Running ``libinput debug-events`` lists
172 all 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
181 Note the event node name for your device and translate it into a syspath in
182 the form of ``/sys/class/input/eventX``. This path can be supplied to ``udevadm
183 info`` ::
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
198 Lines starting with ``E:`` are udev properties available to libinput. For
199 example, the above device's ``ID_INPUT_SWITCH`` property will cause libinput
200 to treat this device as switch device.
201
202
203 .. _hwdb_reloading:
204
205 ..............................................................................
206 Reloading the hwdb
207 ..............................................................................
208
209 The actual hwdb is stored in binary file on-disk and must be updated
210 manually whenever a ``.hwdb`` file changes. This is required both when a user
211 manually edits the ``.hwdb`` file but also when the git tree is updated (and
212 that update causes a hwdb change).
213
214 To update the binary file on-disk, run: ::
215
216 sudo systemd-hwdb update
217
218 Then, to trigger a reload of all properties on your device, run: ::
219
220 sudo udevadm trigger /sys/class/input/eventX
221
222 Then 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
224 test`` to check for error messages by udev and the hwdb (e.g. syntax errors
225 in 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 ..............................................................................
237 Modifying 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
244 For information about older libinput versions, please see the documentation
245 for your version available in: https://wayland.freedesktop.org/libinput/doc/