Hello,
This is an updated implementation of the interface for controlling haptic
touchpads.
Below is an updated design proposal for the userspace and HID interfaces,
modified from what one of my colleagues submitted in 2019 [0].
We would appreciate any feedback you might have.
Thank you,
Jonathan Denose
Chromium OS Team
Background
==========
There are multiple independent projects to develop a touchpad with force sensors
and haptic actuators, instead of a traditional button. These haptic touchpads
have several advantages and potential uses; they allow clicking across the
entire touchpad surface, adjusting the force requirement for clicks, haptic
feedback initiated by UI, etc. Supporting these features will potentially
require two new communication channels at the kernel level:
* Control of haptic motor by the host
* Force sensor data from device to host
This document includes two related proposals:
1. HID design proposal, that hardware makers would need to implement
2. Kernel design proposal
Objective
==========
Develop a standard protocol to allow userspace applications to communicate with
haptic touchpads, and minimize duplicated code and effort.
Requirements:
1. Support UI-initiated haptic feedback.
2. Allow userspace to control when button press and button release haptic
effects are triggered. (Useful when detecting a false click, changing force
thresholds, or sending context-dependent effects).
3. Reveal force sensor readings to userspace applications.
4. Only allow OS-controlled haptic feedback for those systems which support it.
Proposal
========
In order to minimize duplicated effort, we propose standardized haptic touchpad
support in the linux kernel.
HID API
-------
Modes
.....
The haptic touchpad should be able to operate under two different modes.
1. Device-controlled mode
The haptic touchpad should start up in "device-controlled mode"
(HID_HAPTIC_MODE_DEVICE), meaning it acts as a normal touchpad. This means it
should perform the press and release haptic feedback autonomously at predefined
force thresholds, and send the appropriate BTN_* events.
2. Host-controlled mode
Once the touchpad has been confirmed as supporting haptics (described in more
detail in the the "Click and release control" section below), the device should
enter "host-controlled mode" (HID_HAPTIC_MODE_HOST). In this mode userspace
should take control. From here, userspace will take control over
press/release haptic feedback, relying on the effects sent by the kernel.
Multitouch
..........
The HID API for multitouch reports should follow the Microsoft precision
touchpad spec [1], with the following changes:
* A tip pressure field [2] should be used to report the force. The physical unit
Type (Newtons or grams), exponent, and limits should be reported in the
report descriptor for the force field.
* The device will always report the button state according to its predefined
force thresholds, even when not in device-controlled mode.
* The device must expose a "simple haptic controller" logical collection
alongside the touchpad collection.
Haptic control
..............
The HID protocol described in HUTRR63[3] must be used.
The following waveforms should be supported:
| WAVEFORMNONE | Implicit waveforms required by protocol |
| WAVEFORMSTOP | |
| ------------------------ | ------------------------------------------------- |
| WAVEFORMPRESS | To be used to simulate button press. In device- |
| | controlled mode, it will also be used to simulate |
| | button release. |
| ------------------------ | ------------------------------------------------- |
| WAVEFORMRELEASE | To be used to simulate button release. |
All waveforms will have an associated duration; continuous waveforms will be
ignored by the kernel.
Triggers & Mode switching
.........................
The “auto trigger waveform” should be set to WAVEFORM_PRESS by default, and the
button from the touchpad collection should be set as the “auto trigger
associated control”.
The kernel can trigger the different modes in the following ways:
* Device-controlled mode can be enabled by setting the “auto trigger waveform” to
WAVEFORM_PRESS.
* Host-controlled mode can be enabled by setting the "auto trigger waveform" to
WAVEFORM_STOP.
The device must also support manual triggering. If intensity modification for
waveforms is supported by the device, the intensity control should be included
in the manual trigger output report. This allows modification of the intensity
on a per-waveform basis. Retriggering does not need to be supported by the
device.
Userspace API
-------------
Multitouch protocol
...................
ABS_MT_PRESSURE will be used to report force. The resolution of ABS_MT_PRESSURE
should also be defined and reported in force units of grams or Newtons.
ABS_PRESSURE should be reported as the total force applied to the touchpad.
When the kernel is in host-controlled mode, it should always forward the button
press and release events to userspace.
Use Force Feedback protocol to request pre-defined effects
..........................................................
The force feedback protocol [4] should be used to control predefined effects.
Typical use of the force feedback protocol requires loading effects to the
driver by describing the output waveform, and then requesting those effects
using an ID provided by the driver. However, for haptic touchpads we do not want
to describe the output waveform explicitly, but use a set of predefined effects,
which are identified by HID usage.
The force feedback protocol will need to be extended to allow requests for HID
haptic effects. This requires a new feedback effect type:
/**
* struct ff_haptic_effect
* @hid_usage: hid_usage according to Haptics page (WAVEFORM_CLICK, etc.)
* @vendor_id: the waveform vendor ID if hid_usage is in the vendor-defined
* range
* @vendor_id: the vendor waveform page if hid_usage is in the vendor-defined
* range
* @intensity: strength of the effect
* @repeat_count: number of times to retrigger effect
* @retrigger_period: time before effect is retriggered (in ms)
*/
struct ff_haptic_effect {
__u16 hid_usage;
__u16 vendor_id;
__u8 vendor_waveform_page;
__s16 intensity;
__u16 repeat_count;
__u16 retrigger_period;
}
Since the standard waveform id namespace does not overlap with the vendor
waveform id namespace, the vendor id and page can be ignored for standard
waveforms.
Click and release control
.........................
Haptic functionality shall be gated behind the HID_MULTITOUCH_HAPTIC kernel
configuration option, and this kernel configuration option should only be
enabled if userspace will support haptic capabilities. Haptic functionality will
only be initialized and used if HID_MULTITOUCH_HAPTIC is enabled, and if the
following conditions have been met:
* ABS_MT_PRESSURE is defined and reporting force units of Newtons or grams.
* The device supports haptic effects according to the hid protocol defined in
HUTRR63 [3].
These checks will happen when the driver probes and initializes the multitouch
device.
In the case when the kernel configuration option has been set and the device
reports pressure and haptic effects as defined above, the kernel will initialize
the haptic device and configure the haptic driver to signal that the touchpad is
haptic-compatible. To signal to userspace that the touchpad is haptic-compatible
the kernel will mark INPUT_PROP_HAPTIC_TOUCHPAD.
With userspace willing and able to take control, the kernel will signal to the
device to exit device-controlled mode once a WAVEFORMPRESS or WAVEFORMRELEASE
event is uploaded. From here, userspace will take control over press/release
haptic feedback, relying on the effects sent by the kernel.
In all other cases, the driver will take no action to enable haptic
functionality.
Summary of normal use-case
1. The kernel waits for userspace to upload WAVEFORMPRESS or
WAVEFORMRELEASE.
2. Userspace determines when a click has been performed based on its own
criteria and tells the touchpad to perform a haptic effect.
3. When userspace erases the WAVEFORMPRESS or WAVEFORMRELEASE effect, signal the
device to return to device-controlled mode.
[0]: https://www.spinics.net/lists/linux-input/msg60938.html
[1]: https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/touchpad-devices
[2]: Usage ID 0x30 of HID usage table 0x0D. See chapter 16:
https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
[3]: https://www.usb.org/sites/default/files/hutrr63b_-_haptics_page_redline_0.pdf
[4]: https://www.kernel.org/doc/html/v4.20/input/ff.html
Signed-off-by: Jonathan Denose <jdenose@xxxxxxxxxx>
---
Changes in v2:
- Rename FF_HID and ff_hid_effect to FF_HAPTIC and ff_haptic_effect
- Add more detail to CONFIG_HID_HAPTIC config option description
- Remove CONFIG_MULTITOUCH_HAPTIC config option
- Utilize devm api in hid-multitouch haptic functions
- Link to v1: https://lore.kernel.org/all/20250714-support-forcepads-v1-0-71c7c05748c9@xxxxxxxxxx
---
Angela Czubak (11):
HID: add haptics page defines
Input: add FF_HAPTIC effect type
Input: add INPUT_PROP_HAPTIC_TOUCHPAD
HID: haptic: introduce hid_haptic_device
HID: input: allow mapping of haptic output
HID: haptic: initialize haptic device
HID: input: calculate resolution for pressure
HID: haptic: add functions handling events
Input: MT - add INPUT_MT_TOTAL_FORCE flags
HID: haptic: add hid_haptic_switch_mode
HID: multitouch: add haptic multitouch support
Documentation/input/event-codes.rst | 14 +
drivers/hid/Kconfig | 11 +
drivers/hid/Makefile | 1 +
drivers/hid/hid-haptic.c | 580 +++++++++++++++++++++++++++++++++
drivers/hid/hid-haptic.h | 131 ++++++++
drivers/hid/hid-input.c | 18 +-
drivers/hid/hid-multitouch.c | 47 +++
drivers/input/input-mt.c | 14 +-
include/linux/hid.h | 29 ++
include/linux/input/mt.h | 1 +
include/uapi/linux/input-event-codes.h | 1 +
include/uapi/linux/input.h | 22 +-
12 files changed, 862 insertions(+), 7 deletions(-)
---
base-commit: 86731a2a651e58953fc949573895f2fa6d456841
change-id: 20250625-support-forcepads-0b4f74fd3d0a
Best regards,
--
Jonathan Denose <jdenose@xxxxxxxxxx>
