Implement piecewise linear envelope effects

Stay organized with collections Save and categorize content based on your preferences.

Piecewise linear envelope (PWLE) effects are sequences of points defining vibration frequency and acceleration over time. PWLEs offer richer and more dynamic haptic feedback.

Android 16 and higher provides two app developer APIs to help create PWLE effects:

• Basic PWLE API: Simple, but with limitations. Good for getting started quickly. This is available at BasicEnvelopeBuilder.
• Advanced PWLE API: More control and flexibility, requires haptics knowledge and some familiarity with hardware. Available at WaveformEnvelopeBuilder.

To support these APIs, devices are required to implement the following HAL APIs:

• Frequency to output acceleration mapping (FOAM): Provides a mapping of vibration frequency to maximum achievable output acceleration for the device.
• Compose PWLE: Plays a vibration defined by a PWLE of the vibration waveform.

Basic PWLE API

For a quick way to create PWLE effects without diving into the hardware or nuances of human perception, developers can use the basic PWLE API, defined using these parameters:

• Intensity value in the range of [0, 1] represents the perceived strength of the vibration. For example, a 0.5 value is perceived as half the global maximum intensity that can be achieved by the device.
• Sharpness value in the range of [0, 1] represents the crispness of the vibration. Lower values translate to smoother vibrations, while higher values create a more sharp sensation.
• Duration is the time taken to transition from the last PWLE point (that is, the intensity and sharpness pair) to the new one, in milliseconds.

Here's an example waveform that ramps up the intensity from a low pitch to a high pitch maximum-strength vibration over 500 ms and then ramps down to 0 (off) over 100 ms:

VibrationEffect effect = new VibrationEffect.BasicEnvelopeBuilder()
          .setInitialSharpness(0.0f)
          .addControlPoint(1.0f, 1.0f, 500)
          .addControlPoint(0.0f, 1.0f, 100)
          .build();

Constraints

To create a smooth and seamless haptic experience, PWLE effects must start and end with an intensity of 0.0. The API enforces this by fixing the start intensity at 0 and throws an exception if the end intensity isn't 0. This constraint prevents undesirable dynamic effects in the vibrations due to discontinuities in the amplitude that can negatively impact the user's haptic perception.

To ensure consistent PWLE effect rendering across the Android ecosystem, the framework requires that devices supporting this feature can handle a minimum duration of 10 ms between PWLE points and at least 16 points for PWLE effects. These requirements are enforced by VTS tests, helping ensure reliable PWLE effects across Android devices.

Advanced PWLE API

Developers with advanced knowledge in haptics can define PWLE effects using these criteria:

• Amplitude value in the range of [0, 1] represents the achievable strength at given frequency, as determined by the device FOAM. For example, a 0.5 value generates half the maximum output acceleration that can be achieved at the given frequency.
• Frequency is specified directly in Hertz.
• Duration is the time taken to transition from the last PWLE point to the new one, in milliseconds.

Here's an example waveform that ramps a vibrator from off to full amplitude at 120 Hz over 100 ms, holds that state for 200 ms, and then ramps back down over 100 ms:

VibrationEffect effect = new VibrationEffect.WaveformEnvelopeBuilder()
          .addControlPoint(1.0f, 120f, 100)
          .addControlPoint(1.0f, 120f, 200)
          .addControlPoint(0.0f, 120f, 100)
          .build();

Constraints

The framework doesn't modify the requested frequency and amplitude values provided by the developer but adds a 0 amplitude starting point to ensure a smooth transition.

Developers are responsible for ensuring that the frequency specified in their PWLE effects falls within the device's supported range, as defined by the device's FOAM. If values exceed these limits, the device doesn't play any vibration.

Frequency to output acceleration mapping (FOAM)

Accurate representation of a device's frequency to output acceleration capabilities is essential for supporting the PWLE APIs. This section details the significance of this data, how it's used by PWLE APIs, and the process of generating it.

Understand the mapping

Devices supporting PWLE effects need to provide a frequency to output acceleration map (FOAM). The FOAM is a data structure generated by the HAL that maps the vibration frequency (in Hertz) to the actuator's maximum achievable output acceleration (in G peak) at that frequency. This map is crucial for understanding how vibration output varies for the supported frequency range, and for defining the basic PWLE API.

The following plot shows an example of a FOAM for a typical resonant actuator, with input voltage limited around the resonant frequency to protect the motor:

Figure 1. Example of a FOAM for a typical resonant actuator.

The FOAM serves three key purposes:

