diff --git a/README.md b/README.md index 5fe0ddb..e64e137 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,47 @@ # LIS3DH -A C89 driver for the 3-axis accelerometer LIS3DH. Supports both i2c and SPI. +A C89 driver for the 3-axis accelerometer LIS3DH. Supports both I2C and SPI. -> ### Features +### Features > - FIFO > - HP filter > - 2G, 4G, 8G and 16G > - Low-power mode, normal mode and high-resolution mode -> - ADC (x3) and temperature sensing +> - ADC and temperature sensing > - Interrupt generation -> - Free-fall detection (soon) +> - Free-fall detection > - Single-click detection > - Double-click detection > - 4D/6D orientation detection (soon) + ## Examples -See the examples/ dir for complete code examples +See the `examples/` dir for complete code examples ## Implementation -This driver requires the user to provide pointers to the following abstractely named functions: +This driver requires the user to implement the following interface functions: This project has example interface code for I2C used on Raspberry Pi. ```c /* initialise the "interface" */ int init(void); -/* read from device register `reg`, `size` amount of bytes and write them to `dst` */ +/* read from register `reg`, `size` amount of bytes, and write them to `dst` */ int read(uint8_t reg, uint8_t *dst, uint32_t size); -/* write `value` to device register `reg` */ +/* write `value` to register `reg` */ int write(uint8_t reg, uint8_t value); /* sleep for `dur_us` microseconds */ int sleep(uint32_t dur_us); /* deinitalise the "interface" */ int deinit(void); ``` -All above functions return `0` on success. +All above functions return `0` on success, and any non-zero value on error. -The `init` and `deinit` pointers can both be set to `NULL` and they won't be run. +If `init` and `deinit` are set to `NULL`, they will be ignored. Useful on microcontrollers. +--- ### Using i2c on STM32 -Simple example code +Example code because I couldn't previously find working examples. ```c #define LIS3DH_I2C_ADDR 0x18 diff --git a/example/README.md b/example/README.md index 8033520..e644df6 100644 --- a/example/README.md +++ b/example/README.md @@ -4,16 +4,14 @@ Basic example of how to use this device ### file: fifo.c -Instead of polling for every single [x y z] set, a FIFO with programmable capacity ("watermark") can be used, and then dumped into memory once full. - -All FIFO readings use 10-bit resolution regardless of the mode set in `lis.cfg.mode`. - -The watermark level can be adjusted to a value [0-31] by modifying the `lis.cfg.fifo.fth` property before calling `lis3dh_configure()`. +Instead of polling for every single [x y z] set, a FIFO with programmable capacity ("watermark") can be used, and then dumped into memory once full. All FIFO readings use 10-bit resolution regardless of the mode set in `lis.cfg.mode`. The watermark level can be adjusted to a value [0-31] by modifying the `lis.cfg.fifo.fth` property before calling `lis3dh_configure()`. The LIS3DH can optionally apply a HP filter on the sample data. It can be used to greatly reduce the "DC acceleration" present. ### file: interrupts.c -This device supports two different interrupt "output pins," `INT1` and `INT2`. The appropriate flag must be set in either `cfg.pin1` or `cfg.pin2` and the interrupt source must be configured to trigger into `INT1` or `INT2`. This file contains example code that listens and receives an interrupt when the FIFO watermark is reached i.e. it is full. +This device supports two different interrupt "output pins," `INT1` and `INT2`. The appropriate flag must be set in either `cfg.pin1` or `cfg.pin2` and the interrupt source must be configured to trigger into `INT1` or `INT2`. + +This file contains example code that listens and receives an interrupt when the FIFO watermark is reached i.e. it is full. ### file: single-click.c @@ -40,6 +38,8 @@ Enable and read built-in temperature sensor ### Inertial interrupts +There are two interrupt registers, `int1` and `int2` that can be configured for inertial interrupts. The config structs are identical and contain the fields: `zh`, `zl`, `yh`, `yl`, `xh`, `xl`, and more. `zh` stands for `Z_axis_high` and `zl` stands for `Z_axis_low`. If both are enabled, the device will generate an interrupt upon Z-axis acceleration exceeding `threshold`, or upon Z-axis acceleration reading at or below `-threshold` (in OR mode. Not possible in AND mode). + | aoi | en_6d | interrupt mode | |-----|-------|-------------------------| @@ -65,8 +65,6 @@ An interrupt is generated when all of the configures axes are at or above the th An interrupt is generated when the device is "stable" in a known direction. The interrupt is active as long as the direction is maintained. -There are two interrupt registers, `int1` and `int2` that can be configured for inertial interrupts. The config structs are identical and contain the fields: `zh`, `zl`, `yh`, `yl`, `xh`, `xl`, and more. `zh` stands for `Z_axis_high` and `zl` stands for `Z_axis_low`. If both are enabled, the device will generate an interrupt upon Z-axis acceleration exceeding `threshold`, or upon Z-axis acceleration reading at or below `-threshold` (in OR mode. Not possible in AND mode). - ### file: inertial-wakeup.c Inertial interrupt example in OR mode (easily changed to AND mode) with configurable axes, threshold and minimum acceleration duration.