Driver for the STM LIS2DH12 accelerometer. More...

Detailed Description

Driver for the STM LIS2DH12 accelerometer.

This device driver provides a minimal interface to LIS2DH12 devices. As of now, it only provides very basic access to the device. The driver configures the device to continuously read the acceleration data with statically defined scale and rate, and with a fixed 10-bit resolution. The LIS2DH12's FIFO is bypassed, so the driver might not be sufficient for use cases where the complete history of readings is of interest.

Also, the current version of the driver supports only interfacing the sensor via SPI. The driver is however written in a way, that adding I2C interface support is quite simple, as all bus related functions (acquire, release, read, write) are cleanly separated in the code.

This driver provides [S]ensor [A]ctuator [U]ber [L]ayer capabilities.

Files
file	lis2dh12.h
	Interface definition for the STM LIS2DH12 accelerometer.

file	lis2dh12_params.h
	Default configuration for LIS2DH12 devices.

file	lis2dh12_registers.h
	LIS2DH12 register definitions.

file	lis2dh12_internal.h
	Command definition for the LIS2DH12 accelerometer.

Data Structures
struct	lis2dh12_params_t
	LIS2DH12 configuration parameters. More...

struct	lis2dh12_highpass_t
	LIS2DH12 high pass config values. More...

struct	lis2dh12_click_t
	LIS2DH12 click config values. More...

struct	lis2dh12_t
	LIS2DH12 device descriptor. More...

struct	lis2dh12_int_params_t
	Parameter for interrupt configuration. More...

union	lis2dh12_fifo_data_t
	LIS2DH12 FIFO data struct. More...

struct	lis2dh12_fifo_t
	LIS2DH12 FIFO config values. More...

Macros
#define	LIS2DH12_ADDR_DEFAULT (0x19)
	Default I2C slave address for LIS2DH12 devices.

#define	LIS2DH12_CLICK_X_SINGLE (1 << 0)
	single click on X axis

#define	LIS2DH12_CLICK_X_DOUBLE (1 << 1)
	double click on X axis

#define	LIS2DH12_CLICK_Y_SINGLE (1 << 2)
	single click on Y axis

#define	LIS2DH12_CLICK_Y_DOUBLE (1 << 3)
	double click on Y axis

#define	LIS2DH12_CLICK_Z_SINGLE (1 << 4)
	single click on Z axis

#define	LIS2DH12_CLICK_Z_DOUBLE (1 << 5)
	double click on Z axis

Enumerations
enum	lis2dh12_scale_t { LIS2DH12_SCALE_2G = 0x0 , LIS2DH12_SCALE_4G = 0x1 , LIS2DH12_SCALE_8G = 0x2 , LIS2DH12_SCALE_16G = 0x3 }
	Available scale values. More...

enum	lis2dh12_rate_t { LIS2DH12_RATE_1HZ = 0x1 , LIS2DH12_RATE_10HZ = 0x2 , LIS2DH12_RATE_25HZ = 0x3 , LIS2DH12_RATE_50HZ = 0x4 , LIS2DH12_RATE_100HZ = 0x5 , LIS2DH12_RATE_200HZ = 0x6 , LIS2DH12_RATE_400HZ = 0x7 , LIS2DH12_RATE_1620HZ = 0x8 , LIS2DH12_RATE_VERYHIGH = 0x9 }
	Available sampling rates. More...

enum	lis2dh12_resolution_t { LIS2DH12_POWER_DOWN = 0 , LIS2DH12_POWER_LOW = 1 , LIS2DH12_POWER_NORMAL = 2 , LIS2DH12_POWER_HIGH = 3 }
	Available resolutions. More...

enum	lis2dh12_hp_mode_t { LIS2DH12_HP_MODE_NORMAL = 0x0 , LIS2DH12_HP_MODE_REFERENCE = 0x1 , LIS2DH12_HP_MODE_AUTORESET = 0x3 }
	LIS2DH12 high pass modes. More...

enum	lis2dh12_hp_freq_t { LIS2DH12_HP_FREQ_DIV50 = 0 , LIS2DH12_HP_FREQ_DIV100 = 1 , LIS2DH12_HP_FREQ_DIV200 = 2 , LIS2DH12_HP_FREQ_DIV400 = 3 }
	LIS2DH12 high pass cutoff frequency. More...

enum	{ LIS2DH12_OK = 0 , LIS2DH12_NOBUS = -1 , LIS2DH12_NODEV = -2 , LIS2DH12_NOINT = -3 , LIS2DH12_NODATA = -4 }
	Status and error return codes. More...

