FIFO README

README.md

@@ -16,7 +16,7 @@ A C89 driver for the 3-axis accelerometer LIS3DH. Supports both I2C and SPI.
 
 
 ## Examples
-See the `examples/` dir for complete code examples
+See the `examples/` dir for complete code examples and explanations of LIS3DH terminology
 
 ## Implementation
 This driver requires the user to implement the following interface functions:
@@ -54,6 +54,7 @@ int lis3dh_reference(lis3dh_t *lis3dh);
 int lis3dh_reset(lis3dh_t *lis3dh);
 int lis3dh_read_adc(lis3dh_t *lis3dh);
 int lis3dh_read_temp(lis3dh_t *lis3dh);
+int lis3dh_fifo_reset(lis3dh_t *lis3dh);
 ```
 All functions return `0` on success, and any non-zero value on error.
 

example/README.md

@@ -3,16 +3,22 @@
 ### file: simple.c
 Basic example of how to use this device
 
-### file: fifo.c
+# FIFO
 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 `cfg.mode`.
 
 The watermark level can be adjusted to a value [1-32] (0 disables FIFO) by modifying the `cfg.fifo.size` property before calling `lis3dh_configure()`.
 
-The LIS3DH can optionally apply a HP filter on the sampling to reduce 'static acceleration' from the data.
+The FIFO "engine" samples/appends another set of [x y z] values at 1/ODR. The maximum ODR supported by the FIFO "engine" is 200 Hz.
+
+| FIFO mode        |  symbol               | description                |
+|------------------|-----------------------|----------------------------|
+|  Bypass          |   `LIS3DH_FIFO_MODE_BYPASS` | FIFO is inoperational      |
+|  FIFO            |   `LIS3DH_FIFO_MODE_FIFO`   | FIFO can be read/emptied at any time but once overrun has to be reset. See file: `fifo-mode-fifo.c`     |
+|  Stream          |   `LIS3DH_FIFO_MODE_STREAM` | FIFO continously writes new data at 1/ODR and will overwrite old data until it is read/emptied. See file: `fifo-mode-stream.c`    |
+|  Stream_to_FIFO  |   `LIS3DH_FIFO_STREAM_TO_FIFO`  | FIFO behaves like Stream mode until a set interrupt is activated, then changes to a mode FIFO. |
 
-Note: it seems that the highest data rate (ODR) possible using FIFO is 200 Hz, faster than that and it does not want to restart after 1 FIFO buffer. To sample faster, such as at the advertised 5 KHz rate, you have to use `lis3dh_read()` with `LP` mode.
 
 ### 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`.

example/fifo-mode-fifo.c

@@ -0,0 +1,49 @@
+#define _GNU_SOURCE
+#include <unistd.h>
+#include <stdio.h>
+#include "lis3dh.h"
+#include "i2c.h"
+#include "interrupt.h"
+
+#define GPIO_INTERRUPT_PIN_INT1 12
+
+int main() {
+
+    lis3dh_t lis;
+    struct lis3dh_fifo_data fifo;
+    int i;
+
+    lis.dev.init = i2c_init;
+    lis.dev.read = i2c_read;
+    lis.dev.write = i2c_write;
+    lis.dev.sleep = usleep;
+    lis.dev.deinit = i2c_deinit;
+
+    lis3dh_init(&lis);
+    lis3dh_reset(&lis);
+    int_register(GPIO_INTERRUPT_PIN_INT1);
+
+    lis.cfg.mode = LIS3DH_MODE_HR;
+    lis.cfg.range = LIS3DH_FS_2G;
+    lis.cfg.rate = LIS3DH_ODR_100_HZ;
+    lis.cfg.pin1.overrun = 1;
+    lis.cfg.fifo.mode = LIS3DH_FIFO_MODE_FIFO;
+    lis.cfg.fifo.trig = LIS3DH_FIFO_TRIG_INT1;
+
+    lis3dh_configure(&lis);
+
+    for ( ;; ) {
+
+        int_poll(GPIO_INTERRUPT_PIN_INT1);
+        lis3dh_read_fifo(&lis, &fifo);
+        for(i=0; i<fifo.size; i++)
+            printf("x: %4.4d mg, y: %4.4d mg, z: %4.4d mg\n", fifo.x[i], fifo.y[i], fifo.z[i]);
+
+        printf("fifo.size=%d\n", fifo.size);
+        lis3dh_fifo_reset(&lis);
+    }
+
+    lis3dh_deinit(&lis);
+
+    return 0;
+}

example/fifo-mode-stream.c

