Re: [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams

[Benjamin Tissoires <benjamin.tissoires@gmail.com>]

On Wed, Jan 13, 2021 at 12:03 AM Peter Hutterer
<peter.hutterer@who-t.net> wrote:
>
> ABS_PRESSURE and ABS_MT_PRESSURE on touch devices usually represent
> contact size (as a finger flattens with higher pressure the contact size
> increases) and userspace translates the kernel pressure value back into
> contact size. For example, libinput has pressure thresholds when a touch is
> considered a palm (palm == large contact area -> high pressure). The values
> themselves are on an arbitrary scale and device-specific.
>
> On pressurepads however, the pressure axis may represent the real physical
> pressure. Pressurepads are touchpads without a hinge but an actual pressure
> sensor underneath the device instead, for example the Lenovo Yoga 9i.
>
> A high-enough pressure is converted to a button click by the firmware.
> Microsoft does not require a pressure axis to be present, see [1], so as seen
> from userspace most pressurepads are identical to clickpads - one button and
> INPUT_PROP_BUTTONPAD set.
>
> However, pressurepads that export the pressure axis break userspace because
> that axis no longer represents contact size, resulting in inconsistent touch
> tracking, e.g. [2]. Userspace needs to know when a pressure axis represents
> real pressure and the best way to do so is to define what the resolution
> field means. Userspace can then treat data with a pressure resolution as
> true pressure.
>
> This patch documents that the pressure resolution is in units/gram. This
> allows for fine-grained detail and tops out at roughly ~2000t, enough for the
> devices we're dealing with. Grams is not a scientific pressure unit but the
> alternative is:
> - Pascal: defined as force per area and area is unreliable on many devices and
>   seems like the wrong option here anyway, especially for devices with a
>   single pressure sensor only.
> - Newton: defined as mass * distance/acceleration and for the purposes of a
>   pressure axis, the distance is tricky to interpret and we get the data to
>   calculate acceleration from event timestamps anyway.
>
> For the purposes of touch devices and digitizers, grams seems the best choice
> and the easiest to interpret.
>
> Bonus side effect: we can use the existing hwdb infrastructure in userspace to
> fix devices that advertise false pressure.
>
> [1] https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required-hid-top-level-collections#windows-precision-touchpad-input-reports
> [2] https://gitlab.freedesktop.org/libinput/libinput/-/issues/562
>
> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

FWIW, and because I was involved in the initial discussion:
Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>

Cheers,
Benjamin

> ---
>  Documentation/input/event-codes.rst          | 15 +++++++++++++++
>  Documentation/input/multi-touch-protocol.rst |  4 ++++
>  2 files changed, 19 insertions(+)
>
> diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
> index b24b5343f5eb..3118fc1c1e26 100644
> --- a/Documentation/input/event-codes.rst
> +++ b/Documentation/input/event-codes.rst
> @@ -236,6 +236,21 @@ A few EV_ABS codes have special meanings:
>    - Used to describe multitouch input events. Please see
>      multi-touch-protocol.txt for details.
>
> +* ABS_PRESSURE/ABS_MT_PRESSURE:
> +
> +   - For touch devices, many devices converted contact size into pressure.
> +     A finger flattens with pressure, causing a larger contact area and thus
> +     pressure and contact size are directly related. This is not the case
> +     for other devices, for example digitizers and touchpads with a true
> +     pressure sensor ("pressure pads").
> +
> +     A device should set the resolution of the axis to indicate whether the
> +     pressure is in measurable units. If the resolution is zero, the
> +     pressure data is in arbitrary units. If the resolution is nonzero, the
> +     pressure data is in units/gram. For example, a value of 10 with a
> +     resolution of 1 represents 10 gram, a value of 10 with a resolution on
> +     1000 represents 10 microgram.
> +
>  EV_SW
>  -----
>
> diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst
> index 307fe22d9668..21c1e6a22888 100644
> --- a/Documentation/input/multi-touch-protocol.rst
> +++ b/Documentation/input/multi-touch-protocol.rst
> @@ -260,6 +260,10 @@ ABS_MT_PRESSURE
>      of TOUCH and WIDTH for pressure-based devices or any device with a spatial
>      signal intensity distribution.
>
> +    If the resolution is zero, the pressure data is in arbitrary units.
> +    If the resolution is nonzero, the pressure data is in units/gram. See
> +    :ref:`input-event-codes` for details.
> +
>  ABS_MT_DISTANCE
>      The distance, in surface units, between the contact and the surface. Zero
>      distance means the contact is touching the surface. A positive number means
> --
> 2.29.2
>