• Defining full frequency range: The FOAM defines the device's full frequency range by specifying the minimum and maximum vibration frequencies supported.
• Defining the intensity and sharpness values: The basic PWLE API operates on a human perception scale for intensity and sharpness, which are then mapped to hardware frequency and amplitude parameters using the output acceleration values in the FOAM. This mapping helps ensure that the haptic effects are rendered according to hardware capabilities. The sharpness range is defined by the minimum perceivable threshold and corresponds to the frequencies where the device can produce haptic effects that users can feel. The framework maps the Intensity values to amplitude based on the target output acceleration at the selected frequency. This helps ensure that the selected intensity level is achieved while staying within the device's capabilities.
• Exposing hardware capabilities: The FOAM is exposed to developers in VibratorFrequencyProfile, providing the complete frequency to output acceleration dataset detailing some of the device's haptic capabilities. This data empowers developers using the advanced PWLE API to create custom vibration effects that go beyond the basic intensity and sharpness ranges defined by the framework.

FOAM and basic PWLE API

The FOAM plays a vital role in shaping vibration effects. It's used to calculate the sharpness range for the basic envelope API, ensuring that vibrations are perceptible to the user. This range corresponds to frequencies where the output acceleration is no less than 10 dB above the human perception detection threshold (that is, minimum perceivable level) for each frequency. This ensures that the vibrations are strong enough to be felt.

Additionally, the framework uses the FOAM data to map the intensity and sharpness values used in the basic PWLE API to their corresponding amplitude and frequency values. This mapping helps in producing perceivable haptic feedback across different devices.

VTS tests are in place to ensure devices that support envelope effects have a nonempty frequency range that produces perceivable vibrations. This helps ensure that the device can produce vibrations with sufficient intensity to be clearly felt by users.

FOAM and advanced PWLE API

FOAM is exposed to developers by VibratorFrequencyProfile with the following information:

• Frequency range: Developers can retrieve the device's minimum and maximum supported frequencies, in Hertz, using getMinFrequencyHz and getMaxFrequencyHz, respectively.
• Maximum output acceleration: The device's maximum achievable output acceleration (in G) is available through getMaxOutputAccelerationGs.
• Frequency to output acceleration mapping: getFrequenciesOutputAcceleration provides the frequency to output acceleration mapping as implemented in the HAL.

Developers can use this information when creating envelope effects with the advanced PWLE API. For example, when specifying an output acceleration (in G), they must normalize it to a value within the range [0.0, 1.0], relative to the device's maximum output acceleration.

With the advanced PWLE API, developers can use the entire frequency range, so it's crucial that the provided FOAM data is safe for the vibrator and doesn't exceed its capabilities.

Human perception detection threshold

The human perception detection threshold refers to the minimum acceleration of a vibration that a person can reliably detect. This level varies based on the vibration frequency.

The following plot shows the human haptic perception detection threshold¹, in acceleration, as a function of temporal frequency:

Figure 2. Human haptic perception detection threshold.

So that users can consistently feel the haptic effects, VTS tests validate that devices with envelope capabilities have a frequency range that can produce vibration amplitudes exceeding the human perception detection threshold by 10 dB.

Perceived vibration intensity versus vibration acceleration amplitude

Human perception of vibration intensity (a perception measure) doesn't grow linearly with vibration amplitude (a physical parameter). The PWLE API assumes that when a designer or developer thinks about changes in vibration strength, they expect the perceived intensity to follow a PWLE. Perceived intensity is characterized by sensation level (SL), which is defined as dB above detection threshold at the same frequency. Thus, the vibration acceleration amplitude (in G peak) can be calculated as follows:

\(Amplitude(G) =10^\frac{Amplitude(db)}{20}\)

Where the amplitude dB is the sum of SL and detection threshold (the value along the ordinate in the following plot) at a particular frequency.

This way, the PWLE API ensures that perceived intensity changes linearly between successive pairs of control points.

The following plot shows the vibration acceleration levels² at 10, 20, 30, 40, and 50 dB SL, along with the human haptic perception detection threshold (0 dB SL), as a function of temporal frequency.

Figure 3. Vibration acceleration levels.

Determine the frequency to maximum output acceleration curve

This section provides a general guideline for how to obtain the frequency to maximum output acceleration curve from the device, which you use to generate the FOAM data.

Obtain the maximum voltage curve (V)

V is the maximum voltage that can be safely applied to the vibrator over its operating frequency range. This ensures the vibrator operates within safe limits, preventing damage and maximizing vibration output.

