Interfaces for haptic drivers. More...

Topics
	Device-specific Haptics API extensions
	Haptics Driver Backend API

Files
file	haptics.h
	Main header file for haptics driver API.

Data Structures
union	haptics_config
	Haptics source configuration. More...

Typedefs
typedef void(*	haptics_error_callback_t) (const struct device dev, const uint32_t errors, void const user_data)
	Function type of callback invoked when an error occurs.

Enumerations
enum	haptics_error_type { HAPTICS_ERROR_OVERCURRENT = BIT(0) , HAPTICS_ERROR_OVERTEMPERATURE = BIT(1) , HAPTICS_ERROR_UNDERVOLTAGE = BIT(2) , HAPTICS_ERROR_OVERVOLTAGE = BIT(3) , HAPTICS_ERROR_DC = BIT(4) }
	Haptics error types. More...
enum	haptics_monitor { HAPTICS_MONITOR_BEMF , HAPTICS_MONITOR_CURRENT , HAPTICS_MONITOR_F0 , HAPTICS_MONITOR_RE , HAPTICS_MONITOR_AMBIENT_TEMP , HAPTICS_MONITOR_DIE_TEMP , HAPTICS_MONITOR_VBAT , HAPTICS_MONITOR_VBST , HAPTICS_MONITOR_VOUT , HAPTICS_MONITOR_ALL }
	Integrated sensing features. More...
enum	haptics_monitor_type { HAPTICS_MONITOR_TYPE_MIN , HAPTICS_MONITOR_TYPE_MAX , HAPTICS_MONITOR_TYPE_MEAN , HAPTICS_MONITOR_TYPE_SINGLE }
	Qualifiers for integrated sensor readings. More...
enum	haptics_source { HAPTICS_SOURCE_ROM , HAPTICS_SOURCE_RAM , HAPTICS_SOURCE_DAI , HAPTICS_SOURCE_ANALOG , HAPTICS_SOURCE_PWM , HAPTICS_SOURCE_CONTROL_PORT , HAPTICS_SOURCE_ALL }
	Haptics playback sources. More...

Functions
int	haptics_calibrate (const struct device *dev, const uint32_t routine)
	Calibrate the haptic driver for an external actuator.
int	haptics_monitor_get (const struct device dev, const enum haptics_monitor monitor, const enum haptics_monitor_type type, struct sensor_value const val)
	Retrieve an integrated sensor reading from the haptic driver.
int	haptics_monitor_set (const struct device *dev, const enum haptics_monitor monitor, const bool enable)
	Enable or disable integrated sensing for the haptic driver.
static int	haptics_register_error_callback (const struct device dev, haptics_error_callback_t cb, void const user_data)
	Register a callback function for haptics errors.
int	haptics_select_source (const struct device dev, const enum haptics_source src, const union haptics_config const cfg)
	Specify a playback source and related configuration details.
int	haptics_set_level (const struct device dev, const enum haptics_source src, const union haptics_config const cfg, const uint32_t level)
	Set level controls for haptic effects.
int	haptics_start_output (const struct device *dev)
	Start playback for a haptic effect.
int	haptics_stop_output (const struct device *dev)
	Stop an ongoing haptic effect and cancel any queued effects, if applicable.
int	haptics_stream_samples (const struct device dev, const uint8_t const samples, const size_t len)
	Stream 8-bit samples over the control port for haptic effects.

Detailed Description

Interfaces for haptic drivers.

Typedef Documentation

◆ haptics_error_callback_t

typedef void(* haptics_error_callback_t) (const struct device *dev, const uint32_t errors, void *const user_data)

#include <zephyr/drivers/haptics.h>

Function type of callback invoked when an error occurs.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	errors	Device errors (bitmask of haptics_error_type values)
[in]	user_data	User data provided when the error callback was registered

Enumeration Type Documentation

◆ haptics_error_type

enum haptics_error_type

#include <zephyr/drivers/haptics.h>

Haptics error types.

Most haptic drivers provide protection features to prevent damage during operation. Applications can register a callback function (see haptics_register_error_callback()) to handle or recover from error states. The following error types are used to construct a bitmask provided to the application layer at run-time (see haptics_error_callback_t).

Enumerator
HAPTICS_ERROR_OVERCURRENT	Output overcurrent error.
HAPTICS_ERROR_OVERTEMPERATURE	Device overtemperature error.
HAPTICS_ERROR_UNDERVOLTAGE	Power source undervoltage error.
HAPTICS_ERROR_OVERVOLTAGE	Power source overvoltage error.
HAPTICS_ERROR_DC	Output direct-current error.

