CS40L5x

CS40L5x Haptic Driver. More...

Data Structures
struct	cs40l5x_calibration
	Calibration data for click compensation. More...
struct	cs40l5x_pwle_section
	PWLE section definition. More...
struct	cs40l5x_trigger_config
	Structure to store GPIO trigger configurations. More...
struct	cs40l5x_trigger_gpios
	Structure to store and handle trigger GPIOs. More...
struct	cs40l5x_bus_io
	Control port I/O functions. More...
struct	cs40l5x_bus
	Structure to store control port devices. More...
struct	cs40l5x_config
	CS40L5x configuration structure for a device instance. More...
struct	cs40l5x_data
	CS40L5x data structure for a device instance. More...

Typedefs
typedef struct device *(*	cs40l5x_io_bus_get_device) (const struct device *const dev)
	Return pointer to control port instance.
typedef bool(*	cs40l5x_io_bus_is_ready) (const struct device *const dev)
	Function wrapper for i2c_is_ready_dt() or spi_is_ready_dt().
typedef int(*	cs40l5x_io_bus_read) (const struct device *const dev, const uint32_t addr, uint32_t *const rx, const uint32_t len)
	Function wrapper for i2c_write_read_dt() or spi_read_dt().
typedef int(*	cs40l5x_io_bus_write) (const struct device *const dev, uint32_t *const tx, const uint32_t len)
	Function wrapper for i2c_write_dt() or spi_read_dt().

Enumerations
enum	cs40l5x_attenuation {   CS40L5X_ATTENUATION_7DB = -7 , CS40L5X_ATTENUATION_6DB , CS40L5X_ATTENUATION_5DB , CS40L5X_ATTENUATION_4DB ,   CS40L5X_ATTENUATION_3DB , CS40L5X_ATTENUATION_2DB , CS40L5X_ATTENUATION_1DB , CS40L5X_ATTENUATION_0DB }
	Attenuation options for GPIO-triggered haptic effects. More...
enum	cs40l5x_bank { CS40L5X_ROM_BANK , CS40L5X_CUSTOM_BANK , CS40L5X_BUZ_BANK , CS40L5X_NO_BANK }
	Wavetable sources for haptic effects. More...
enum	cs40l5x_custom_index { CS40L5X_CUSTOM_0 , CS40L5X_CUSTOM_1 , CS40L5X_NUM_CUSTOM_EFFECTS }
	Custom haptics source indices (0 or 1). More...
enum	cs40l5x_error_type {   CS40L5X_ERROR_AMPLIFIER_SHORT = BIT(0) , CS40L5X_ERROR_OVERTEMPERATURE = BIT(1) , CS40L5X_ERROR_UNDERVOLTAGE = BIT(2) , CS40L5X_ERROR_INDUCTOR_SHORT = BIT(3) ,   CS40L5X_ERROR_OVERCURRENT = BIT(4) , CS40L5X_ERROR_BATTERY_UNDERVOLTAGE = BIT(4) }
	Types of fatal CS40L5x hardware errors. More...
enum	cs40l5x_logger { CS40L5X_LOGGER_DISABLE , CS40L5X_LOGGER_ENABLE , CS40L5X_LOGGER_NO_CHANGE }
	Options for runtime haptics logging. More...
enum	cs40l5x_logger_source { CS40L5X_LOGGER_BEMF , CS40L5X_LOGGER_VBST , CS40L5X_LOGGER_VMON }
	Options for runtime haptics logging sources. More...
enum	cs40l5x_logger_source_type { CS40L5X_LOGGER_MIN , CS40L5X_LOGGER_MAX , CS40L5X_LOGGER_MEAN }
	Type specification for runtime haptics logging sources. More...
enum	cs40l5x_trigger_edge { CS40L5X_RISING_EDGE , CS40L5X_FALLING_EDGE }
	Options for edge-triggered haptics effects. More...

Functions
int	cs40l5x_calibrate (const struct device *const dev)
	Run calibration to derive ReDC and F0 values and apply results for click compensation.
int	cs40l5x_configure_buzz (const struct device *const dev, const uint32_t frequency, const uint8_t level, const uint32_t duration)
	Configure ROM buzz for haptic playback.
int	cs40l5x_configure_trigger (const struct device *const dev, const struct gpio_dt_spec *const gpio, const enum cs40l5x_bank bank, const uint8_t index, const enum cs40l5x_attenuation attenuation, const enum cs40l5x_trigger_edge edge)
	Configure edge-triggered haptic effect.
int	cs40l5x_logger (const struct device *const dev, enum cs40l5x_logger logger_state)
	Update runtime haptics logging and get current status.