@@ -0,0 +1,48 @@
+#define _GNU_SOURCE
+#include <unistd.h>
+#include <stdio.h>
+#include "lis3dh.h"
+#include "i2c.h"
+#include "interrupt.h"
+
+#define GPIO_INTERRUPT_PIN_INT1 12
+
+int main() {
+
+    lis3dh_t lis;
+    struct lis3dh_fifo_data fifo;
+    int i;
+
+    lis.dev.init = i2c_init;
+    lis.dev.read = i2c_read;
+    lis.dev.write = i2c_write;
+    lis.dev.sleep = usleep;
+    lis.dev.deinit = i2c_deinit;
+
+    lis3dh_init(&lis);
+    lis3dh_reset(&lis);
+    int_register(GPIO_INTERRUPT_PIN_INT1);
+
+    lis.cfg.mode = LIS3DH_MODE_HR;
+    lis.cfg.range = LIS3DH_FS_2G;
+    lis.cfg.rate = LIS3DH_ODR_100_HZ;
+    lis.cfg.pin1.overrun = 1;
+    lis.cfg.fifo.mode = LIS3DH_FIFO_MODE_STREAM;
+    lis.cfg.fifo.trig = LIS3DH_FIFO_TRIG_INT1;
+
+    lis3dh_configure(&lis);
+
+    for ( ;; ) {
+
+        int_poll(GPIO_INTERRUPT_PIN_INT1);
+        lis3dh_read_fifo(&lis, &fifo);
+        for(i=0; i<fifo.size; i++)
+            printf("x: %4.4d mg, y: %4.4d mg, z: %4.4d mg\n", fifo.x[i], fifo.y[i], fifo.z[i]);
+
+        printf("fifo.size=%d\n", fifo.size);
+    }
+
+    lis3dh_deinit(&lis);
+
+    return 0;
+}

example/fifo.c

@@ -1,56 +0,0 @@
-#define _GNU_SOURCE
-#include <unistd.h>
-#include <stdio.h>
-#include "lis3dh.h"
-#include "i2c.h"
-
-int main() {
-
-    lis3dh_t lis;
-    struct lis3dh_fifo_data fifo;
-    int i;
-
-    lis.dev.init = i2c_init;
-    lis.dev.read = i2c_read;
-    lis.dev.write = i2c_write;
-    lis.dev.sleep = usleep;
-    lis.dev.deinit = i2c_deinit;
-
-    /* initialise LIS3DH struct */
-    if (lis3dh_init(&lis)) {
-        /* error handling */
-    }
-
-    /* reset device just in case */
-    if (lis3dh_reset(&lis)) {
-        /* error handling */
-    }
-
-    lis.cfg.mode = LIS3DH_MODE_HR;
-    lis.cfg.range = LIS3DH_FS_4G;
-    lis.cfg.rate = LIS3DH_ODR_100_HZ;
-    lis.cfg.fifo.mode = LIS3DH_FIFO_MODE_NORMAL;
-
-    /* write device config */
-    if (lis3dh_configure(&lis)) {
-        /* error handling */
-    }
-
-    /* read as many [x y z] sets as specified by watermark level (size) default (max/32) */
-    /* copy them to the fifo data struct `fifo' */
-    if (lis3dh_read_fifo(&lis, &fifo)) {
-        /* error handling */
-    }
-
-    /* read out fifo buffer data */
-    for(i=0; i<fifo.size; i++) {
-        printf("x: %d mg, y: %d mg, z: %d mg\n", fifo.x[i], fifo.y[i], fifo.z[i]);
-    }
-
-    /* deinitialise struct */
-    if (lis3dh_deinit(&lis)) {
-        /* error handling */
-    }
-
-    return 0;
-}

example/interrupts.c

