Add amplitude control to vibrator HAL
Providing control over the strength of the vibration allows the platform
to provide a richer haptic experience to users. How this amplitude is
modulated is left up to the vibrator implementation.
This also adds an interface to ask the HAL to perform specific haptic
effects. By exposing the intent of the haptic event to the HAL, we can
let device and haptic driver manufacturers implement custom waveforms
that more closely match the desired effect.
Test: Manual testing with Marlin HAL +
adb shell /data/nativetest/vibrator_hidl_hal_test/vibrator_hidl_hal_test
Change-Id: Icfccb464c6c85adecdf354e2bd4cf422d7d31eb5
diff --git a/vibrator/1.0/IVibrator.hal b/vibrator/1.0/IVibrator.hal
index 0a4ffca..757ad0d 100644
--- a/vibrator/1.0/IVibrator.hal
+++ b/vibrator/1.0/IVibrator.hal
@@ -17,7 +17,8 @@
package android.hardware.vibrator@1.0;
interface IVibrator {
- /** Turn on vibrator
+ /**
+ * Turn on vibrator
*
* This function must only be called after the previous timeout has expired or
* was canceled (through off()).
@@ -26,10 +27,46 @@
*/
on(uint32_t timeoutMs) generates (Status vibratorOnRet);
- /** Turn off vibrator
+ /**
+ * Turn off vibrator
*
* Cancel a previously-started vibration, if any.
* @return vibratorOffRet whether vibrator command was successful or not.
*/
off() generates (Status vibratorOffRet);
+
+ /**
+ * Returns whether the vibrator supports changes to its vibrational amplitude.
+ */
+ supportsAmplitudeControl() generates (bool supports);
+
+ /**
+ * Sets the motor's vibrational amplitude.
+ *
+ * Changes the force being produced by the underlying motor.
+ *
+ * @param amplitude The unitless force setting. Note that this number must
+ * be between 1 and 255, inclusive. If the motor does not
+ * have exactly 255 steps, it must do it's best to map it
+ * onto the number of steps it does have.
+ * @return status Whether the command was successful or not. Must return
+ * Status::UNSUPPORTED_OPERATION if setting the amplitude is
+ * not supported by the device.
+ */
+ setAmplitude(uint8_t amplitude) generates (Status status);
+
+ /**
+ * Fire off a predefined haptic event.
+ *
+ * @param event The type of haptic event to trigger.
+ * @return status Whether the effect was successfully performed or not. Must
+ * return Status::UNSUPPORTED_OPERATION is the effect is not
+ * supported.
+ * @return lengthMs The length of time the event is expected to take in
+ * milliseconds. This doesn't need to be perfectly accurate,
+ * but should be a reasonable approximation. Should be a
+ * positive, non-zero value if the returned status is
+ * Status::OK, and set to 0 otherwise.
+ */
+ perform(Effect effect, EffectStrength strength) generates (Status status, uint32_t lengthMs);
};