int	cs40l5x_logger_get (const struct device *const dev, enum cs40l5x_logger_source source, enum cs40l5x_logger_source_type type, uint32_t *const value)
	Get runtime haptics logging data for the specified logger source.
void	cs40l5x_register_error_callback (const struct device *dev, void(*error_callback)(const struct device *const haptic_dev, const uint32_t errors))
	Register an application callback to handle fatal hardware errors.
int	cs40l5x_select_output (const struct device *const dev, const enum cs40l5x_bank bank, const uint8_t index)
	Select haptic effect triggered via haptics_start_output().
int	cs40l5x_set_gain (const struct device *const dev, const uint8_t gain)
	Configure gain for haptic effects triggered via haptics_start_output().
int	cs40l5x_upload_pcm (const struct device *const dev, const enum cs40l5x_custom_index index, const uint16_t redc, const uint16_t f0, const int8_t *const samples, const uint16_t num_samples)
	Upload PCM effect to the specified index.
int	cs40l5x_upload_pwle (const struct device *const dev, const enum cs40l5x_custom_index index, const struct cs40l5x_pwle_section *const sections, const uint8_t num_sections)
	Upload PWLE effect to the specified index.

Detailed Description

CS40L5x Haptic Driver.

Typedef Documentation

cs40l5x_io_bus_get_device

typedef struct device *(* cs40l5x_io_bus_get_device) (const struct device *const dev)

#include <zephyr/drivers/haptics/cs40l5x.h>

Return pointer to control port instance.

Parameters

dev	Pointer to the device structure for the haptic device instance

Returns

Returns a pointer to the control port device structure

cs40l5x_io_bus_is_ready

typedef bool(* cs40l5x_io_bus_is_ready) (const struct device *const dev)

#include <zephyr/drivers/haptics/cs40l5x.h>

Function wrapper for i2c_is_ready_dt() or spi_is_ready_dt().

Parameters

dev	Pointer to the device structure for the haptic device instance

Return values

true	control port is ready for use
false	control port is not ready for use

cs40l5x_io_bus_read

typedef int(* cs40l5x_io_bus_read) (const struct device *const dev, const uint32_t addr, uint32_t *const rx, const uint32_t len)

#include <zephyr/drivers/haptics/cs40l5x.h>

Function wrapper for i2c_write_read_dt() or spi_read_dt().

Parameters

dev	Pointer to the device structure for the haptic device instance
addr	Starting register address
rx	Pointer to unsigned 32-bit storage (value or array) to store read values
len	Number of registers to read

Returns

a value from i2c_write_read_dt() or spi_read_dt()

cs40l5x_io_bus_write

typedef int(* cs40l5x_io_bus_write) (const struct device *const dev, uint32_t *const tx, const uint32_t len)

#include <zephyr/drivers/haptics/cs40l5x.h>

Function wrapper for i2c_write_dt() or spi_read_dt().

Parameters

dev	Pointer to the device structure for the haptic device instance
tx	Unsigned 32-bit array with the base register address followed by values to write
len	Pointer to unsigned 32-bit storage (value or array) to store read values

Returns

a value from i2c_write_dt() or spi_write_dt()

Enumeration Type Documentation

cs40l5x_attenuation

enum cs40l5x_attenuation

#include <zephyr/drivers/haptics/cs40l5x.h>

Attenuation options for GPIO-triggered haptic effects.

Provide to cs40l5x_configure_trigger().

Enumerator
CS40L5X_ATTENUATION_7DB	Configure haptic effect with 7 dB attenuation.
CS40L5X_ATTENUATION_6DB	Configure haptic effect with 6 dB attenuation.
CS40L5X_ATTENUATION_5DB	Configure haptic effect with 5 dB attenuation.
CS40L5X_ATTENUATION_4DB	Configure haptic effect with 4 dB attenuation.
CS40L5X_ATTENUATION_3DB	Configure haptic effect with 3 dB attenuation.
CS40L5X_ATTENUATION_2DB	Configure haptic effect with 2 dB attenuation.
CS40L5X_ATTENUATION_1DB	Configure haptic effect with 1 dB attenuation.
CS40L5X_ATTENUATION_0DB	Configure haptic effect with no attenuation.

cs40l5x_bank

enum cs40l5x_bank

#include <zephyr/drivers/haptics/cs40l5x.h>

Wavetable sources for haptic effects.

Provide to cs40l5x_configure_trigger() or cs40l5x_select_output().

Enumerator
CS40L5X_ROM_BANK	Playback from the pre-programmed ROM library.
CS40L5X_CUSTOM_BANK	Playback from custom haptics source programmed at runtime.
CS40L5X_BUZ_BANK	Playback from buzz source programmed at runtime.
CS40L5X_NO_BANK	Reserved for driver error handling.

cs40l5x_custom_index

enum cs40l5x_custom_index

