Debian Codegraph @

doc/user/touchpad-pressure-debugging.rst

raw
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 &nbsp;
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 &nbsp;
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.