1============================================================================== 2Debugging touchpad pressure/size ranges 3============================================================================== 4 5:ref:`Touchpad pressure/size ranges <touchpad_pressure>` depend on 6:ref:`device-quirks` entry specific to each laptop model. To check if a 7pressure/size range is already defined for your device, use the 8:ref:`libinput quirks <device-quirks-debugging>` tool: :: 9 10 $ libinput quirks list /dev/input/event19 11 12If your device does not list any quirks, it probably needs a touch 13pressure/size range, a palm threshold and a thumb threshold. Start with 14:ref:`touchpad_pressure_hwdb`, then :ref:`touchpad_touch_size_hwdb`. The 15respective tools will exit if the required axis is not supported. 16 17 18.. _touchpad_pressure_hwdb: 19 20------------------------------------------------------------------------------ 21Debugging touchpad pressure ranges 22------------------------------------------------------------------------------ 23 24This section describes how to determine the touchpad pressure ranges 25required for a touchpad device and how to add the required 26:ref:`device-quirks` locally. Note that the quirk is **not public API** and **may 27change at any time**. Users are advised to :ref:`report a bug <reporting_bugs>` 28with the updated pressure ranges when testing has completed. 29 30.. note:: Most distributions ship ``libinput measure`` in a separate 31 ``libinput-utils`` package. 32 33Use the ``libinput measure touchpad-pressure`` tool provided by libinput. 34This tool will search for your touchpad device and print some pressure 35statistics, including whether a touch is/was considered logically down. 36 37.. note:: This tool will only work on touchpads with pressure. 38 39Example output of the tool is below: :: 40 41 $ sudo libinput measure touchpad-pressure 42 Using Synaptics TM2668-002: /dev/input/event21 43 44 This is an interactive tool 45 46 Place a single finger on the touchpad to measure pressure values. 47 Check that: 48 - touches subjectively perceived as down are tagged as down 49 - touches with a thumb are tagged as thumb 50 - touches with a palm are tagged as palm 51 52 If the touch states do not match the interaction, re-run 53 with --touch-thresholds=down:up using observed pressure values. 54 See --help for more options. 55 56 Press Ctrl+C to exit 57 58 +-------------------------------------------------------------------------------+ 59 | Thresh | 70 | 60 | 130 | 100 | | 60 +-------------------------------------------------------------------------------+ 61 | Touch | down | up | palm | thumb | min | max | p | avg | median | 62 +-------------------------------------------------------------------------------+ 63 | 178 | x | x | | | 75 | 75 | 0 | 75 | 75 | 64 | 179 | x | x | | | 35 | 88 | 0 | 77 | 81 | 65 | 180 | x | x | | x | 65 | 113 | 0 | 98 | 98 | 66 | 181 | x | x | | x | 50 | 101 | 0 | 86 | 90 | 67 | 182 | x | x | | | 40 | 80 | 0 | 66 | 70 | 68 | 183 | x | | | | 43 | 78 | 78 | | 69 ... 70 71 72The example output shows five completed touch sequences and one ongoing one. 73For each, the respective minimum and maximum pressure values are printed as 74well as some statistics. The ``down`` column show that each sequence was 75considered logically down at some point, two of the sequences were considered 76thumbs. This is an interactive tool and its output may change frequently. Refer 77to the **libinput-measure-touchpad-pressure(1)** man page for more details. 78 79By default, this tool uses the :ref:`device-quirks` for the pressure range. To 80narrow down on the best values for your device, specify the 'logically down' 81and 'logically up' pressure thresholds with the ``--touch-thresholds`` 82argument: :: 83 84 $ sudo libinput measure touchpad-pressure --touch-thresholds=10:8 --palm-threshold=20 85 86 87Interact with the touchpad and check if the output of this tool matches your 88expectations. 89 90.. note:: This is an interactive process. You will need to re-run the 91 tool with varying thresholds until you find the right range for 92 your touchpad. Attaching output logs to a bug will not help, only 93 you with access to the hardware can figure out the correct 94 ranges. 95 96Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with 97:ref:`device-quirks` entry similar to this: :: 98 99 $> cat /etc/libinput/local-overrides.quirks 100 [Touchpad pressure override] 101 MatchUdevType=touchpad 102 MatchName=*SynPS/2 Synaptics TouchPad 103 MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230* 104 AttrPressureRange=10:8 105 106The file name **must** be ``/etc/libinput/local-overrides.quirks``. The 107The first line is the section name and can be free-form. The ``Match`` 108directives limit the quirk to your touchpad, make sure the device name 109matches your device's name (see ``libinput record``'s output). The dmi 110modalias match should be based on the information in 111``/sys/class/dmi/id/modalias``. This modalias should be shortened to the 112specific system's information, usually system vendor (svn) 113and product name (pn). 114 115Once in place, run the following command to verify the quirk is valid and 116works for your device: :: 117 118 $ sudo libinput list-quirks /dev/input/event10 119 AttrPressureRange=10:8 120 121Replace the event node with the one from your device. If the 122``AttrPressureRange`` quirk does not show up, re-run with ``--verbose`` and 123check the output for any error messages. 124 125If the pressure range quirk shows up correctly, restart X or the 126Wayland compositor and libinput should now use the correct pressure 127thresholds. The :ref:`tools` can be used to verify the correct 128functionality first without the need for a restart. 129 130Once the pressure ranges are deemed correct, 131:ref:`report a bug <reporting_bugs>` to get the pressure ranges into the 132repository. 133 134.. _touchpad_touch_size_hwdb: 135 136------------------------------------------------------------------------------ 137Debugging touch size ranges 138------------------------------------------------------------------------------ 139 140This section describes how to determine the touchpad size ranges 141required for a touchpad device and how to add the required 142:ref:`device-quirks` locally. Note that the quirk is **not public API** and **may 143change at any time**. Users are advised to :ref:`report a bug <reporting_bugs>` 144with the updated pressure ranges when testing has completed. 145 146.. note:: Most distributions ship ``libinput measure`` in a separate 147 ``libinput-utils`` package. 148 149Use the ``libinput measure touch-size`` tool provided by libinput. 150This tool will search for your touchpad device and print some touch size 151statistics, including whether a touch is/was considered logically down. 152 153.. note:: This tool will only work on touchpads with the ``ABS_MT_MAJOR`` axis. 154 155Example output of the tool is below: :: 156 157 $ sudo libinput measure touch-size --touch-thresholds 10:8 --palm-threshold 14 158 Using ELAN Touchscreen: /dev/input/event5 159 160 Ready for recording data. 161 Touch sizes used: 10:8 162 Palm size used: 14 163 Place a single finger on the device to measure touch size. 164 Ctrl+C to exit 165 166 Sequence: major: [ 9.. 11] minor: [ 7.. 9] 167 Sequence: major: [ 9.. 10] minor: [ 7.. 7] 168 Sequence: major: [ 9.. 14] minor: [ 6.. 9] down 169 Sequence: major: [ 11.. 11] minor: [ 9.. 9] down 170 Sequence: major: [ 4.. 33] minor: [ 1.. 5] down palm 171 172The example output shows five completed touch sequences. For each, the 173respective minimum and maximum pressure values are printed as well as some 174statistics. The ``down`` and ``palm`` tags show that sequence was considered 175logically down or a palm at some point. This is an interactive tool and its 176output may change frequently. Refer to the **libinput-measure-touch-size(1)** man 177page for more details. 178 179By default, this tool uses the :ref:`device-quirks` for the touch size range. To 180narrow down on the best values for your device, specify the 'logically down' 181and 'logically up' pressure thresholds with the ``--touch-thresholds`` 182arguments as in the example above. 183 184Interact with the touchpad and check if the output of this tool matches your 185expectations. 186 187.. note:: This is an interactive process. You will need to re-run the 188 tool with varying thresholds until you find the right range for 189 your touchpad. Attaching output logs to a bug will not help, only 190 you with access to the hardware can figure out the correct 191 ranges. 192 193Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with 194:ref:`device-quirks` entry similar to this: :: 195 196 $> cat /etc/libinput/local-overrides.quirks 197 [Touchpad touch size override] 198 MatchUdevType=touchpad 199 MatchName=*SynPS/2 Synaptics TouchPad 200 MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230* 201 AttrTouchSizeRange=10:8 202 203The first line is the match line and should be adjusted for the device name 204(see :ref:`libinput record <libinput-record>`'s output) and for the local system, based on the 205information in ``/sys/class/dmi/id/modalias``. The modalias should be 206shortened to the specific system's information, usually system vendor (svn) 207and product name (pn). 208 209Once in place, run the following command to verify the quirk is valid and 210works for your device: :: 211 212 $ sudo libinput list-quirks /dev/input/event10 213 AttrTouchSizeRange=10:8 214 215Replace the event node with the one from your device. If the 216``AttrTouchSizeRange`` quirk does not show up, re-run with ``--verbose`` and 217check the output for any error messages. 218 219If the touch size range property shows up correctly, restart X or the 220Wayland compositor and libinput should now use the correct thresholds. 221The :ref:`tools` can be used to verify the correct functionality first without 222the need for a restart. 223 224Once the touch size ranges are deemed correct, :ref:`reporting_bugs` "report a 225bug" to get the thresholds into the repository. 226 227