cleanup and code examples in README

README.md

@@ -1,10 +1,10 @@
 # LIS3DH
 
-A C89 driver for the 3-axis accelerometer LIS3DH by ST. Supports both i2c and SPI. 
+A C89 driver for the 3-axis accelerometer LIS3DH. Supports both i2c and SPI. 
 
 > ### Features
 > - FIFO of varying watermark level, up to 32
-> - HP filter
+> - HP filter (4 c/o freq)
 > - 2G, 4G, 8G and 16G
 > - All power modes
 > - Interrupt generation (soon)
@@ -12,66 +12,314 @@ A C89 driver for the 3-axis accelerometer LIS3DH by ST. Supports both i2c and SP
 > - Single and double click detection (soon)
 > - 4D/6D orientation detection (soon)
 
-FIFO output example
-
-```
-$ ./lis3dh 
-x: 0.5320, y: -0.8800, z: -0.0600 mag: 1.0301
-x: 0.5440, y: -0.8680, z: -0.0760 mag: 1.0272
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0760 mag: 1.0306
-x: 0.5440, y: -0.8720, z: -0.0720 mag: 1.0303
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0720 mag: 1.0392
-x: 0.5480, y: -0.8800, z: -0.0800 mag: 1.0398
-x: 0.5480, y: -0.8960, z: -0.0960 mag: 1.0547
-```
-
 > ### Notes
 > FIFO is always and only 10-bit
 
 
