• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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     &nbsp;
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     &nbsp;
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