enum	{ LIS2DH12_INT1 = 1 , LIS2DH12_INT2 = 2 }

enum	lis2dh12_fifo_mode_t { LIS2DH12_FIFO_MODE_BYPASS = 0 , LIS2DH12_FIFO_MODE_FIFOMODE , LIS2DH12_FIFO_MODE_STREAM , LIS2DH12_FIFO_MODE_STREAMtoFIFO }
	LIS2DH12 FIFO modes. More...

Functions
void	lis2dh12_cfg_threshold_event (const lis2dh12_t *dev, uint32_t mg, uint32_t us, uint8_t axis, uint8_t event, uint8_t pin)
	Configure a threshold event An Interrupt will be generated if acceleration exceeds the set threshold around the current reference value. More...

void	lis2dh12_cfg_click_event (const lis2dh12_t *dev, uint32_t mg, uint32_t us_limit, uint32_t us_latency, uint32_t us_window, uint8_t click, uint8_t pin)
	Configure a click event A click event is generated when the acceleration exceeds the set threshold for less than `us_limit` µs. More...

void	lis2dh12_cfg_disable_event (const lis2dh12_t *dev, uint8_t event, uint8_t pin)
	Disable interrupt generation for an event This disables an interrupt on `pin` if a previously configured event occurs. More...

int	lis2dh12_wait_event (const lis2dh12_t *dev, uint8_t pin, bool stale_events)
	Wait for an interrupt event This function will block until an interrupt is received. More...

int	lis2dh12_set_fifo (const lis2dh12_t dev, const lis2dh12_fifo_t config)
	Set the FIFO configuration. More...

int	lis2dh12_restart_fifo (const lis2dh12_t *dev)
	Restart the FIFO mode this sets the FIFO mode in BYPASS mode and then back to previous mode Note: The LIS module disables the FIFO after interrupt automatically, it is recommended to set the FIFO in BYPASS mode and then back to old FIFO mode to enable the FIFO again. More...

uint8_t	lis2dh12_read_fifo_data (const lis2dh12_t dev, lis2dh12_fifo_data_t fifo_data, uint8_t number)
	This function will read a given number of data from FIFO reads amount of data that is available in FIFO. More...

int	lis2dh12_init (lis2dh12_t dev, const lis2dh12_params_t params)
	Initialize the given LIS2DH12 sensor device. More...

int	lis2dh12_read (const lis2dh12_t dev, lis2dh12_fifo_data_t data)
	Read acceleration data from the given device. More...

int	lis2dh12_read_temperature (const lis2dh12_t dev, int16_t temp)
	Read temperature data from the given device. More...

int	lis2dh12_clear_data (const lis2dh12_t *dev)
	Clear the LIS2DH12 memory, clears all sampled data. More...

int	lis2dh12_set_scale (lis2dh12_t *dev, lis2dh12_scale_t scale)
	Change device measuring range. More...

lis2dh12_scale_t	lis2dh12_get_scale (lis2dh12_t *dev)
	Get device measuring range. More...

int	lis2dh12_set_datarate (const lis2dh12_t *dev, lis2dh12_rate_t rate)
	Change device sampling rate. More...

uint16_t	lis2dh12_get_datarate (const lis2dh12_t *dev)
	Get device sampling rate in Hz. More...

int	lis2dh12_set_resolution (const lis2dh12_t *dev, lis2dh12_resolution_t resolution)
	Change device resolution. More...

lis2dh12_resolution_t	lis2dh12_get_resolution (const lis2dh12_t *dev)
	Get device resolution. More...

int	lis2dh12_set_highpass (const lis2dh12_t dev, const lis2dh12_highpass_t config)
	Configures the high pass filter. More...

int	lis2dh12_set_reference (const lis2dh12_t *dev, uint8_t reference)
	Set the reference value to control the high-pass reference. More...

int	lis2dh12_poweron (const lis2dh12_t *dev)
	Power on the given device and resets resolution and sampling rate to default values in the device descriptor parameters. More...

int	lis2dh12_poweroff (const lis2dh12_t *dev)
	Power off the given device. More...

const saul_driver_t	lis2dh12_saul_driver
	Export the SAUL interface for this driver.

const saul_driver_t	lis2dh12_saul_temp_driver

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Status and error return codes.

Enumerator
LIS2DH12_OK	everything was fine
LIS2DH12_NOBUS	bus interface error
LIS2DH12_NODEV	unable to talk to device
LIS2DH12_NOINT	wrong interrupt line (has to be LIS2DH12_INT1 or LIS2DH12_INT2)
LIS2DH12_NODATA	no data available