@@ -1,88 +0,0 @@
-#define _GNU_SOURCE
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-#include <math.h>
-#include "lis3dh.h"
-#include "interrupt.h"
-#include "i2c.h"
-
-/* GPIO 12 or Pin 32 */
-#define GPIO_INTERRUPT_PIN 12
-
-int main() {
-
-    lis3dh_t lis;
-    struct lis3dh_fifo_data fifo;
-    int i;
-
-    lis.dev.init = i2c_init;
-    lis.dev.read = i2c_read;
-    lis.dev.write = i2c_write;
-    lis.dev.sleep = usleep;
-    lis.dev.deinit = i2c_deinit;
-
-    /* initalise LIS3DH struct */
-    if (lis3dh_init(&lis)) {
-        /* error handling */
-    }
-
-    /* reset device just in case */
-    if (lis3dh_reset(&lis)) {
-        /* error handling */
-    }
-
-    /* register interrupt */
-    if (int_register(GPIO_INTERRUPT_PIN)) {
-        /* error handling */
-    }
-
-    lis.cfg.mode = LIS3DH_MODE_NORMAL;
-    lis.cfg.range = LIS3DH_FS_2G;
-    lis.cfg.rate = LIS3DH_ODR_100_HZ;
-    lis.cfg.fifo.mode = LIS3DH_FIFO_MODE_STREAM;
-    lis.cfg.fifo.trig = LIS3DH_FIFO_TRIG_INT1; /* trigger interrupt into int pin1 */
-    lis.cfg.pin1.overrun = 1; /* trigger upon FIFO overrun */
-
-    /* set up HP filter to remove DC component */
-    lis.cfg.filter.mode = LIS3DH_FILTER_MODE_NORMAL_REF;
-    lis.cfg.filter.cutoff = LIS3DH_FILTER_CUTOFF_4;
-    lis.cfg.filter.fds = 0; /* remove this line, or set to 1 to enable filter */
-    
-    /* write device config */
-    if (lis3dh_configure(&lis)) {
-       /* error handling */
-    }
-
-    /* read REFERENCE to set filter to current accel field */
-    if (lis3dh_reference(&lis)) {
-        /* error handling */
-    }
-    
-    /* wait for interrupt from LIS3DH */
-    if (int_poll(GPIO_INTERRUPT_PIN)) {
-        /* error handling */
-    }
-
-    /* read as many [x y z] sets as specified by watermark level (size) */
-    /* copy them to the fifo data struct given below as `fifo' */
-    if (lis3dh_read_fifo(&lis, &fifo)) {
-       /* error handling */
-    }
-
-    for(i=0; i<fifo.size; i++) {
-        printf("x: %d mg, y: %d mg, z: %d mg\n", fifo.x[i], fifo.y[i], fifo.z[i]);
-    }
-    
-    /* unregister interrupt */
-    if (int_unregister(GPIO_INTERRUPT_PIN)) {
-        /* error handling */
-    }
-
-    /* deinitalise struct */
-    if (lis3dh_deinit(&lis)) {
-        /* error handling */
-    }
-
-    return 0;
-}

lis3dh.c

@@ -283,8 +283,7 @@ int lis3dh_read_fifo(lis3dh_t *lis3dh, struct lis3dh_fifo_data *fifo) {
     } while (idx++ < lis3dh->cfg.fifo.size - 1 && !LIS3DH_FIFO_SRC_EMPTY(fifo_src) && !err);
 
     /* the device stores FIFO offsets rather than `size' so a size-32 FIFO */
-    /* has an offset of 31 */
-
+    /* has an offset of 31 ^ */
     fifo->size = idx;
 
     return err;
@@ -396,3 +395,28 @@ int lis3dh_read_temp(lis3dh_t *lis3dh) {
     lis3dh->adc.adc3 = (int8_t)data + 25;
     return err;
 }
+
+/* This function is meant to be used to reset the FIFO in `FIFO' mode. */
+int lis3dh_fifo_reset(lis3dh_t *lis3dh) {
+    /* 1. write BYPASS cfg */
+    /* 2. maybe sleep */
+    /* 3. write FIFO cfg as in configure() */
+    int err = 0;
+    uint8_t fifo_ctrl_reg = 0;
+
+    fifo_ctrl_reg |= ((lis3dh->cfg.fifo.size - 1) & 0x1F);
+    fifo_ctrl_reg |= (LIS3DH_FIFO_MODE_BYPASS << 6);
+    fifo_ctrl_reg |= ((lis3dh->cfg.fifo.trig & 1) << 5);
+
+    err |= lis3dh->dev.write(REG_FIFO_CTRL_REG, fifo_ctrl_reg);
+    lis3dh->dev.sleep(1000);
+
+    fifo_ctrl_reg |= ((lis3dh->cfg.fifo.size - 1) & 0x1F);
+    fifo_ctrl_reg |= (lis3dh->cfg.fifo.mode << 6);
+    fifo_ctrl_reg |= ((lis3dh->cfg.fifo.trig & 1) << 5);
+
+    err |= lis3dh->dev.write(REG_FIFO_CTRL_REG, fifo_ctrl_reg);
+
+    return err;
+
+}

lis3dh.h

@@ -53,20 +53,24 @@
 #define LIS3DH_ODR_LP_5376_HZ 0x09
 
 /* range/sens */
