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