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 710x012a with the model ID of 0x034b. :: 72 73 ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \ 74 ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1" 75 76 77 78.. _udev_device_type: 79 80------------------------------------------------------------------------------ 81Device type assignment via udev 82------------------------------------------------------------------------------ 83 84libinput requires the **ID_INPUT** property to be set on a device, 85otherwise the device will be ignored. In addition, one of 86**ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, 87ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, 88ID_INPUT_ACCELEROMETER** must be set on the device to determine the 89device type. The usual error handling applies within libinput and a device 90type label does not guarantee that the device is initialized by libinput. 91If a device fails to meet the requirements for a device type (e.g. a keyboard 92labelled as touchpad) the device will not be available through libinput. 93 94Only one device type should be set per device at a type, though libinput can 95handle some combinations for historical reasons. 96 97Below is an example udev rule to remove an **ID_INPUT_TOUCHPAD** setting 98and change it into an **ID_INPUT_TABLET** setting. This rule would apply 99for a device with the vendor/model ID of 012a/034b. :: 100 101 ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \ 102 ENV{ID_MODEL_ID}=="034b", ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1" 103 104 105 106.. _ignoring_devices: 107 108------------------------------------------------------------------------------ 109Ignoring specific devices 110------------------------------------------------------------------------------ 111 112If a device has the **LIBINPUT_IGNORE_DEVICE** udev property set to any 113value but "0", that device is not initialized by libinput. For a context 114created with **libinput_udev_create_context()**, the device is silently ignored 115and never shows up. If the device is added with **libinput_path_add_device()** 116to a context created with **libinput_path_create_context()**, adding the device 117will fail and return NULL (see that function's documentation for more 118information). 119 120If the property value is exactly "0", then the property is considered unset 121and libinput initializes the device normally. 122 123This property should be used for devices that are correctly detected as 124input devices (see :ref:`udev_device_type`) but that should not be used by 125libinput. It is recommended that devices that should not be handled as input 126devices at all unset the **ID_INPUT** and related properties instead. The 127**LIBINPUT_IGNORE_DEVICE** property signals that only libinput should 128ignore this property but other parts of the stack (if any) should continue 129treating this device normally. 130 131 132.. _model_specific_configuration: 133 134------------------------------------------------------------------------------ 135Model-specific configuration 136------------------------------------------------------------------------------ 137 138As of libinput 1.12, model-specific configuration is stored in the 139:ref:`device-quirks` and not in the hwdb anymore. Please see 140:ref:`device-quirks` for 141details. 142 143.. _model_specific_configuration_x220fw81: 144 145.............................................................................. 146Lenovo x220 with touchpad firmware v8.1 147.............................................................................. 148 149The property **LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81** may be set by a 150user in a local hwdb file. This property designates the touchpad on a Lenovo 151x220 with a touchpad firmware version 8.1. When this firmware version is 152installed, the touchpad is imprecise. The touchpad device does not send 153continuos x/y axis position updates, a behavior also observed on its 154successor model, the Lenovo x230 which has the same firmware version. If the 155above property is set, libinput adjusts its behavior to better suit this 156particular model. 157 158The touchpad firmware version cannot be detected automatically by libinput, 159local configuration is required to set this property. Refer to the libinput 160model quirks hwdb for instructions. 161 162This property must not be used for any other purpose, no specific behavior 163is guaranteed. 164 165 166.. _hwdb: 167 168------------------------------------------------------------------------------ 169Configuring the hwdb 170------------------------------------------------------------------------------ 171 172This section outlines how to query the 173`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_ 174and reload properties so they are available to libinput. 175 176The hwdb contains a set of match rules that assign udev properties that are 177available to libinput when the device is connected and/or libinput is 178initialized. This section only describes the hwdb in relation to libinput, 179it is not a full documentation on how the hwdb works. 180 181libinput's use of the hwdb is limited to properties systemd and custom 182rules files (where available) provide. Hardware-specific quirks as used by 183libinput are in the :ref:`device-quirks` system. 184 185.. _hwdb_querying: 186 187.............................................................................. 188Querying the hwdb 189.............................................................................. 190 191libinput only uses device nodes in the form of ``/dev/input/eventX`` where X 192is the number of the specific device. Running ``libinput debug-events`` lists 193all devices currently available to libinput and their event node name: :: 194 195 $> sudo libinput debug-events 196 -event2 DEVICE_ADDED Power Button seat0 default group1 cap:k 197 -event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k 198 -event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S 199 200 ... 201 202Note the event node name for your device and translate it into a syspath in 203the form of ``/sys/class/input/eventX``. This path can be supplied to ``udevadm 204info`` :: 205 206 $> udevadm info 207 P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0 208 N: input/event0 209 E: DEVNAME=/dev/input/event0 210 E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0 211 E: ID_INPUT=1 212 E: ID_INPUT_SWITCH=1 213 E: MAJOR=13 214 E: MINOR=64 215 E: SUBSYSTEM=input 216 E: TAGS=:power-switch: 217 E: USEC_INITIALIZED=7167898 218 219Lines starting with ``E:`` are udev properties available to libinput. For 220example, the above device's ``ID_INPUT_SWITCH`` property will cause libinput 221to treat this device as switch device. 222 223 224.. _hwdb_reloading: 225 226.............................................................................. 227Reloading the hwdb 228.............................................................................. 229 230The actual hwdb is stored in binary file on-disk and must be updated 231manually whenever a ``.hwdb`` file changes. This is required both when a user 232manually edits the ``.hwdb`` file but also when the git tree is updated (and 233that update causes a hwdb change). 234 235To update the binary file on-disk, run: :: 236 237 sudo systemd-hwdb update 238 239Then, to trigger a reload of all properties on your device, run: :: 240 241 sudo udevadm trigger /sys/class/input/eventX 242 243Then check with ``udevadm info`` whether the properties were updated, see 244:ref:`hwdb_querying`. If a new property does not appear on the device, use ``udevadm 245test`` to check for error messages by udev and the hwdb (e.g. syntax errors 246in the udev rules files). :: 247 248 sudo udevadm test /sys/class/input/eventX 249 250.. warning:: ``udevadm test`` does not run commands specified in ``RUN`` 251 directives. This affects the udev properties relying on e.g. 252 the udev keyboard builtin such as the :ref:`touchpad_jitter` 253 workarounds. 254 255.. _hwdb_modifying: 256 257.............................................................................. 258Modifying the hwdb 259.............................................................................. 260 261.. warning:: This section has been removed as it no longer applies in libinput 1.12 262 and later. libinput users should not need to modify the hwdb, any 263 device-specific quirks must go in to the :ref:`device-quirks` system. 264 265For information about older libinput versions, please see the documentation 266for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/ 267