| 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/ |