-### Noise at 2G
+## Usage
-![DC noise at 2G](.gitea/graph-2g.png)
+Simple example:
+```c
+#define _GNU_SOURCE
+#include <unistd.h> /* usleep() */
+#include <stdio.h>
+#include "lis3dh.h"
+#include "i2c.h"
 
-![DC noise at 2G](.gitea/graph-2g-filter.png)
+int main() {
-### Noise at 4G
-![DC noise at 4G](.gitea/graph-4g.png)
     
-![DC noise at 2G](.gitea/graph-4g-filter.png)
+	lis3dh_t lis;
-### Noise at 8G
-![DC noise at 8G](.gitea/graph-8g.png)
 
-![DC noise at 2G](.gitea/graph-8g-filter.png)
+	lis.dev.init = i2c_init;
-### Noise at 16G
+    lis.dev.read = i2c_read;
-![DC noise at 16G](.gitea/graph-16g.png)
+    lis.dev.write = i2c_write;
+    lis.dev.sleep = usleep;
+    lis.dev.deinit = i2c_deinit;
 
-![DC noise at 2G](.gitea/graph-16g-filter.png)
+	if (lis3dh_init(&lis)) {
+        /* error handling */
+    }
 
-## Using i2c on STM32
+	lis.cfg.mode = LIS3DH_MODE_HR;
+    lis.cfg.range = LIS3DH_FS_4G;
+    lis.cfg.rate = LIS3DH_ODR_100_HZ;
+
+	if (lis3dh_configure(&lis)) {
+        /* error handling */
+    }
+
+	if (lis3dh_poll(&lis)) {
+        /* error handling */
+	}
+
+	if (lis3dh_read(&lis)) {
+        /* error handling */
+	}
+
+	printf("x: %f, y: %f, z: %f\n", lis.acc.x, lis.acc.y, lis.acc.z);
+
+	if (lis3dh_deinit(&lis)) {
+        /* error handling */
+	}
+
+	return 0;
+}
+```
+The output should be something similar to this:
+```
+$ ./lis3dh 
+x: 0.540000, y: -0.882000, z: -0.100000
+```
+poll() and read() can be indefinitely looped for a constant data stream, like this:
+```c
+#define _GNU_SOURCE
+#include <unistd.h>
+#include <stdio.h>
+#include "lis3dh.h"
+#include "i2c.h"
+
+int main() {
+
+	lis3dh_t lis;
+    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;
+
+	if (lis3dh_init(&lis)) {
+        /* error handling */
+    }
+
+	lis.cfg.mode = LIS3DH_MODE_HR;
+    lis.cfg.range = LIS3DH_FS_4G;
+    lis.cfg.rate = LIS3DH_ODR_100_HZ;
+
+	if (lis3dh_configure(&lis)) {
+        /* error handling */
+    }
+
+    for(i=0; i<10; i++) {
+
+        if (lis3dh_poll(&lis)) {
+            /* error handling */
+	    }
+
+	    if (lis3dh_read(&lis)) {
+            /* error handling */
+	    }
+
+        printf("x: %f, y: %f, z: %f\n", lis.acc.x, lis.acc.y, lis.acc.z);
+    }
+
+	if (lis3dh_deinit(&lis)) {
+        /* error handling */
+	}
+
+	return 0;
+}
+```
+Output:
+```
+$ ./lis3dh 
+x: 0.534000, y: -0.882000, z: -0.102000
+x: 0.538000, y: -0.866000, z: -0.136000
+x: 0.518000, y: -0.846000, z: -0.100000
+x: 0.518000, y: -0.840000, z: -0.098000
+x: 0.542000, y: -0.876000, z: -0.098000
+x: 0.518000, y: -0.834000, z: -0.146000
+x: 0.512000, y: -0.854000, z: -0.106000
+x: 0.574000, y: -0.870000, z: -0.122000
+x: 0.518000, y: -0.846000, z: -0.098000
+x: 0.516000, y: -0.852000, z: -0.112000
+```
+## Using FIFO
+Instead of polling for every single [x y z] set, a FIFO with programmable capacity ("watermark") can be used like such:
+
+It should be noted that all FIFO readings use 10-bit resolution regardless of the mode. The watermark level can also be adjusted to a value [0-32] inclusive by modifying the `lis.cfg.fifo.fth` property before calling configure().
+```c
+#define _GNU_SOURCE
+#include <unistd.h>
+#include <stdio.h>
+#include "lis3dh.h"
+#include "i2c.h"
+
+int main() {
+
+	lis3dh_t lis;
+    struct lis3dh_fifo_data data;
+    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;
+
+	if (lis3dh_init(&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;
+
+	if (lis3dh_configure(&lis)) {
+        /* error handling */
+    }
+
+    if (lis3dh_poll_fifo(&lis)) {
+        /* error handling */
+    }
+
+    if (lis3dh_read_fifo(&lis, &data)) {
+        /* error handling */
+    }
+
+    /* read out fifo buffer data */
+    for(i=0; i<data.size; i++) {
+        printf("x: %f, y: %f, z: %f\n", data.x[i], data.y[i], data.z[i]);
+    }
+
+	if (lis3dh_deinit(&lis)) {
+        /* error handling */
+	}
+
+	return 0;
+}
+```
+Output:
+```
+$ ./lis3dh 
+x: 0.544000, y: -0.904000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.528000, y: -0.880000, z: -0.104000
+x: 0.528000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.104000
+x: 0.536000, y: -0.880000, z: -0.128000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.568000, y: -0.872000, z: -0.160000
+x: 0.560000, y: -0.872000, z: -0.160000
+```
+## Using the HP filter
+The LIS3DH can optionally apply a HP filter on the sample data. It can be used to greatly reduce the "DC acceleration" present.
+```c
+#define _GNU_SOURCE
+#include <unistd.h>
+#include <stdio.h>
+#include "lis3dh.h"
+#include "i2c.h"
+
+int main() {
+
+	lis3dh_t lis;
+    struct lis3dh_fifo_data data;
+    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;
+
+	if (lis3dh_init(&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;
+    lis.cfg.filter.mode = LIS3DH_FILTER_MODE_AUTORESET;
+    lis.cfg.filter.cutoff = LIS3DH_FILTER_CUTOFF_8;
+
+	if (lis3dh_configure(&lis)) {
+        /* error handling */
+    }
+
+    if (lis3dh_poll_fifo(&lis)) {
+        /* error handling */
+    }
+
+    if (lis3dh_read_fifo(&lis, &data)) {
+        /* error handling */
+    }
+
+    /* read out fifo buffer data */
+    for(i=0; i<data.size; i++) {
+        printf("x: %f, y: %f, z: %f\n", data.x[i], data.y[i], data.z[i]);
+    }
+
+	if (lis3dh_deinit(&lis)) {
+        /* error handling */
+	}
+
+	return 0;
+}
+```
+Output:
+```
+$ ./lis3dh 
+x: 0.008000, y: 0.000000, z: 0.000000
+x: 0.000000, y: 0.000000, z: 0.016000
+x: -0.016000, y: -0.008000, z: -0.008000
+x: -0.032000, y: 0.008000, z: 0.000000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.032000
+x: 0.024000, y: -0.016000, z: -0.008000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.016000, y: -0.032000, z: -0.040000
+x: -0.008000, y: -0.024000, z: -0.008000
+```
+
+### Using i2c on STM32
 Simple example code
 ```c
 #define LIS3DH_I2C_ADDR 0x18
@@ -89,3 +337,4 @@ int i2c_read(uint8_t reg, uint8_t *dst, uint32_t size) {
 	return 0;
 }
 ```