Definition at line 186 of file lis2dh12.h.

◆ anonymous enum

anonymous enum

Enumerator
LIS2DH12_INT1	first interrupt line
LIS2DH12_INT2	second interrupt line

Definition at line 198 of file lis2dh12.h.

◆ lis2dh12_fifo_mode_t

enum lis2dh12_fifo_mode_t

LIS2DH12 FIFO modes.

Enumerator
LIS2DH12_FIFO_MODE_BYPASS	default mode, FIFO is bypassed
LIS2DH12_FIFO_MODE_FIFOMODE	normal FIFO mode, stops if FIFO is full
LIS2DH12_FIFO_MODE_STREAM	Stream mode, oldest values get overwritten.
LIS2DH12_FIFO_MODE_STREAMtoFIFO	Stream mode and on interrupt jumps to FIFO mode.

Definition at line 230 of file lis2dh12.h.

◆ lis2dh12_hp_freq_t

enum lis2dh12_hp_freq_t

LIS2DH12 high pass cutoff frequency.

Enumerator
LIS2DH12_HP_FREQ_DIV50	cutoff freq is ODR divided by 50
LIS2DH12_HP_FREQ_DIV100	cutoff freq is ODR divided by 100
LIS2DH12_HP_FREQ_DIV200	cutoff freq is ODR divided by 200
LIS2DH12_HP_FREQ_DIV400	cutoff freq is ODR divided by 400

Definition at line 140 of file lis2dh12.h.

◆ lis2dh12_hp_mode_t

enum lis2dh12_hp_mode_t

LIS2DH12 high pass modes.

Enumerator
LIS2DH12_HP_MODE_NORMAL	normal mode, reset by reading REG_REFERENCE
LIS2DH12_HP_MODE_REFERENCE	uses the reference signal for filtering
LIS2DH12_HP_MODE_AUTORESET	automatically resets on interrupt generation

Definition at line 131 of file lis2dh12.h.

◆ lis2dh12_rate_t

enum lis2dh12_rate_t

Available sampling rates.

Enumerator
LIS2DH12_RATE_1HZ	sample with 1Hz @ all resolutions
LIS2DH12_RATE_10HZ	sample with 10Hz @ all resolutions
LIS2DH12_RATE_25HZ	sample with 25Hz @ all resolutions
LIS2DH12_RATE_50HZ	sample with 50Hz @ all resolutions
LIS2DH12_RATE_100HZ	sample with 100Hz @ all resolutions
LIS2DH12_RATE_200HZ	sample with 200Hz @ all resolutions
LIS2DH12_RATE_400HZ	sample with 400Hz @ all resolutions
LIS2DH12_RATE_1620HZ	sample with 1620HZ @ 8-bit
LIS2DH12_RATE_VERYHIGH	sample with 1344Hz @ High resolution or \ 5376Hz @ 8-bit

Definition at line 77 of file lis2dh12.h.

◆ lis2dh12_resolution_t

enum lis2dh12_resolution_t

Available resolutions.

Enumerator
LIS2DH12_POWER_DOWN	power down the device
LIS2DH12_POWER_LOW	8-bit mode
LIS2DH12_POWER_NORMAL	10-bit mode
LIS2DH12_POWER_HIGH	12-bit mode

Definition at line 94 of file lis2dh12.h.

◆ lis2dh12_scale_t

enum lis2dh12_scale_t

Available scale values.

Enumerator
LIS2DH12_SCALE_2G	+- 2g
LIS2DH12_SCALE_4G	+- 4g
LIS2DH12_SCALE_8G	+- 8g
LIS2DH12_SCALE_16G	+- 16g

Definition at line 66 of file lis2dh12.h.

Function Documentation

◆ lis2dh12_cfg_click_event()

void lis2dh12_cfg_click_event	(	const lis2dh12_t *	dev,
		uint32_t	mg,
		uint32_t	us_limit,
		uint32_t	us_latency,
		uint32_t	us_window,
		uint8_t	click,
		uint8_t	pin
	)

Configure a click event A click event is generated when the acceleration exceeds the set threshold for less than us_limit µs.

A double click event is generated if a second click event occurs within us_window µs after the first one.

Parameters

[in]	dev	device descriptor
[in]	mg	acceleration in mg
[in]	us_limit	upper limit for click duration in µs
[in]	us_latency	dead time after click event in µs
[in]	us_window	time after `us_latency` in which the second click event must occur to register as double click
[in]	click	bit map of click axis / types
[in]	pin	Interrupt pin to use (LIS2DH12_INT1/LIS2DH12_INT2)