◆ haptics_monitor

enum haptics_monitor

#include <zephyr/drivers/haptics.h>

Integrated sensing features.

Some haptic drivers include integrated sensors for monitoring electrical and physical characteristics (e.g., voltage, current, resistance, etc.) related to power or an external actuator. Use any of the following monitor options with haptics_monitor_get() or haptics_monitor_set() to retrieve sensor readings or enable measurements, respectively.

Enumerator
HAPTICS_MONITOR_BEMF	Back EMF.
HAPTICS_MONITOR_CURRENT	Amperage.
HAPTICS_MONITOR_F0	Resonant frequency.
HAPTICS_MONITOR_RE	Coil resistance.
HAPTICS_MONITOR_AMBIENT_TEMP	Ambient temperature.
HAPTICS_MONITOR_DIE_TEMP	Die temperature.
HAPTICS_MONITOR_VBAT	Supply voltage.
HAPTICS_MONITOR_VBST	Boost supply voltage.
HAPTICS_MONITOR_VOUT	Amplifier output voltage.
HAPTICS_MONITOR_ALL	All integrated sensors.

◆ haptics_monitor_type

enum haptics_monitor_type

#include <zephyr/drivers/haptics.h>

Qualifiers for integrated sensor readings.

There is no uniform implementation for integrated sensors in haptic drivers. Some only provide the most recent sensor reading, and others aggregate readings over time into minimums, maximums, and averages. Refer to device drivers for implementation details.

Enumerator
HAPTICS_MONITOR_TYPE_MIN	Minimum sensor reading.
HAPTICS_MONITOR_TYPE_MAX	Maximum sensor reading.
HAPTICS_MONITOR_TYPE_MEAN	Mean sensor reading.
HAPTICS_MONITOR_TYPE_SINGLE	Most recent or single-shot sensor reading.

◆ haptics_source

enum haptics_source

#include <zephyr/drivers/haptics.h>

Haptics playback sources.

Haptic effects are typically pre-programmed in non-volatile memory, programmed at run-time into volatile memory, or streamed to the haptic driver over a control port or using a well-defined digital interface (e.g., I2S) or analog signal. Provide any of the following playback sources to haptics_select_source() to configure the device before calling haptics_start_output().

Enumerator
HAPTICS_SOURCE_ROM	Effect from a pre-programmed wavetable.
HAPTICS_SOURCE_RAM	Effect loaded at runtime into volatile memory.
HAPTICS_SOURCE_DAI	Effect streamed from a digital audio source (e.g., I2S).
HAPTICS_SOURCE_ANALOG	Effect streamed from an analog source.
HAPTICS_SOURCE_PWM	Effect streamed from a PWM source.
HAPTICS_SOURCE_CONTROL_PORT	Effect streamed via the control port (e.g., I2C or SPI).
HAPTICS_SOURCE_ALL	All playback sources.

Function Documentation

◆ haptics_calibrate()

int haptics_calibrate	(	const struct device *	dev,
		const uint32_t	routine )

#include <zephyr/drivers/haptics.h>

Calibrate the haptic driver for an external actuator.

Most haptic drivers provide calibration features that tune the hardware for an external actuator's particular physical and electrical characteristics, e.g., coil resistance and resonant frequency. Not all haptic drivers require discrete calibration routines. Refer to device drivers for implementation details.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	routine	Device-specific calibration routine, refer to the device's header file

Return values

0	if successful
-ENOSYS	if not implemented
<0	if failed

◆ haptics_monitor_get()

int haptics_monitor_get	(	const struct device *	dev,
		const enum haptics_monitor	monitor,
		const enum haptics_monitor_type	type,
		struct sensor_value *const	val )

#include <zephyr/drivers/haptics.h>

Retrieve an integrated sensor reading from the haptic driver.

Some haptic drivers may require enabling an integrated sensor using haptics_monitor_set() before values can be read from the device. Refer to device drivers for implementation details.

Note: Requesting readings from all sensors simultaneously (e.g., setting monitor to HAPTICS_MONITOR_ALL) is invalid.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	monitor	Sensing option (of type haptics_monitor)
[in]	type	Type of sensor reading (of type haptics_monitor_type)
[out]	val	Sensor reading (of type sensor_value)

Return values

0	if successful
-ENOSYS	if not implemented
<0	if failed

◆ haptics_monitor_set()

int haptics_monitor_set	(	const struct device *	dev,
		const enum haptics_monitor	monitor,
		const bool	enable )

