Haptics

Haptics

Haptics are usually taken for granted on devices, they make it easier to tell if your finger has hit the keyboard when typing, and generally add a new dimension of UX.

Device Support

Non-SoC haptic drivers:

• GPIO vibrator uses a simple GPIO line to provide a vibrating feedback
• Regulator Haptic uses a regulator
• PWM vibrator uses a PWM
• MAX77693 vibrator - an MFD that includes haptic support

The following SoCs support haptics:

TODO: Add haptics to the support list and make this list automatic

• MSM8916 (and newer related SoCs?) (drivers/input/misc/pm8xxx-vibrator.c)
• MSM8996 - SDM845 (pmi8998_haptics.c) drivers/input/misc/pmi8998-haptics.c <- the driver is not yet upstream, a version can be found here.

If your device uses one of MSM8996, MSM8998, SDM845, you can use this WIP haptics driver (and associated dts node). You will have to find the correct play-rate for your device and fill it out like this.

Currently only the buffer play mode and LRA (Linear Resonant Actuator) are supported, contributions welcome! For more detailed information on how the haptics hardware works, see the bottom of this page.

You can test the haptics device using fftest which is part of the linuxconsoletools package.

Software Support

feedbackd

Once your hardware is up and running, copy the /usr/share/feedbackd/themes/pine,pinephone.json file and adjust it to match the DTS compatible line for your device (e.g. oneplus,enchilada.json).

In order for feedbackd to detect your haptics hardware, you need to add a new udev rule, below is the rule for pmi8998_haptics.

/usr/lib/udev/rules.d/90-feedbackd.rules

SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT}=="1", ATTRS{name}=="pmi8998_haptics", TAG+="uaccess", ENV{FEEDBACKD_TYPE}="vibra"

After this, run

# udevadm control --reload-rules
# udevadm trigger --attr-match=subsystem=input

This will find the haptics input device and add the ENV{FEEDBACKD_TYPE}="vibra" property for feedbackd.

With the above changes, you should now feel ForceFeedback in Phosh!

Tweak your feedbackd theme file to work well with your device, then upstream it to feedbackd-device-themes.

hfd-service

hfd-service is used by Lomiri (previously known as Unity8). It is now supported by Alpine Linux. Support for forcefeedback vibrators is added by this PR. The Manjaro ARM unstable branch also currently has these patches.

hfd-service automatically detects the first input device that supports forcefeedback and uses it for haptics.

fftest

The program fftest from the alpine package linuxconsoletools can be used to test a haptic device if you have a driver for it. For a device with a max77693 mfd responsible for the vibrations, fftest checks for possible vibration pattern modes and lets you select which one to run:

$ fftest /dev/input/by-path/platform-i2c-gpio-1-platform-max77693-haptic-event 
Force feedback test program.
HOLD FIRMLY YOUR WHEEL OR JOYSTICK TO PREVENT DAMAGES

Device /dev/input/by-path/platform-i2c-gpio-1-platform-max77693-haptic-event opened
Features:
  * Absolute axes: 
    [00 00 00 00 00 00 00 00 ]
  * Relative axes: 
    [00 00 ]
  * Force feedback effects types: Periodic, Rumble, Gain, 
    Force feedback periodic effects: Square, Triangle, Sine, 
    [00 00 00 00 00 00 00 00 00 00 03 07 01 00 00 00 ]
  * Number of simultaneous effects: 16

Setting master gain to 75% ... OK
Uploading effect #0 (Periodic sinusoidal) ... OK (id 0)
Uploading effect #1 (Constant) ... Error: Invalid argument
Uploading effect #2 (Spring) ... Error: Invalid argument
Uploading effect #3 (Damper) ... Error: Invalid argument
Uploading effect #4 (Strong rumble, with heavy motor) ... OK (id 1)
Uploading effect #5 (Weak rumble, with light motor) ... OK (id 2)
Enter effect number, -1 to exit
0
Now Playing: Sine vibration

See also

• WIP pmi8998 haptics driver
• pmaports!2002 to add udev rule for feedbackd to sdm845 common package
• PR to add support for forcefeedback to hfd-service
• Caleb's documentation on pmi8998 haptics