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 https://github.com/torvalds/linux/blob/master/drivers/input/misc/gpio-vibra.c uses a simple GPIO line to provide a vibrating feedback
* Regulator Haptic https://github.com/torvalds/linux/blob/master/drivers/input/misc/regulator-haptic.c uses a regulator
* PWM vibrator https://github.com/torvalds/linux/blob/master/drivers/input/misc/gpio-vibra.c uses a PWM
* MAX77693 vibrator https://github.com/torvalds/linux/blob/master/drivers/mfd/max77693.c - an MFD that includes haptic support
The following SoCs support haptics:
* 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.
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
* 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
== References ==
Category:Hardware
Category:Technical Reference