CS40L5x

CS40L5x Haptic Driver for LRA and VCM. More...

Files
file	cs40l5x.h
	Header file providing the API for the CS40L5x haptic driver.

Data Structures
struct	cs40l5x_pwle_section
	PWLE section definition. More...

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 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_logger { CS40L5X_LOGGER_DISABLE , CS40L5X_LOGGER_ENABLE }
	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)
	Enable or disable runtime haptics logging.
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.
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 for LRA and VCM.

Enumeration Type Documentation

cs40l5x_attenuation

enum cs40l5x_attenuation

#include <cs40l5x.h>

Attenuation options for 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 <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 <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_logger

enum cs40l5x_logger

#include <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_source

enum cs40l5x_logger_source

#include <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 <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 <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 <cs40l5x.h>

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

Parameters

[in]

dev

Pointer to the device structure for haptic device instance

Returns

0 on success, negative errno value on failure.

Return values

-EAGAIN	ReDC or F0 estimation timed out.
-EIO	A control port transaction failed.

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 <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

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

Returns

0 on success, negative errno value on failure.

Return values

-EIO	A control port transaction failed.

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 <cs40l5x.h>

Configure edge-triggered haptic effect.

Parameters

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

Returns

0 on success, negative errno value on failure.

Return values

-EINVAL	Invalid wavetable source and index provided (e.g., index out of bounds).
-EIO	A control port transaction failed.

cs40l5x_logger()

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

#include <cs40l5x.h>

Enable or disable runtime haptics logging.

Parameters

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

Return values

1	Logging is enabled.
0	Logging is disabled.
-EINVAL	Invalid wavetable source or trigger GPIO provided.
-EIO	A control port transaction failed.

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 <cs40l5x.h>

Get runtime haptics logging data for the specified logger source.

Parameters

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

Returns

0 on success, negative errno value on failure.

Return values

-EIO	A control port transaction failed.

cs40l5x_select_output()

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

#include <cs40l5x.h>

Select haptic effect triggered via haptics_start_output().

Parameters

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

Returns

0 on success, negative errno value on failure.

Return values

-EINVAL

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 <cs40l5x.h>

Configure gain for haptic effects triggered via haptics_start_output().

Parameters

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

Returns

0 on success, negative errno value on failure.

Return values

-EINVAL	Provided gain is greater than 100%.
-EIO	A control port transaction failed.

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 <cs40l5x.h>

Upload PCM effect to the specified index.

Parameters

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

Returns

0 on success, negative errno value on failure.

Return values

-EINVAL	Invalid index provided (e.g., index out of bounds).
-EIO	A control port transaction failed.

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 <cs40l5x.h>

Upload PWLE effect to the specified index.

Parameters

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

Returns

0 on success, negative errno value on failure.

Return values

-EINVAL	Invalid index provided (e.g., index out of bounds).
-EIO	A control port transaction failed.