From 4dcc5b109d90b97b1034c58dd000b21dab477050 Mon Sep 17 00:00:00 2001 From: William Clark Date: Sat, 6 Jan 2024 17:49:36 +0000 Subject: [PATCH] cleanup comments --- example/4d-movement.c | 2 +- example/4d-position.c | 4 ++-- example/6d-movement.c | 4 ++-- example/6d-position.c | 4 ++-- example/fifo.c | 12 +++++----- example/free-fall.c | 6 ++--- example/interrupts.c | 3 +-- example/temp.c | 2 -- lis3dh.c | 54 +++++++++++++++++++++++-------------------- lis3dh.h | 2 +- 10 files changed, 47 insertions(+), 46 deletions(-) diff --git a/example/4d-movement.c b/example/4d-movement.c index 06e041a..ef8d390 100644 --- a/example/4d-movement.c +++ b/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 */ } diff --git a/example/4d-position.c b/example/4d-position.c index f3cae98..f7505d4 100644 --- a/example/4d-position.c +++ b/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 .. */ diff --git a/example/6d-movement.c b/example/6d-movement.c index fc49a11..4b7c4a4 100644 --- a/example/6d-movement.c +++ b/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", diff --git a/example/6d-position.c b/example/6d-position.c index bafb0c3..7e1a208 100644 --- a/example/6d-position.c +++ b/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", diff --git a/example/fifo.c b/example/fifo.c index ac476e5..512765c 100644 --- a/example/fifo.c +++ b/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 */ - /* copy them to the fifo data struct given below as `data' */ - if (lis3dh_read_fifo(&lis, &data)) { + /* 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 -#include +#include /* NULL */ +#include /* memset() */ #include "lis3dh.h" #include "registers.h" -#include - +/* 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. - shift down the 16 bit word by this amount: */ + +/* The "real size" of the i16 accelerometer axis reading depends on the power mode. */ +/* 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 - turns it to a multiple of mg. */ +/* returns a scalar that when multiplied with axis reading */ +/* 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 - it uses the --current-- acceleration as the base in the filter */ +/* read REFERENCE reg to reset HP filter in REFERENCE mode */ +/* 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 - st 1 lsb is equal to 1 millivolt */ +/* read all 3 ADCs and convert data depending on power mode */ +/* 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, - and the factory calibrated temperature, 25 celsius. - in increments of plus or negative 1 unit celsius. - the reported temperature is stored inplace of adc3 - temp sensing is always in 8-bit mode - operating range: -40 to 85 celsius - 1 lsb = 1 deg C */ +/* the temperature sensor only reports the difference between its current temp, */ +/* and the factory calibrated temperature, 25 celsius. */ +/* in increments of plus or negative 1 unit celsius. */ +/* the reported temperature is stored inplace of adc3 */ +/* temp sensing is always in 8-bit mode */ +/* operating range: -40 to 85 celsius */ +/* 1 lsb = 1 deg C */ int lis3dh_read_temp(lis3dh_t *lis3dh) { uint8_t data; int err = 0; diff --git a/lis3dh.h b/lis3dh.h index 46e249a..79ecca0 100644 --- a/lis3dh.h +++ b/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];