#include <zephyr/drivers/haptics/cs40l5x.h>

Custom haptics source indices (0 or 1).

Provide to cs40l5x_upload_pcm() or cs40l5x_upload_pwle() to specify index to upload custom haptics source.

Enumerator
CS40L5X_CUSTOM_0	Custom haptics source at index 0.
CS40L5X_CUSTOM_1	Custom haptics source at index 1.
CS40L5X_NUM_CUSTOM_EFFECTS	Maximum number of custom haptics effects.

cs40l5x_error_type

enum cs40l5x_error_type

#include <zephyr/drivers/haptics/cs40l5x.h>

Types of fatal CS40L5x hardware errors.

Provided to application callback function. See cs40l5x_register_error_callback().

Enumerator
CS40L5X_ERROR_AMPLIFIER_SHORT	Amplifier short detected.
CS40L5X_ERROR_OVERTEMPERATURE	Overtemperature detected.
CS40L5X_ERROR_UNDERVOLTAGE	Undervoltage detected.
CS40L5X_ERROR_INDUCTOR_SHORT	Inductor short detected.
CS40L5X_ERROR_OVERCURRENT	Overcurrent condition detected.
CS40L5X_ERROR_BATTERY_UNDERVOLTAGE	Vdd_batt undervoltage detected.

cs40l5x_logger

enum cs40l5x_logger

#include <zephyr/drivers/haptics/cs40l5x.h>

Options for runtime haptics logging.

Provide to cs40l5x_logger() to update runtime haptics logging.

Enumerator
CS40L5X_LOGGER_DISABLE	Disable runtime logging for the device.
CS40L5X_LOGGER_ENABLE	Enable runtime logging for the device.
CS40L5X_LOGGER_NO_CHANGE	Use to retrieve haptics logging status without updating.

cs40l5x_logger_source

enum cs40l5x_logger_source

#include <zephyr/drivers/haptics/cs40l5x.h>

Options for runtime haptics logging sources.

Provide to cs40l5x_logger_get() to get runtime device characteristics.

Enumerator
CS40L5X_LOGGER_BEMF	Back EMF (SVC) in signed Q0.23 format (full scale is 24 V).
CS40L5X_LOGGER_VBST	Boost voltage in unsigned Q0.24 format (full scale is 14 V).
CS40L5X_LOGGER_VMON	Output voltage in signed Q0.23 format (full scale is 24 V).

cs40l5x_logger_source_type

enum cs40l5x_logger_source_type

#include <zephyr/drivers/haptics/cs40l5x.h>

Type specification for runtime haptics logging sources.

Provide to cs40l5x_logger_get() to get minimum, mean, or maximum logged values.

Enumerator
CS40L5X_LOGGER_MIN	Minimum value sampled for a logger source.
CS40L5X_LOGGER_MAX	Maximum value sampled for a logger source.
CS40L5X_LOGGER_MEAN	Mean value sampled for a logger source.

cs40l5x_trigger_edge

enum cs40l5x_trigger_edge

#include <zephyr/drivers/haptics/cs40l5x.h>

Options for edge-triggered haptics effects.

Provide to cs40l5x_configure_trigger() to specify the edge for haptic effects.

Enumerator
CS40L5X_RISING_EDGE	Configure a rising-edge haptic effect.
CS40L5X_FALLING_EDGE	Configure a falling-edge haptic effect.

Function Documentation

cs40l5x_calibrate()

int cs40l5x_calibrate

(

const struct device *const

dev

)

#include <zephyr/drivers/haptics/cs40l5x.h>

Run calibration to derive ReDC and F0 values and apply results for click compensation.

Parameters

dev	Pointer to the device structure for haptic device instance

Return values

0	if success
-EAGAIN	if ReDC or F0 estimation times out
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_configure_buzz()

int cs40l5x_configure_buzz	(	const struct device *const	dev,
		const uint32_t	frequency,
		const uint8_t	level,
		const uint32_t	duration )

#include <zephyr/drivers/haptics/cs40l5x.h>

Configure ROM buzz for haptic playback.

With large amplitudes and insufficient power (e.g., in the case of internal boost configurations), it's possible to induce boost errors.

Parameters

dev	Pointer to the device structure for haptic device instance
frequency	Frequency of haptic effect in Hz (default: 0xF0)
level	Amplitude of haptic effect, where UINT8_MAX is 100% (default: 0x1B)
duration	Playback duration in milliseconds, where 0 is infinite duration (default: 0x32)

Return values

0	if success
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_configure_trigger()

int cs40l5x_configure_trigger	(	const struct device *const	dev,
		const struct gpio_dt_spec *const	gpio,
		const enum cs40l5x_bank	bank,
		const uint8_t	index,
		const enum cs40l5x_attenuation	attenuation,
		const enum cs40l5x_trigger_edge	edge )