◆ lis2dh12_cfg_disable_event()

void lis2dh12_cfg_disable_event	(	const lis2dh12_t *	dev,
		uint8_t	event,
		uint8_t	pin
	)

Disable interrupt generation for an event This disables an interrupt on pin if a previously configured event occurs.

Parameters

[in]	dev	device descriptor
[in]	event	Event to disable (LIS2DH12_EVENT_1, LIS2DH12_EVENT_2 or LIS2DH12_EVENT_CLICK)
[in]	pin	Interrupt pin to use (LIS2DH12_INT1/LIS2DH12_INT2)

◆ lis2dh12_cfg_threshold_event()

void lis2dh12_cfg_threshold_event	(	const lis2dh12_t *	dev,
		uint32_t	mg,
		uint32_t	us,
		uint8_t	axis,
		uint8_t	event,
		uint8_t	pin
	)

Configure a threshold event An Interrupt will be generated if acceleration exceeds the set threshold around the current reference value.

Parameters

[in]	dev	device descriptor
[in]	mg	acceleration in mg
[in]	us	time in µs for which the threshold must be exceeded
[in]	axis	bitmap of axis / events to be monitored
[in]	event	Event slot (1 or 2)
[in]	pin	Interrupt pin to use (LIS2DH12_INT1/LIS2DH12_INT2)

◆ lis2dh12_clear_data()

int lis2dh12_clear_data ( const lis2dh12_t * dev )

Clear the LIS2DH12 memory, clears all sampled data.

Parameters

[in] dev device descriptor

Returns: LIS2DH12_OK on success

◆ lis2dh12_get_datarate()

uint16_t lis2dh12_get_datarate ( const lis2dh12_t * dev )

Get device sampling rate in Hz.

Parameters

[in] dev device descriptor

Returns: current sampling rate in Hz

◆ lis2dh12_get_resolution()

lis2dh12_resolution_t lis2dh12_get_resolution ( const lis2dh12_t * dev )

Get device resolution.

Parameters

[in] dev device descriptor

Returns: Current device resolution settings

◆ lis2dh12_get_scale()

lis2dh12_scale_t lis2dh12_get_scale ( lis2dh12_t * dev )

Get device measuring range.

Parameters

[in] dev device descriptor

Returns: Current device range

◆ lis2dh12_init()

int lis2dh12_init	(	lis2dh12_t *	dev,
		const lis2dh12_params_t *	params
	)

Initialize the given LIS2DH12 sensor device.

Parameters

[out]	dev	device descriptor
[in]	params	static device configuration

Returns: LIS2DH12_OK on success; LIS2DH12_NOBUS on bus errors; LIS2DH12_NODEV if no LIS2DH12 device was found on the bus

◆ lis2dh12_poweroff()

int lis2dh12_poweroff ( const lis2dh12_t * dev )

Power off the given device.

Parameters

[in] dev device descriptor

Returns: LIS2DH12_OK on success; LIS2DH12_NOBUS on bus error

◆ lis2dh12_poweron()

int lis2dh12_poweron ( const lis2dh12_t * dev )

Power on the given device and resets resolution and sampling rate to default values in the device descriptor parameters.

Parameters

[in] dev device descriptor

Returns: LIS2DH12_OK on success; LIS2DH12_NOBUS on bus error

◆ lis2dh12_read()

int lis2dh12_read	(	const lis2dh12_t *	dev,
		lis2dh12_fifo_data_t *	data
	)

Read acceleration data from the given device.

Parameters

[in]	dev	device descriptor
[out]	data	acceleration data in mili-g

Returns: LIS2DH12_OK on success; LIS2DH12_NOBUS on bus error

◆ lis2dh12_read_fifo_data()

uint8_t lis2dh12_read_fifo_data	(	const lis2dh12_t *	dev,
		lis2dh12_fifo_data_t *	fifo_data,
		uint8_t	number
	)

This function will read a given number of data from FIFO reads amount of data that is available in FIFO.

Parameters

[in]	dev	device descriptor
[out]	fifo_data	FIFO data, must have space for number of data
[in]	number	amount of FIFO data to be read

Returns: number of valid data read from FIFO

◆ lis2dh12_read_temperature()

int lis2dh12_read_temperature	(	const lis2dh12_t *	dev,
		int16_t *	temp
	)

Read temperature data from the given device.

Note: The temperature sensor is not calibrated. Temperature values are only relative to a device specific reference.

Parameters

