cleanup comments

example/4d-movement.c

@@ -25,7 +25,7 @@ int main() {
         /* error handling */
     }
 
-    /* reset device because it sometimes corrupts itself */
+    /* reset device just in case */
     if (lis3dh_reset(&lis)) {
         /* error handling */
     }

example/4d-position.c

@@ -25,7 +25,7 @@ int main() {
         /* error handling */
     }
 
-    /* reset device because it sometimes corrupts itself */
+    /* reset device just in case */
     if (lis3dh_reset(&lis)) {
         /* error handling */
     }
@@ -106,7 +106,7 @@ int main() {
             /* error handling */
         }
 
-        /* only print if INT1 interrupt active = 1*/
+        /* only print if INT1 interrupt active (IA) = 1*/
         /* ZH and ZL are always 0 in 4D mode */
         if (LIS3DH_INT_SRC_IA(lis.src.int1)) {
             /* print received interrupt .. */

example/6d-movement.c

@@ -25,7 +25,7 @@ int main() {
         /* error handling */
     }
 
-    /* reset device because it sometimes corrupts itself */
+    /* reset device just in case */
     if (lis3dh_reset(&lis)) {
         /* error handling */
     }
@@ -107,7 +107,7 @@ int main() {
             /* error handling */
         }
 
-        /* only print if INT1 interrupt active = 1*/
+        /* only print if INT1 interrupt active (IA) = 1*/
         if (LIS3DH_INT_SRC_IA(lis.src.int1)) {
             /* print received interrupt .. */
             printf("IA=%d ZH=%d ZL=%d YH=%d YL=%d XH=%d XL=%d\n",

example/6d-position.c

@@ -25,7 +25,7 @@ int main() {
         /* error handling */
     }
 
-    /* reset device because it sometimes corrupts itself */
+    /* reset device just in case */
     if (lis3dh_reset(&lis)) {
         /* error handling */
     }
@@ -107,7 +107,7 @@ int main() {
             /* error handling */
         }
 
-        /* only print if INT1 interrupt active = 1*/
+        /* only print if INT1 interrupt active (IA) = 1*/
         if (LIS3DH_INT_SRC_IA(lis.src.int1)) {
             /* print received interrupt .. */
             printf("IA=%d ZH=%d ZL=%d YH=%d YL=%d XH=%d XL=%d\n",

example/fifo.c

@@ -7,7 +7,7 @@
 int main() {
 
     lis3dh_t lis;
-    struct lis3dh_fifo_data data;
+    struct lis3dh_fifo_data fifo;
     int i;
 
     lis.dev.init = i2c_init;
@@ -36,15 +36,15 @@ int main() {
         /* error handling */
     }
 
-    /* read as many [x y z] sets as specified by watermark level (size) default max/32 */
+    /* read as many [x y z] sets as specified by watermark level (size) default (max/32) */
-    /* copy them to the fifo data struct given below as `data' */
+    /* copy them to the fifo data struct `fifo' */
-    if (lis3dh_read_fifo(&lis, &data)) {
+    if (lis3dh_read_fifo(&lis, &fifo)) {
         /* error handling */
     }
 
     /* read out fifo buffer data */
-    for(i=0; i<data.size; i++) {
+    for(i=0; i<fifo.size; i++) {
-        printf("x: %d mg, y: %d mg, z: %d mg\n", data.x[i], data.y[i], data.z[i]);
+        printf("x: %d mg, y: %d mg, z: %d mg\n", fifo.x[i], fifo.y[i], fifo.z[i]);
     }
 
     /* deinitialise struct */

example/free-fall.c

@@ -46,9 +46,9 @@ int main() {
     lis.cfg.int1.latch = 1; /* latch interrupt until INT1_SRC is read */
 
     /* enable all the low directions */
-    /* this works because the low directions are compared to -threshold,
+    /* this works because the low directions are compared to -threshold, */
-       and are below it at rest, and greater than it at free-fall,
+    /* and are below it at rest, and greater than it at free-fall, */
-       while the opposite is true for the high directions. */
+    /* while the opposite is true for the high directions. */
     lis.cfg.int1.xl = 1;
     lis.cfg.int1.yl = 1;
     lis.cfg.int1.zl = 1;

example/interrupts.c

@@ -64,13 +64,12 @@ int main() {
         /* error handling */
     }
 
-    /* read as many [x y z] sets as specified by watermark level (fth) */
+    /* 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 */
     }
 
-    /* above function also writes out the qty of [x y z] sets stored in `fifo' */
     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]);
     }

example/temp.c

@@ -52,8 +52,6 @@ int main() {
 
     printf("ADC1: %d mV\n", lis.adc.adc1);
     printf("ADC2: %d mV\n", lis.adc.adc2);
-    
-    /* no decimals, step size is 1 celsius */
     printf("ADC3: %d oC\n", lis.adc.adc3);
 
     /* deinitalise struct */

lis3dh.c

@@ -1,10 +1,9 @@
-#include <stddef.h>
+#include <stddef.h> /* NULL */
-#include <string.h>
+#include <string.h> /* memset() */
 #include "lis3dh.h"
 #include "registers.h"
-#include <stdio.h>
-
 
+/* initialise device struct and read WHO_AM_I register */
 int lis3dh_init(lis3dh_t *lis3dh) {
     uint8_t result;
     int err = 0;
@@ -37,6 +36,8 @@ int lis3dh_init(lis3dh_t *lis3dh) {
     return err;
 }
 
+/* write configuration options to the device */
+/* then sleep 100 ms to let it set itself up properly */
 int lis3dh_configure(lis3dh_t *lis3dh) {
     uint8_t ctrl_reg1, ctrl_reg2, ctrl_reg3;
     uint8_t ctrl_reg4, ctrl_reg5, ctrl_reg6;
@@ -177,7 +178,7 @@ int lis3dh_configure(lis3dh_t *lis3dh) {
     ctrl_reg0 |= (lis3dh->cfg.sdo_pullup & 1) << 7;
 
 
-    /* Registers have to be set in this order for SPI to function correctly */
+    /* Registers have to be set in this order for SPI to function correctly, I think */
     err |= lis3dh->dev.write(REG_CTRL_REG4, ctrl_reg4);
     err |= lis3dh->dev.write(REG_CTRL_REG5, ctrl_reg5);
     err |= lis3dh->dev.write(REG_FIFO_CTRL_REG, fifo_ctrl_reg);
@@ -206,9 +207,9 @@ int lis3dh_configure(lis3dh_t *lis3dh) {
     return err;
 }
 
-/* the real size of the int you get back from reading the acc u16 
+ 
-   depends on the power mode. 
+/* The "real size" of the i16 accelerometer axis reading depends on the power mode. */
-   shift down the 16 bit word by this amount: */
+/* shift down the 16 bit word by this amount: */
 static uint8_t acc_shift(uint8_t mode) {
     switch (mode) {
         case LIS3DH_MODE_HR:     return 4;  /* i12 */
@@ -218,8 +219,8 @@ static uint8_t acc_shift(uint8_t mode) {
     }
 }
 
-/* returns a scalar that when multiplied with axis reading
+/* returns a scalar that when multiplied with axis reading */
-   turns it to a multiple of mg. */
+/* turns it to a multiple of mg (1/1000 g). */
 static uint8_t acc_sensitivity(uint8_t mode, uint8_t range) {
     switch (range) {
         case LIS3DH_FS_2G:    return (mode == LIS3DH_MODE_LP) ? 16  : (mode == LIS3DH_MODE_NORMAL) ? 4  : 1;
@@ -240,6 +241,7 @@ int lis3dh_read(lis3dh_t *lis3dh) {
     sens = acc_sensitivity(lis3dh->cfg.mode, lis3dh->cfg.range);
 
     /* poll STATUS_REG until new data is available */
+
     do {
         err |= lis3dh->dev.read(REG_STATUS_REG, &status, 1);
         lis3dh->dev.sleep(1000);
@@ -253,18 +255,17 @@ int lis3dh_read(lis3dh_t *lis3dh) {
     return err;
 }
 
-/* assume fifo has been configured and poll'd */
+/* assume fifo has been configured */
 /* wait until FIFO is NOT empty, then */
 /* read groups of the 6 OUT bytes until EMPTY flag in FIFO_SRC is set */
 int lis3dh_read_fifo(lis3dh_t *lis3dh, struct lis3dh_fifo_data *fifo) {
-    uint8_t data[6]; /* max size */
+    uint8_t data[6]; 
     uint8_t sens, fifo_src;
     int err = 0;
     int idx = 0;
 
     /* wait until there is at least 1 unread sample in the FIFO */
-    /* otherwise can cause problems at really fast ODRs and calling this */
+
-    /* function in a loop without delays. */
     do {
         err |= lis3dh->dev.read(REG_FIFO_SRC_REG, &fifo_src, 1);
         lis3dh->dev.sleep(1000);
@@ -281,6 +282,9 @@ int lis3dh_read_fifo(lis3dh_t *lis3dh, struct lis3dh_fifo_data *fifo) {
         fifo->z[idx] = ((int16_t)(data[5] | data[4] << 8) >> 6) * sens;
     } 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 */
+
     fifo->size = idx;
 
     return err;
@@ -310,8 +314,8 @@ int lis3dh_read_click(lis3dh_t *lis3dh) {
     return lis3dh->dev.read(REG_CLICK_SRC, &lis3dh->src.click, 1);
 }
 
-/* read REFERENCE reg to reset HP filter in REFERENCE mode
+/* read REFERENCE reg to reset HP filter in REFERENCE mode */
-   it uses the --current-- acceleration as the base in the filter */
+/* it then uses the --current-- acceleration as the base in the filter */
 int lis3dh_reference(lis3dh_t *lis3dh) {
     uint8_t res;
     return lis3dh->dev.read(REG_REFERENCE, &res, 1);
@@ -359,8 +363,8 @@ int lis3dh_reset(lis3dh_t *lis3dh) {
     return err;
 }
 
-/* read all 3 ADCs and convert readings depending on power mode
+/* read all 3 ADCs and convert data depending on power mode */
-   st 1 lsb is equal to 1 millivolt */
+/* result: 1 lsb is equal to 1 millivolt */
 int lis3dh_read_adc(lis3dh_t *lis3dh) {
     uint8_t data[6];
     uint8_t shift;
@@ -377,13 +381,13 @@ int lis3dh_read_adc(lis3dh_t *lis3dh) {
     return err;
 }
 
-/* the temperature sensor only reports the difference between its current temp,
+/* the temperature sensor only reports the difference between its current temp, */
-   and the factory calibrated temperature, 25 celsius.
+/* and the factory calibrated temperature, 25 celsius. */
-   in increments of plus or negative 1 unit celsius.
+/* in increments of plus or negative 1 unit celsius. */
-   the reported temperature is stored inplace of adc3 
+/* the reported temperature is stored inplace of adc3 */
-   temp sensing is always in 8-bit mode 
+/* temp sensing is always in 8-bit mode */
-   operating range: -40 to 85 celsius 
+/* operating range: -40 to 85 celsius */
-   1 lsb = 1 deg C */
+/* 1 lsb = 1 deg C */
 int lis3dh_read_temp(lis3dh_t *lis3dh) {
     uint8_t data;
     int err = 0;

lis3dh.h

@@ -289,7 +289,7 @@ typedef struct lis3dh lis3dh_t;
 /* struct for containing the FIFO data */
 /* 1 lsb = 1 mg */
 struct lis3dh_fifo_data {
-    uint8_t size; /* up to 32 */
+    uint8_t size; /* up to 31 */
     int16_t x[32];
     int16_t y[32];
     int16_t z[32];