If the hardware includes a voltage limitation feature, use it to directly measure the maximum achievable voltage across the supported frequency range.

Calculate the maximum Acceleration (M)

M is the maximum acceleration, which you can calculate through various methodologies. This section shows one method for devices using linear resonant actuators (LRAs).

This method converts the maximum applied voltage at a given frequency into a corresponding maximum acceleration value, expressed in G peak.

The core equation used for this conversion is:

\(\text{Accel}(w)= (\text{Vsys}\times\text{BLsys}\times\text{Loc_coeff}/\text{Rsys}/\text{MPhone})\times{w^2}/\text{Psys_abs}/{9.81}\)

Where:

Vsys: Actual voltage level applied to the haptic actuator

BLsys: Product of magnetic field strength (B) and conductor length (L) of the vibration motor

Loc_coeff: Location coefficient to convert module level acceleration to phone level acceleration

Rsys: Electrical resistance of the vibration motor coil

MPhone: Mass of the device (for example, phone)

w: Angular frequency (radians per second) of the driving signal, calculated as:

\(w = 2 \pi f\)

Psys_abs: Amplitude response of a second order mass, damper, and spring system, calculated as:

\(\text{Psys_abs} = (\text{Wnsys}^2-w^2)^2+({w}\times(\text{Wnsys}/\text{Qsys}))^2\)

Wnsys: Natural frequency of the vibrating system

Qsys: Quality factor of the vibrating system

Loc_coeff is the ratio of the acceleration measured at the phone level to the acceleration measured at the module level. This ratio is used to convert module-level acceleration readings to equivalent phone-level acceleration readings. At the phone level, due to the angular acceleration of the module movement, the acceleration is amplified, and this coefficient accounts for that type of effect. It's calculated as:

\(\text{Loc_coeff} = \text{phone_acceleration} / \text{module_acceleration}\)

For example, if the module acceleration is 1 g and the phone acceleration is 2.5 g, then Loc_coeff = 2.5. This indicates a 2.5x amplification.

The Android framework takes frequency in the unit of Hertz, so the HAL needs to convert the frequency unit from radians per second to Hertz when generating the FOAM data.

Generate the FOAM curve

Combine the maximum voltage curve (V) and the acceleration calculation (M) to determine the FOAM curve:

• For each frequency (f) in your desired range, find the corresponding maximum voltage V(f) from your maximum voltage curve.
• Calculate the maximum acceleration at that frequency using the equation above, substituting V(f) for Vsys and the corresponding f for w. This gives you M(V(f), f).
• This calculated acceleration is your FOAM(f) value.

Expose the FOAM data

After the FOAM curve is generated, the HAL represents the curve as a list of FrequencyAccelerationMapEntry objects. Each entry defines a point in the mapping, specifying a frequency (in Hertz) and its corresponding maximum output acceleration (in G peak).

While there are no strict requirements for the resolution of the FOAM, we recommend defining curves with one maximum peak. Only the first peak is used in the basic envelope API to map the vibration effects. To optimize the accuracy of the linear interpolation when determining intermediate acceleration values, we recommend defining a high frequency resolution around the peak. For example, use 1 Hz steps within the range of +/- 10 Hz of the peak frequency.

Device capabilities and limitations

For Android 16 and higher, to help developers optimize their PWLE effects and ensure compatibility across devices, Android includes HAL APIs for querying the device's PWLE capabilities. These methods provide information about the device's limitations, such as the minimum or maximum PWLE primitive duration and the number of primitives allowed in a PWLE composition.

The HAL APIs include:

• CAP_COMPOSE_PWLE_EFFECTS_V2: Is returned by IVibrator.getCapabilities when the device supports this feature.
• getFrequencyToOutputAccelerationMap: Retrieves the FOAM data.
• getPwleV2PrimitiveDurationMinMillis: Retrieves the minimum duration allowed for any primitive PWLE in milliseconds.
• getPwleV2PrimitiveDurationMaxMillis: Retrieves the maximum duration allowed for any primitive PWLE in milliseconds.
• getPwleV2CompositionSizeMax: Retrieves the maximum number of PWLE primitives supported by IVibrator.composePwleV2.

This information is exposed to developers to let them tailor their effects to the specific capabilities of the target device, especially when using the advanced PWLE API.

The framework also uses these APIs when handling effects created with the basic API. If an effect exceeds the device's limitations (for example, too many PWLE points or a duration exceeding the maximum), the framework automatically adjusts the effect to fit within the allowed boundaries. This adjustment process tries to preserve the original intent and feel of the design as much as possible.