#include <zephyr/drivers/haptics/cs40l5x.h>

Configure edge-triggered haptic effect.

Parameters

dev	Pointer to the device structure for haptic device instance
gpio	Pointer to the device structure for the GPIO used as the trigger source
bank	Wavetable source for desired haptic effect, see cs40l5x_bank
index	Wavetable index for desired haptic effect
attenuation	Attenuation in dB for desired haptic effect, see cs40l5x_attenuation
edge	Specify edge (rising or falling) to trigger haptic effects

Return values

0	if success
-EINVAL	if invalid wavetable source and index provided (e.g., index out of bounds)
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_logger()

int cs40l5x_logger	(	const struct device *const	dev,
		enum cs40l5x_logger	logger_state )

#include <zephyr/drivers/haptics/cs40l5x.h>

Update runtime haptics logging and get current status.

Parameters

dev	Pointer to the device structure for haptic device instance
logger_state	See cs40l5x_logger

Return values

1	if logging is enabled
0	if logging is disabled
-EINVAL	if invalid wavetable source or trigger GPIO provided
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_logger_get()

int cs40l5x_logger_get	(	const struct device *const	dev,
		enum cs40l5x_logger_source	source,
		enum cs40l5x_logger_source_type	type,
		uint32_t *const	value )

#include <zephyr/drivers/haptics/cs40l5x.h>

Get runtime haptics logging data for the specified logger source.

Parameters

dev	Pointer to the device structure for haptic device instance
source	See cs40l5x_logger_source
value	Unsigned 32-bit integer to store the retrieved data
type	See cs40l5x_logger_source_type

Return values

0	if success
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_register_error_callback()

void cs40l5x_register_error_callback	(	const struct device *	dev,
		void(*	error_callback )(const struct device *const haptic_dev, const uint32_t errors) )

#include <zephyr/drivers/haptics/cs40l5x.h>

Register an application callback to handle fatal hardware errors.

Parameters

dev	Pointer to the device structure for haptic device instance
error_callback	Application function that takes a pointer to the device structure for a haptic device instance and a bitmask of cs40l5x_error_type

cs40l5x_select_output()

int cs40l5x_select_output	(	const struct device *const	dev,
		const enum cs40l5x_bank	bank,
		const uint8_t	index )

#include <zephyr/drivers/haptics/cs40l5x.h>

Select haptic effect triggered via haptics_start_output().

Parameters

dev	Pointer to the device structure for haptic device instance
bank	Wavetable source for desired haptic effect, see cs40l5x_bank
index	Wavetable index for desired haptic effect

Return values

0	if success
-EINVAL	if invalid wavetable source and index provided (e.g., index out of bounds)

cs40l5x_set_gain()

int cs40l5x_set_gain	(	const struct device *const	dev,
		const uint8_t	gain )

#include <zephyr/drivers/haptics/cs40l5x.h>

Configure gain for haptic effects triggered via haptics_start_output().

Parameters

dev	Pointer to the device structure for haptic device instance
gain	Gain setting (valid values between 0 and 100)

Return values

0	if success
-EINVAL	if provided gain is greater than 100%
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_upload_pcm()

int cs40l5x_upload_pcm	(	const struct device *const	dev,
		const enum cs40l5x_custom_index	index,
		const uint16_t	redc,
		const uint16_t	f0,
		const int8_t *const	samples,
		const uint16_t	num_samples )

#include <zephyr/drivers/haptics/cs40l5x.h>

Upload PCM effect to the specified index.

Parameters

dev	Pointer to the device structure for haptic device instance
index	See cs40l5x_custom_index
redc	ReDC compensation in unsigned Q5.7 format | redc * (24 / 2.9)
f0	F0 compensation in unsigned Q9.3 format | (f0 - 50) * 8
samples	Array of signed 8-bit PCM samples
num_samples	Number of PCM samples

Return values

0	if success
-EINVAL	if invalid index provided (e.g., index out of bounds)
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback

cs40l5x_upload_pwle()

int cs40l5x_upload_pwle	(	const struct device *const	dev,
		const enum cs40l5x_custom_index	index,
		const struct cs40l5x_pwle_section *const	sections,
		const uint8_t	num_sections )

#include <zephyr/drivers/haptics/cs40l5x.h>

Upload PWLE effect to the specified index.

Parameters

dev	Pointer to the device structure for haptic device instance
index	See cs40l5x_custom_index
sections	Array of cs40l5x_pwle_section
num_sections	Number of PWLE sections

Return values

0	if success
-EINVAL	if invalid index provided (e.g., index out of bounds)
-EIO	if a control port transaction fails
-errno	another error code on failure, resulting from PM action callback