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 185 of file lis2dh12.h.

◆ anonymous enum

anonymous enum
Enumerator
LIS2DH12_INT1 

first interrupt line

LIS2DH12_INT2 

second interrupt line

Definition at line 197 of file lis2dh12.h.

◆ 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 229 of file lis2dh12.h.

◆ 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 139 of file lis2dh12.h.

◆ 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 130 of file lis2dh12.h.

◆ 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 76 of file lis2dh12.h.

◆ 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 93 of file lis2dh12.h.

◆ 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 65 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]devdevice descriptor
[in]mgacceleration in mg
[in]us_limitupper limit for click duration in µs
[in]us_latencydead time after click event in µs
[in]us_windowtime after us_latency in which the second click event must occur to register as double click
[in]clickbit map of click axis / types
[in]pinInterrupt 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]devdevice descriptor
[in]eventEvent to disable (LIS2DH12_EVENT_1, LIS2DH12_EVENT_2 or LIS2DH12_EVENT_CLICK)
[in]pinInterrupt 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]devdevice descriptor
[in]mgacceleration in mg
[in]ustime in µs for which the threshold must be exceeded
[in]axisbitmap of axis / events to be monitored
[in]eventEvent slot (1 or 2)
[in]pinInterrupt 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]devdevice 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]devdevice 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]devdevice descriptor
Returns
Current device resolution settings

◆ lis2dh12_get_scale()

lis2dh12_scale_t lis2dh12_get_scale ( lis2dh12_t dev)

Get device measuring range.

Parameters
[in]devdevice 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]devdevice descriptor
[in]paramsstatic 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]devdevice 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]devdevice 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]devdevice descriptor
[out]dataacceleration 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]devdevice descriptor
[out]fifo_dataFIFO data, must have space for number of data
[in]numberamount 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]devdevice descriptor
[out]temptemperature 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]devdevice 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]devdevice descriptor
[in]ratechange 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]devdevice descriptor
[in]configdevice 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]devdevice descriptor
[in]configdevice 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]devdevice descriptor
[in]referencereference 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]devdevice descriptor
[in]resolutionchange 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]devdevice descriptor
[in]scalechange 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]devdevice descriptor
[in]pinInterrupt pin to monitor (LIS2DH12_INT1 or LIS2DH12_INT2)
[in]stale_eventsIf 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