+

main.c

@@ -38,7 +38,7 @@ int main() {
     }
 
     /* set up config */
-    lis.cfg.mode = LIS3DH_MODE_HR;
+    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;
@@ -48,7 +48,7 @@ int main() {
         quit("configure()", &lis);
     }
 
-    for (i=0; i<50; i++) {
+    for (i=0; i<100; i++) {
     
         /* poll fifo reg */
         if (lis3dh_poll_fifo(&lis)) {
@@ -61,7 +61,7 @@ int main() {
         }
 
         for(k=0; k<fifo.size; k++) {
-            printf("x: %04.04f, y: %04.04f, z: %04.04f mag: %04.04f\n",
+            printf("%04.04f %04.04f %04.04f %04.04f\n",
                 fifo.x[k], fifo.y[k], fifo.z[k],
                 mag(fifo.x[k], fifo.y[k], fifo.z[k]));
         }

plot.gp

@@ -1,41 +0,0 @@
-# gnuplot
-reset
-
-set terminal pngcairo enhanced size 1920/2,1080/2
-set grid
-set key box opaque
-
-set ylabel "|[x y z]| - 1g"
-set xlabel "Samples over time"
-set yrange [-0.3:0.1]
-
-n(g) = g - 1.0
-
-do for [g in "2g 4g 8g 16g"] {
-    name = sprintf("graph-%s", g)
-    out = sprintf("%s.png", name)
-    stub = sprintf("data/fifo_%s_", g)
-    set title sprintf("[%s FIFO] comparison of ODR setting effect on magnitude of [x y z] acc vector (- 1g)", g)
-    set output out
-    plot stub."50.txt" u n(4) w p ps 0.3 t "50 Hz", \
-         stub."100.txt" u n(4) w p ps 0.3 t "100 Hz", \
-         stub."200.txt" u n(4) w p ps 0.3 t "200 Hz", \
-         stub."400.txt" u n(4) w p ps 0.3 t "400 Hz", \
-}
-
-set ylabel "|[x y z]|"
-set xlabel "Samples over time"
-set yrange [-0.1:0.1]
-
-
-do for [g in "2g 4g 8g 16g"] {
-    name = sprintf("graph-%s-filter", g)
-    out = sprintf("%s.png", name)
-    stub = sprintf("data/filt_%s_", g)
-    set title sprintf("[%s AUTORESET filter] comparison of f_{cutoff} DC acc. removal", g)
-    set output out
-    plot stub."1.txt" u n(4) w p ps 0.3 t "1", \
-         stub."2.txt" u n(4) w p ps 0.3 t "2", \
-         stub."4.txt" u n(4) w p ps 0.3 t "4", \
-         stub."8.txt" u n(4) w p ps 0.3 t "8", \
-}