-#define LIS3DH_FS_2G 0x00
-#define LIS3DH_FS_4G 0x01
-#define LIS3DH_FS_8G 0x02
-#define LIS3DH_FS_16G 0x03
+#define LIS3DH_FS_2G  0x00 /* Full-scale sensing range: ± 2G */
+#define LIS3DH_FS_4G  0x01 /* Full-scale sensing range: ± 4G */
+#define LIS3DH_FS_8G  0x02 /* Full-scale sensing range: ± 8G */
+#define LIS3DH_FS_16G 0x03 /* Full-scale sensing range: ± 16G */
 
 /* operating modes */
-#define LIS3DH_MODE_HR 0x00
-#define LIS3DH_MODE_LP 0x01
-#define LIS3DH_MODE_NORMAL 0x02
+#define LIS3DH_MODE_HR     0x00 /* High resolution: 12-bit */
+#define LIS3DH_MODE_LP     0x01 /* Low-power: 8-bit */
+#define LIS3DH_MODE_NORMAL 0x02 /* Normal: 10-bit */
 
 /* FIFO modes */
-#define LIS3DH_FIFO_MODE_BYPASS 0x00
-#define LIS3DH_FIFO_MODE_NORMAL 0x01 /* "FIFO" */
-#define LIS3DH_FIFO_MODE_STREAM 0x02
+/* FIFO is not operational, and the buffer is reset. Must be used for switching FIFO modes */
+#define LIS3DH_FIFO_MODE_BYPASS         0x00
+/* Once FIFO fills up completely, it must be reset to be used again */
+#define LIS3DH_FIFO_MODE_FIFO           0x01 
+/* Continously (over)writes buffer until it is read */
+#define LIS3DH_FIFO_MODE_STREAM         0x02
+/* Stream mode, but automatically switches to FIFO mode once a set interrupt has occurred */
 #define LIS3DH_FIFO_MODE_STREAM_TO_FIFO 0x03
 
 /* FIFO trigger pin selection */
@@ -307,5 +311,6 @@ int lis3dh_reference(lis3dh_t *lis3dh);
 int lis3dh_reset(lis3dh_t *lis3dh);
 int lis3dh_read_adc(lis3dh_t *lis3dh);
 int lis3dh_read_temp(lis3dh_t *lis3dh);
+int lis3dh_fifo_reset(lis3dh_t *lis3dh);
 
 #endif

main.c

@@ -1,34 +1,46 @@
 #define _GNU_SOURCE
-#include <stdio.h>
-#include <stdlib.h>
 #include <unistd.h>
-#include <math.h>
+#include <stdio.h>
 #include "lis3dh.h"
-#include "spi.h"
+#include "i2c.h"
+#include "interrupt.h"
+
+#define GPIO_INTERRUPT_PIN_INT1 12
 
 int main() {
 
     lis3dh_t lis;
+    struct lis3dh_fifo_data fifo;
+    int i;
 
-    lis.dev.init = spi_init;
-    lis.dev.read = spi_read;
-    lis.dev.write = spi_write;
+    lis.dev.init = i2c_init;
+    lis.dev.read = i2c_read;
+    lis.dev.write = i2c_write;
     lis.dev.sleep = usleep;
-    lis.dev.deinit = spi_deinit;
+    lis.dev.deinit = i2c_deinit;
 
     lis3dh_init(&lis);
     lis3dh_reset(&lis);
+    int_register(GPIO_INTERRUPT_PIN_INT1);
 
-    lis.cfg.mode = LIS3DH_MODE_LP;
-    lis.cfg.range = LIS3DH_FS_16G;
-    lis.cfg.rate = LIS3DH_ODR_LP_5376_HZ;
+    lis.cfg.mode = LIS3DH_MODE_HR;
+    lis.cfg.range = LIS3DH_FS_2G;
+    lis.cfg.rate = LIS3DH_ODR_100_HZ;
+    lis.cfg.pin1.overrun = 1;
+    lis.cfg.fifo.mode = LIS3DH_FIFO_MODE_FIFO;
+    lis.cfg.fifo.trig = LIS3DH_FIFO_TRIG_INT1;
 
     lis3dh_configure(&lis);
 
     for ( ;; ) {
 
-        lis3dh_read(&lis);
-        printf("x: %4.4d mg, y: %4.4d mg, z: %4.4d mg\n", lis.acc.x, lis.acc.y, lis.acc.z);
+        int_poll(GPIO_INTERRUPT_PIN_INT1);
+        lis3dh_read_fifo(&lis, &fifo);
+        for(i=0; i<fifo.size; i++)
+            printf("x: %4.4d mg, y: %4.4d mg, z: %4.4d mg\n", fifo.x[i], fifo.y[i], fifo.z[i]);
+
+        printf("fifo.size=%d\n", fifo.size);
+        lis3dh_fifo_reset(&lis);
     }
 
     lis3dh_deinit(&lis);