Merge pull request #11 from dbns97/patch-1

Added FIFO buffer support

Author: betzrhodes

LIS3DH.class.nut

@@ -1,5 +1,5 @@
 class LIS3DH {
-    static version = [1,2,0];
+    static version = [1,3,0];
 
     // Registers
     static TEMP_CFG_REG  = 0x1F;
@@ -15,6 +15,8 @@ class LIS3DH {
     static OUT_Y_H       = 0x2B;
     static OUT_Z_L       = 0x2C;
     static OUT_Z_H       = 0x2D;
+    static FIFO_CTRL_REG = 0x2E;
+    static FIFO_SRC_REG  = 0x2F;
     static INT1_CFG      = 0x30;
     static INT1_SRC      = 0x31;
     static INT1_THS      = 0x32;
@@ -53,6 +55,11 @@ class LIS3DH {
     static HPF_REFERENCE_SIGNAL = 0x40;
     static HPF_NORMAL_MODE = 0x80;
     static HPF_AUTORESET_ON_INTERRUPT = 0xC0;
+    
+    static FIFO_BYPASS_MODE = 0x00;
+    static FIFO_FIFO_MODE = 0x40;
+    static FIFO_STREAM_MODE = 0x80;
+    static FIFO_STREAM_TO_FIFO_MODE = 0xC0;
 
     // Click Detection values
     static SINGLE_CLICK  = 0x15;
@@ -94,6 +101,7 @@ class LIS3DH {
         _setReg(TIME_LIMIT, 0x00);
         _setReg(TIME_LATENCY, 0x00);
         _setReg(TIME_WINDOW, 0x00);
+        _setReg(FIFO_CTRL_REG, 0x00);
 
         // Read the range + set _range property
         getRange();
@@ -254,6 +262,24 @@ class LIS3DH {
 
     //-------------------- INTERRUPTS --------------------//
 
+    // Enable/disable and configure FIFO buffer watermark interrupts
+    function configureFifoInterrupt(state, fifomode = 0x80, watermark = 28) {
+        
+        // Enable/disable the FIFO buffer
+        _setRegBit(CTRL_REG5, 6, state ? 1 : 0);
+        
+        if (state) {
+            // Stream-to-FIFO mode, watermark of [28].
+            _setReg(FIFO_CTRL_REG, (fifomode & 0xc0) | (watermark & 0x1F)); 
+        } else {
+            _setReg(FIFO_CTRL_REG, 0x00); 
+        }
+        
+        // Enable/disable watermark interrupt
+        _setRegBit(CTRL_REG3, 2, state ? 1 : 0);
+        
+    }
+
     // Enable/disable and configure inertial interrupts
     function configureInertialInterrupt(state, threshold = 2.0, duration = 5, options = null) {
         // Set default value for options (using statics, so can't set in ftcn declaration)
@@ -345,6 +371,16 @@ class LIS3DH {
             "doubleClick":  (click & 0x20) != 0
         }
     }
+    
+    function getFifoStats() {
+        local stats = _getReg(FIFO_SRC_REG);
+        return {
+            "watermark": (stats & 0x80) != 0,
+            "overrun": (stats & 0x40) != 0,
+            "empty": (stats & 0x20) != 0,
+            "unread": (stats & 0x1F) + ((stats & 0x40) ? 1 : 0) 
+        }
+    }
 
 
     //-------------------- PRIVATE METHODS --------------------//
@@ -390,5 +426,7 @@ class LIS3DH {
         server.log(format("INT1_CFG 0x%02X", _getReg(INT1_CFG)));
         server.log(format("INT1_SRC 0x%02X", _getReg(INT1_SRC)));
         server.log(format("INT1_THS 0x%02X", _getReg(INT1_THS)));
+        server.log(format("FIFO_CTRL_REG 0x%02X", _getReg(FIFO_CTRL_REG)));
+        server.log(format("FIFO_SRC_REG 0x%02X", _getReg(FIFO_SRC_REG)));
     }
 }

README.md

@@ -4,7 +4,7 @@ The [LIS3DH](http://www.st.com/st-web-ui/static/active/en/resource/technical/doc
 
 The LPS25H can interface over I²C or SPI. This class addresses only I²C for the time being.
 
-**To add this library to your project, add** `#require "LIS3DH.class.nut:1.2.0"` **to the top of your device code**
+**To add this library to your project, add** `#require "LIS3DH.class.nut:1.3.0"` **to the top of your device code**
 
 ## Class Usage
 
@@ -20,7 +20,7 @@ The class’ constructor takes one required parameter (a configured imp I²C
 &nbsp;<br>
 
 ```squirrel
-#require "LIS3DH.class.nut:1.2.0"
+#require "LIS3DH.class.nut:1.3.0"
 
 i2c <- hardware.i2c89;
 i2c.configure(CLOCK_SPEED_400_KHZ);
@@ -127,6 +127,70 @@ The *getRange()* method returns the currently-set measurement range of the senso
 server.log(format("Current Sensor Range is +/- %dG", accel.getRange()));
 ```
 
+### configureFifoInterrupt(*state[, fifomode][, watermark]*)
+
+This method configures an interrupt when the FIFO buffer reaches the set watermark:
+
+| Parameter | Type | Default Value | Description |
+| --------- | ---- | ------------- | ----------- |
+| *state* | Boolean | N/A | `true` to enable, `false` to disable |
+| *fifomode* | bitfield | *FIFO_STREAM_MODE* | See table below |
+| *watermark* | Integer | 28 | Number of buffer slots filled to generate<br> interrupt (buffer has 32 slots) |
+
+This example sets the FIFO buffer to Stream Mode and reads the data from
+the buffer whenever the watermark is reached:
+
+```squirrel
+// Function to read from FIFO buffer
+function readBuffer() {
+    
+    if (wakePin.read() == 0) return;
+    
+    // Read buffer
+    local stats = accel.getFifoStats();
+    for (local i = 0; i < stats.unread; ++i) {
+        local data = accel.getAccel();
+        server.log(format("Accel (x,y,z): [%d, %d, %d]", data.x, data.y, data.z));
+    }
+
+    // Check if we are now overrun        
+    local stats = accel.getFifoStats();
+    if (stats.overrun) {
+        server.error("Accelerometer buffer overrun")
+        
+        // Set FIFO mode to bypass to clear the buffer and then return to stream mode
+        accel.configureFifoInterrupt(true, accel.FIFO_BYPASS_MODE);
+        accel.configureFifoInterrupt(true, accel.FIFO_STREAM_MODE, 30);
+    }
+
+}
+
+i2c  <- hardware.i2cAB;
+i2c.configure(CLOCK_SPEED_400_KHZ);
+accel <- LIS3DH(i2c);
+
+// Configure interrupt pin
+wakePin <- hardware.pinW;
+wakePin.configure(DIGITAL_IN_PULLDOWN, readBuffer);
+
+// Configure accelerometer
+accel.init();
+accel.setDataRate(100);
+
+// Configure the FIFO buffer in Stream Mode and set interrupt generator to
+// generate an interrupt when there are 30 entries in the buffer
+accel.configureFifoInterrupt(true, accel.FIFO_STREAM_MODE, 30);
+```
+
+#### FIFO modes
+    
+| Mode | Description |
+| ---- | ----------- |
+| *FIFO_BYPASS_MODE*  | Disables the FIFO buffer (only the first address is used for each channel) |
+| *FIFO_FIFO_MODE* | When full, the FIFO buffer stops collecting data from the input channels |
+| *FIFO_STREAM_MODE*  | When full, the FIFO buffer discards the older data as the new arrive |
+| *FIFO_STREAM_TO_FIFO_MODE* | When full, the FIFO buffer discards the older data as the new arrive.<br> Once trigger event occurs, the FIFO buffer starts operating in FIFO mode.  |
+
 ### configureInertialInterrupt(*state[, threshold][, duration][, options]*)
 
 This method configures the inertial interrupt generator:
@@ -353,6 +417,17 @@ switch(hardware.wakereason()) {
 }
 ```
 
+### getFifoStats()
+
+This method returns information about the state of the FIFO buffer in a squirrel table:
+
+| Value | Type | Description |
+| --- | --- | --- | --- |
+| *watermark* | Boolean | `true` if watermark has been set |
+| *overrun* | Boolean | `true` if data has been overwritten without being read |
+| *empty* | Boolean | `true` if buffer is empty  |
+| *unread* | Integer | Number of unread slots in buffer |
+
 ### configureHighPassFilter(*filters[, cutoff][, mode]*)
 
 This method configures the high-pass filter.