#include <zephyr/drivers/haptics.h>

Enable or disable integrated sensing for the haptic driver.

Some haptic drivers may allow disabling integrated sensor measurements to reduce power consumption. Refer to device drivers for implementation details.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	monitor	Sensing option (of type haptics_monitor)
[in]	enable	True if enabling integrated sensing, false if disabling

Return values

0	if successful
-ENOSYS	if not implemented
<0	if failed

◆ haptics_register_error_callback()

int haptics_register_error_callback	(	const struct device *	dev,
		haptics_error_callback_t	cb,
		void *const	user_data )

inlinestatic

#include <zephyr/drivers/haptics.h>

Register a callback function for haptics errors.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	cb	Callback function (of type haptics_error_callback_t)
[in]	user_data	User data to be provided back to the application via the callback

Return values

0	if successful
-ENOSYS	if not implemented
<0	if failed

◆ haptics_select_source()

int haptics_select_source	(	const struct device *	dev,
		const enum haptics_source	src,
		const union haptics_config *const	cfg )

#include <zephyr/drivers/haptics.h>

Specify a playback source and related configuration details.

Typically, an application should call this function before calling haptics_start_output(). If unused, there is no uniform default playback source across haptic drivers, so behavior is up to the particular device driver. Refer to device drivers for implementation details.

Note: Some playback sources do not require any additional configuration details, in which case cfg should be set to NULL.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	src	Playback source (of type haptics_source)
[in]	cfg	Source configuration (of type haptics_config) or NULL

Return values

0	if successful
<0	if failed

◆ haptics_set_level()

int haptics_set_level	(	const struct device *	dev,
		const enum haptics_source	src,
		const union haptics_config *const	cfg,
		const uint32_t	level )

#include <zephyr/drivers/haptics.h>

Set level controls for haptic effects.

Most haptic drivers support configuring output level on a global, source-, or even waveform-specific basis. For example, to set global level for a haptic driver, an application might set src to HAPTICS_SOURCE_ALL and cfg to NULL, while level configuration for a pre-programmed waveform might set src to HAPTICS_SOURCE_ROM and cfg to the desired 'idx' value. Refer to device drivers for implementation details.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	src	Playback source (of type haptics_source)
[in]	cfg	Source configuration (of type haptics_config) or NULL
[in]	level	Device-specific output level value, rfer to the device driver for details

Return values

0	if successful
-ENOSYS	if not implemented
<0	if failed

◆ haptics_start_output()

int haptics_start_output ( const struct device * dev )

#include <zephyr/drivers/haptics.h>

Start playback for a haptic effect.

Start playback for a haptic effect specified using haptics_select_source(). If no source is specified, behavior is driver-specific. Refer to device drivers for implementation details.

Parameters

[in] dev Pointer to the device structure for the haptic device instance

Return values

0	if successful
<0	if failed

◆ haptics_stop_output()

int haptics_stop_output ( const struct device * dev )

#include <zephyr/drivers/haptics.h>

Stop an ongoing haptic effect and cancel any queued effects, if applicable.

If desired, any queued effects must be re-queued using haptics_start_output().

Parameters

[in] dev Pointer to the device structure for the haptic device instance

Return values

0	if successful
<0	if failed

◆ haptics_stream_samples()

int haptics_stream_samples	(	const struct device *	dev,
		const uint8_t *const	samples,
		const size_t	len )

#include <zephyr/drivers/haptics.h>

Stream 8-bit samples over the control port for haptic effects.

Most haptic drivers play samples streamed over a control port at a fixed sample rate. Refer to device drivers for implementation details.

Note: HAPTICS_SOURCE_CONTROL_PORT should be provided to haptics_select_source() before calling this function.

Parameters

[in]	dev	Pointer to the device structure for the haptic device instance
[in]	samples	Pointer to an array of 8-bit samples
[in]	len	Number of samples to write

Return values

0	if successful
-ENOSYS	if not implemented
<0	if failed

Topics

Files

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ haptics_error_callback_t

Enumeration Type Documentation

◆ haptics_error_type

◆ haptics_monitor

◆ haptics_monitor_type

◆ haptics_source

Function Documentation

◆ haptics_calibrate()

◆ haptics_monitor_get()

◆ haptics_monitor_set()

◆ haptics_register_error_callback()

◆ haptics_select_source()

◆ haptics_set_level()

◆ haptics_start_output()

◆ haptics_stop_output()

◆ haptics_stream_samples()