[in]	dev	device descriptor
[out]	temp	temperature data in centi-°C

Returns: LIS2DH12_OK on success; LIS2DH12_NOBUS on bus error

◆ lis2dh12_restart_fifo()

int lis2dh12_restart_fifo ( const lis2dh12_t * dev )

Restart the FIFO mode this sets the FIFO mode in BYPASS mode and then back to previous mode Note: The LIS module disables the FIFO after interrupt automatically, it is recommended to set the FIFO in BYPASS mode and then back to old FIFO mode to enable the FIFO again.

Parameters

[in] dev device descriptor

Returns: LIS2DH12_OK on success

◆ lis2dh12_set_datarate()

int lis2dh12_set_datarate	(	const lis2dh12_t *	dev,
		lis2dh12_rate_t	rate
	)

Change device sampling rate.

Parameters

[in]	dev	device descriptor
[in]	rate	change to given sampling rate

Returns: LIS2DH12_OK on success

◆ lis2dh12_set_fifo()

int lis2dh12_set_fifo	(	const lis2dh12_t *	dev,
		const lis2dh12_fifo_t *	config
	)

Set the FIFO configuration.

Parameters

[in]	dev	device descriptor
[in]	config	device FIFO configuration

Returns: LIS2DH12_OK on success

◆ lis2dh12_set_highpass()

int lis2dh12_set_highpass	(	const lis2dh12_t *	dev,
		const lis2dh12_highpass_t *	config
	)

Configures the high pass filter.

Parameters

[in]	dev	device descriptor
[in]	config	device high pass configuration

Returns: LIS2DH12_OK on success

◆ lis2dh12_set_reference()

int lis2dh12_set_reference	(	const lis2dh12_t *	dev,
		uint8_t	reference
	)

Set the reference value to control the high-pass reference.

In LIS2DH12_HP_MODE_REFERENCE the reference value is used to filter data on all axis. Subtracts reference value from acceleration. Note: LSB changes according to LIS2DH12_SCALE

Parameters

[in]	dev	device descriptor
[in]	reference	reference value [8 Bit]

Returns: LIS2DH12_OK on success

◆ lis2dh12_set_resolution()

int lis2dh12_set_resolution	(	const lis2dh12_t *	dev,
		lis2dh12_resolution_t	resolution
	)

Change device resolution.

Parameters

[in]	dev	device descriptor
[in]	resolution	change to given resolution

Returns: LIS2DH12_OK on success

◆ lis2dh12_set_scale()

int lis2dh12_set_scale	(	lis2dh12_t *	dev,
		lis2dh12_scale_t	scale
	)

Change device measuring range.

Parameters

[in]	dev	device descriptor
[in]	scale	change to given scale value

Returns: LIS2DH12_OK on success

◆ lis2dh12_wait_event()

int lis2dh12_wait_event	(	const lis2dh12_t *	dev,
		uint8_t	pin,
		bool	stale_events
	)

Wait for an interrupt event This function will block until an interrupt is received.

Parameters

[in]	dev	device descriptor
[in]	pin	Interrupt pin to monitor (LIS2DH12_INT1 or LIS2DH12_INT2)
[in]	stale_events	If true, this also reports events that were generated before this function was called and which are still in the fifo buffer.

Returns: negative error; positive LIS2DH12_INT_SRC bit mask on success

Detailed Description

Files

Data Structures

Macros

Enumerations

Functions

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ lis2dh12_fifo_mode_t

◆ lis2dh12_hp_freq_t

◆ lis2dh12_hp_mode_t

◆ lis2dh12_rate_t

◆ lis2dh12_resolution_t

◆ lis2dh12_scale_t

Function Documentation

◆ lis2dh12_cfg_click_event()

◆ lis2dh12_cfg_disable_event()

◆ lis2dh12_cfg_threshold_event()

◆ lis2dh12_clear_data()

◆ lis2dh12_get_datarate()

◆ lis2dh12_get_resolution()

◆ lis2dh12_get_scale()

◆ lis2dh12_init()

◆ lis2dh12_poweroff()

◆ lis2dh12_poweron()

◆ lis2dh12_read()

◆ lis2dh12_read_fifo_data()

◆ lis2dh12_read_temperature()

◆ lis2dh12_restart_fifo()

◆ lis2dh12_set_datarate()

◆ lis2dh12_set_fifo()

◆ lis2dh12_set_highpass()

◆ lis2dh12_set_reference()

◆ lis2dh12_set_resolution()

◆ lis2dh12_set_scale()

◆ lis2dh12_wait_event()