1.. _absolute_coordinate_ranges: 2 3============================================================================== 4Coordinate ranges for absolute axes 5============================================================================== 6 7libinput requires that all touchpads provide a correct axis range and 8resolution. These are used to enable or disable certain features or adapt 9the interaction with the touchpad. For example, the software button area is 10narrower on small touchpads to avoid reducing the interactive surface too 11much. Likewise, palm detection works differently on small touchpads as palm 12interference is less likely to happen. 13 14Touchpads with incorrect axis ranges generate error messages 15in the form: 16<blockquote> 17Axis 0x35 value 4000 is outside expected range [0, 3000] 18</blockquote> 19 20This error message indicates that the ABS_MT_POSITION_X axis (i.e. the x 21axis) generated an event outside the expected range of 0-3000. In this case 22the value was 4000. 23This discrepancy between the coordinate range the kernels advertises vs. 24what the touchpad sends can be the source of a number of perceived 25bugs in libinput. 26 27.. _absolute_coordinate_ranges_fix: 28 29------------------------------------------------------------------------------ 30Measuring and fixing touchpad ranges 31------------------------------------------------------------------------------ 32 33To fix the touchpad you need to: 34 35#. measure the physical size of your touchpad in mm 36#. run the ``libinput measure touchpad-size`` tool 37#. verify the hwdb entry provided by this tool 38#. test locally 39#. send a patch to the `systemd project <https://github.com/systemd/systemd>`_. 40 41Detailed explanations are below. 42 43.. note:: ``libinput measure touchpad-size`` was introduced in libinput 44 1.16. For earlier versions, use `libevdev <http://freedesktop.org/wiki/Software/libevdev/>`_'s 45 ``touchpad-edge-detector`` tool. 46 47 48The ``libinput measure touchpad-size`` tool is an interactive tool. It must 49be called with the physical dimensions of the touchpad in mm. In the example 50below, we use 100mm wide and 55mm high. The tool will find the touchpad device 51automatically. 52 53:: 54 55 $> sudo libinput measure touchpad-size 100x55 56 Using "Touchpad SynPS/2 Synaptics TouchPad": /dev/input/event4 57 58 Kernel specified touchpad size: 99.7x75.9mm 59 User specified touchpad size: 100.0x55.0mm 60 61 Kernel axis range: x [1024..5112], y [2024..4832] 62 Detected axis range: x [ 0.. 0], y [ 0.. 0] 63 64 Move one finger along all edges of the touchpad 65 until the detected axis range stops changing. 66 67 ... 68 69Move the finger around until the detected axis range matches the data sent 70by the device. ``Ctrl+C`` terminates the tool and prints a 71suggested hwdb entry. :: 72 73 ... 74 Kernel axis range: x [1024..5112], y [2024..4832] 75 ^C 76 Detected axis range: x [2072..4880], y [2159..4832] 77 Resolutions calculated based on user-specified size: x 28, y 49 units/mm 78 79 Suggested hwdb entry: 80 Note: the dmi modalias match is a guess based on your machine's modalias: 81 dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable: 82 Please verify that this is the most sensible match and adjust if necessary. 83 -8<-------------------------- 84 # Laptop model description (e.g. Lenovo X1 Carbon 5th) 85 evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s* 86 EVDEV_ABS_00=2072:4880:28 87 EVDEV_ABS_01=2159:4832:49 88 EVDEV_ABS_35=2072:4880:28 89 EVDEV_ABS_36=2159:4832:49 90 -8<-------------------------- 91 Instructions on what to do with this snippet are in /usr/lib/udev/hwdb.d/60-evdev.hwdb 92 93 94If there are discrepancies between the coordinate range the kernels 95advertises and what what the touchpad sends, the hwdb entry should be added to the 96``60-evdev.hwdb`` file provided by the `systemd project <https://github.com/systemd/systemd>`_. 97An example commit can be found 98`here <https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045>`_. 99 100The ``libinput measure touchpad-size`` tool attempts to provide the correct 101dmi match but it does require user verification. 102 103In most cases the dmi match can and should be trimmed to the system vendor (``svn``) 104and the product version (``pvr``) or product name (``pn``), with everything else 105replaced by a wildcard (``*``). In the above case, the match string is: 106 107:: 108 109 evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s* 110 111As a general rule: for Lenovo devices use ``pvr`` and for all others use 112``pn``. 113 114.. note:: hwdb match strings only allow for alphanumeric ascii characters. Use a 115 wildcard (* or ?, whichever appropriate) for special characters. 116 117The actual axis overrides are in the form: 118 119:: 120 121 # axis number=min:max:resolution 122 EVDEV_ABS_00=2072:4880:28 123 124or, if the range is correct but the resolution is wrong 125 126:: 127 128 # axis number=::resolution 129 EVDEV_ABS_00=::28 130 131 132Note the leading single space. The axis numbers are in hex and can be found 133in ``linux/input-event-codes.h``. For touchpads ``ABS_X``, ``ABS_Y``, 134``ABS_MT_POSITION_X`` and ``ABS_MT_POSITION_Y`` are required. 135 136.. note:: The touchpad's ranges and/or resolution should only be fixed when 137 there is a significant discrepancy. A few units do not make a 138 difference and a resolution that is off by 2 or less usually does 139 not matter either. 140 141Once a match and override rule has been found, follow the instructions at 142the top of the 143`60-evdev.hwdb <https://github.com/systemd/systemd/blob/master/hwdb/60-evdev.hwdb>`_ 144file to save it locally and trigger the udev hwdb reload. Rebooting is 145always a good idea. If the match string is correct, the new properties will 146show up in the 147output of 148 149:: 150 151 udevadm info /sys/class/input/event4 152 153 154Adjust the command for the event node of your touchpad. 155A udev builtin will apply the new axis ranges automatically. 156 157When the axis override is confirmed to work, please submit it as a pull 158request to the `systemd project <https://github.com/systemd/systemd>`_. 159