From c727ee7f23b3b256abd77c80b56dbf28285cca3e Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Wed, 29 Nov 2017 11:30:54 +1000 Subject: [PATCH] doc: add a doc for trackpoints --- doc/faqs.dox | 6 ++ doc/page-hierarchy.dox | 1 + doc/trackpoints.dox | 164 +++++++++++++++++++++++++++++++++++++++++ meson.build | 1 + 4 files changed, 172 insertions(+) create mode 100644 doc/trackpoints.dox diff --git a/doc/faqs.dox b/doc/faqs.dox index 1d5ff3b1..1dcdca29 100644 --- a/doc/faqs.dox +++ b/doc/faqs.dox @@ -17,6 +17,12 @@ This is a symptom of high-dpi mice (greater than 1000dpi). These devices need a udev hwdb entry to normalize their motion. See @ref motion_normalization for a detailed explanation. +@section faq_fast_trackpoint My trackpoint moves too slow or too fast + +This is a symptom of an invalid trackpoint range. These devices need a udev +hwdb entry to specify the range available so libinput can adjust the pointer +acceleration accordingly. See @ref trackpoint_range for a detailed explanation. + @section faq_enable_tapping Why isn't touchpad tap-to-click enabled by default See @ref tapping_default diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox index edff4d43..5d412536 100644 --- a/doc/page-hierarchy.dox +++ b/doc/page-hierarchy.dox @@ -20,6 +20,7 @@ - @subpage motion_normalization - @subpage middle_button_emulation - @subpage button_debouncing +- @subpage trackpoints @page tablets Graphics Tablets diff --git a/doc/trackpoints.dox b/doc/trackpoints.dox new file mode 100644 index 00000000..e09c3c6e --- /dev/null +++ b/doc/trackpoints.dox @@ -0,0 +1,164 @@ +/** +@page trackpoints Trackpoints and Pointing Sticks + +This page provides an overview of trackpoint handling in libinput, also +refered to as Pointing Stick or Trackstick. The device itself is usually a +round plastic stick between the G, H and B keys with a set of buttons below +the space bar. + +@image html button-scrolling.svg "A trackpoint" + +libinput always treats the buttons below the space bar as the buttons that +belong to the trackpoint even on the few laptops where the buttons are not +physically wired to the trackpoint device anyway, see @ref t440_support. + +Trackpoint devices have @ref button_scrolling enabled by default. This may +interfer with middle-button dragging, if middle-button dragging is required +by a user then button scrolling must be disabled. + +@section trackpoint_range Motion range on trackpoints + +It is difficult to associate motion on a trackpoint with a physical +reference. Unlike mice or touchpads where the motion can be +measured in mm, the trackpoint only responds to pressure. Without special +equipment it is impossible to measure identical pressure values across +multiple laptops. + +The values provided by a trackpoint are motion deltas, usually corresponding +to the pressure applied to the trackstick. For example, pressure towards the +screen on a laptop provides negative y deltas at a fixed rate (e.g. every +10ms). As the pressure increases, the delta increases too. As the pressure +decreases, the delta decreases until it hits the neutral state. + +The delta range itself can vary greatly between laptops, some devices send a +maximum delta value of 30, others can go beyond 100. To normalize the motion +trackpoint, libinput uses the available delta range and fits its +acceleration curve into this range. This requires calibration by the user, +see @ref trackpoint_range_measure. + +@section trackpoint_range_measure Measuring the trackpoint range + +This section describes how to measure the trackpoint range and apply a hwdb +entry to make this range known to libinput. libinput provides the tool +`libinput measure trackpoint-range` for this task. This is an interactive +tool and prints its instructions on the commandline. Example output from +this tool is below: + +@code +$ sudo libinput measure trackpoint-range +This tool measures the commonly used pressure range of the +trackpoint. Push the trackpoint: +- Four times around the screen edges +- From the top left to the bottom right and back, twice +- From the top right to the bottom left and back, twice +A minimum of 1000 events for each axis is required + +Movements should emulate fast pointer movement on the screen +but not use excessive pressure that would not be used +during day-to-day movement. For best results, run this tool +several times to get an idea of the common range. + +Trackpoint sends: max x: 19, max y: 23 samples [121, 121] +@endcode + +Once sufficient samples have been collected, the tool prints a simplified +histogram for x and y axis deltas. This histogram should be used to +estimate the appropriate trackpoint range. For example, let's look at +the histogram below: + +@code +Histogram for x axis deltas, in counts of 5 + -30: + -29: + -28: + + -27: + + -26: ++ + -25: ++++ + -24: +++++ + -23: ++ + -22: ++++++ + -21: +++ + -20: ++++ + -19: +++++++ + -18: ++++++++++++ + -17: ++++++++++++ + -16: ++++++++++++ + -15: ++++ + -14: +++++ + -13: +++++ + -12: ++++++ + -11: +++++ + -10: +++ + -9: ++++ + -8: +++++++ + -7: +++++++ + -6: ++++++++++++ + -5: ++++++++++++ + -4: ++++++++++++ + -3: +++++++++ + -2: +++++++++ + -1: ++++++++ + 0: +++++++ + 1: +++++ + 2: +++++ + 3: ++++++ + 4: ++++++ + 5: +++++++ + 6: ++++ + 7: ++ + 8: +++ + 9: +++ + 10: +++ + 11: +++ + 12: +++ + 13: ++++ + 14: ++++++ + 15: ++++ + 16: ++++ + 17: ++++ + 18: ++++++ + 19: +++++++ + 20: ++++ + 21: ++++++ + 22: ++++++ + 23: ++++++ + 24: ++++++ + 25: +++++++++ + 26: +++++++ + 27: ++++++++ + 28: +++++ + 29: ++ + 30: ++ + 31: + + 32: + 33: + 34: +@endcode + +The 0 delta is the neutral state, each + represents 5 events with that +delta value. Note how the curve is distributed, it's not a classic bell +curve. That can be a factor of the input provided or the firmware-based +pointer acceleration. + +Overall, the majority of events appear to be in the 0-25 range with a few +outliers. So the trackpoint range libinput should use for this particular +device would be 25. Note how there is a fair bit of guesswork involved, a +trackpoint's data is never clean enough to get a definitive value. It is +generally better to take a (slightly) smaller range than one too large. + +The hwdb entry for the above should thus be: +@code +libinput:name:TPPS/2 IBM TrackPoint:dmi:bvn*:bvr*:bd*:svnLENOVO:pn*:pvrThinkPadT440:* + LIBINPUT_ATTR_TRACKPOINT_RANGE=25 +@endcode + +The first line contains the device name and an abbreviated version of the +dmi modalias (see `/sys/class/dmi/id/modalias/`). This dmi string should be +abbreviated to be as generic as possible (hence the *) but specific enough +to match the laptop model. + +See @ref faq_hwdb_changes for instructions on how to add this match to the +system. + +*/ + diff --git a/meson.build b/meson.build index 13c6a27f..35419ccb 100644 --- a/meson.build +++ b/meson.build @@ -291,6 +291,7 @@ if get_option('documentation') meson.source_root() + '/doc/touchpad-jumping-cursors.dox', meson.source_root() + '/doc/touchpad-pressure.dox', meson.source_root() + '/doc/touchpads.dox', + meson.source_root() + '/doc/trackpoints.dox', meson.source_root() + '/doc/what-is-libinput.dox', # dot drawings meson.source_root() + '/doc/dot/seats-sketch.gv',