diff options
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/faqs.dox | 5 | ||||
| -rw-r--r-- | doc/page-hierarchy.dox | 1 | ||||
| -rw-r--r-- | doc/touchpad-pressure.dox | 138 |
4 files changed, 145 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 8af0f33..5391f22 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -29,6 +29,7 @@ header_files = \ $(srcdir)/test-suite.dox \ $(srcdir)/tools.dox \ $(srcdir)/touchpad-jumping-cursors.dox \ + $(srcdir)/touchpad-pressure.dox \ $(srcdir)/touchpads.dox \ $(srcdir)/what-is-libinput.dox diff --git a/doc/faqs.dox b/doc/faqs.dox index 0b8db83..7820ad4 100644 --- a/doc/faqs.dox +++ b/doc/faqs.dox @@ -15,6 +15,11 @@ motion_normalization for a detailed explanation. See @ref tapping_default +@section faq_touchpad_pressure Why does my touchpad lose track of touches + +The most common cause for this is an incorrect pressure threshold range. +See @ref touchpad_pressure for more info. + @section faq_kinetic_scrolling Kinetic scrolling does not work The X.Org synaptics driver implemented kinetic scrolling in the driver. It diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox index ebfb65c..65749fe 100644 --- a/doc/page-hierarchy.dox +++ b/doc/page-hierarchy.dox @@ -5,6 +5,7 @@ - @subpage clickpad_softbuttons - @subpage tapping - @subpage gestures +- @subpage touchpad_pressure - @subpage palm_detection - @subpage t440_support - @subpage touchpad_jumping_cursor diff --git a/doc/touchpad-pressure.dox b/doc/touchpad-pressure.dox new file mode 100644 index 0000000..7c55c9f --- /dev/null +++ b/doc/touchpad-pressure.dox @@ -0,0 +1,138 @@ +/** +@page touchpad_pressure Touchpad pressure-based touch detection + +libinput uses the touchpad pressure values to detect wether a finger has +been placed on the touchpad. This is @ref kernel_pressure_information and +combines with a libinput-specific hardware database to adjust the thresholds +on a per-device basis. libinput uses pressure thresholds primarily to filter +out accidental light touches but pressure information is also used for +some @ref palm_detection. + +Pressure thresholds are **not** directly configurable by the user, rather it +is planned that libinput provides custom pressure thresholds for each device +where necessary. See @ref touchpad_pressure_hwdb for instructions for your +local device. + +@section kernel_pressure_information Information provided by the kernel + +The kernel sends multiple values to inform userspace about a finger touching +the touchpad. The most basic is the ```EV_KEY/BTN_TOUCH``` boolean event +that simply announces physical contact with the touchpad. The decision when +this event is sent is usually made by the kernel driver and may depend on +device-specific thresholds. These thresholds are transparent to userspace +and cannot be modified. + +Many contemporary touchpad devices provide an absolute pressure axis in +addition to ```BTN_TOUCH```. This pressure generally increases as the pressure +increases, however few touchpads are capable of detection pressure. The +pressure value is usually related to the covered area - as the pressure +increases a finger flattens and thus covers a larger area. The range +provided by the kernel is not mapped to a specific physical range and +often requires adjustment. Pressure is sent by the ```ABS_PRESSURE``` axis +for single-touch touchpads or ```ABS_MT_PRESSURE``` on multi-touch capable +touchpads. + +Some devices provide additional touch size information through +the ```ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR``` axes and/or +the ```ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR``` axes. While the kernel +documentation specifies how these axes are supposed to be mapped, few +devices forward +reliable information. + +@section touchpad_pressure_hwdb Debugging touchpad pressure ranges + +This section describes how to determine the touchpad pressure ranges +required for a touchpad device and how to add the required hwdb entry +locally. Note that the hwdb entry is **not public API** and **may change at +any time**. Users are advised to @ref reporting_bugs "report a bug" with the +updated pressure ranges when testing has completed. + +First, install the "evemu" package providing the ```evemu-record``` tool. +Run ```evemu-record``` as root (without arguments) to see a list of devices +and select the touchpad device. Pipe the actual output of the tool into a +file for later analysis. For example: + +<pre> +$ sudo evemu-record > touchpad-pressure.txt +Available devices: +/dev/input/event0: Lid Switch +/dev/input/event1: Sleep Button +/dev/input/event2: Power Button +/dev/input/event3: AT Translated Set 2 keyboard +/dev/input/event4: SynPS/2 Synaptics TouchPad +/dev/input/event5: ELAN Touchscreen +[...] +Select the device event number [0-19]: 4 +# Ctrl+C to quit, the output will be in touchpad-pressure.txt +</pre> + +Now move a finger at **normal pressure** several times around the touchpad, +as if moving the cursor normally around the screen. Avoid any accidental +palm touches or any excessive or light pressure. + +The event recording is then filtered for pressure information, which is +sorted and exported to a new file: +<pre> +$ grep --only-matching "ABS_MT_PRESSURE[ ]*[0-9]*" touchpad-pressure.txt | \ + sed -e "s/ABS_MT_PRESSURE[ ]*//" | \ + sort -n | uniq -c > touchpad-pressure-statistics.txt +</pre> + +The file contains a list of (count, pressure-value) tuples which can be +visualized with gnuplot. Copy the following into a file named +```touchpad-pressure-statistics.gnuplot```: + +<pre> +set style data lines +plot 'touchpad-pressure-statistics.txt' using 2:1 +pause -1 +</pre> + +Now, you can visualize the touchpad pressure curve with the following +command: +<pre> +$ gnuplot touchpad-pressure-statistics.gnuplot +</pre> + +The visualization will show a curve with the various pressure ranges, see +[this bugzilla attachment](https://bugs.freedesktop.org/attachment.cgi?id=130659). +In most cases, the thresholds can be guessed based on this curve. libinput +employes a [Schmitt trigger](https://en.wikipedia.org/wiki/Schmitt_trigger) +with an upper threshold and a lower threshold. A touch is detected when the +pressure goes above the high threshold, a release is detected when the +pressure fallse below the low threshold. Thus, an ideal threshold +combination is with a high threshold slightly above the minimum threshold, a +low threshold on the minimum threshold. + +Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with +the following hwdb file: + +<pre> +$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb +libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p* + LIBINPUT_ATTR_PRESSURE_RANGE=10:8 +</pre> + +The first line is the match line and should be adjusted for the device name +(see evemu-record's output) and for the local system, based on the +information in ```/sys/class/dmi/id/modalias```. The modalias should be +shortened to the specific system's information, usually system vendor (svn) +and product name (pn). + +Once in place, you need to run the following to commands, adjusted for your +device's event node (see @ref faq_hwdb_changes): +<pre> + sudo udevadm hwdb --update + sudo udevadm test /sys/class/input/eventX +</pre> + +If the pressure range property shows up correctly, restart X or the +Wayland compositor and libinput should now use the correct pressure +thresholds. The @ref developer_tools can be used to verify the correct +functionality first without the need for a restart. + +Once the pressure ranges are deemed correct, +@ref reporting_bugs "report a bug" to get the pressure ranges into the +repository. + +*/ |