lis3dh library update

Tilt functions added.

Author: AndyLindsay

Learn/Simple Libraries/Sensor/liblis3dh/cmm/liblis3dh.a

@@ -12,8 +12,8 @@
  * 
  */
 
-#include <stdlib.h>
-//#include "simpletools.h"
+//#include <stdlib.h>
+#include "simpletools.h"
 #include "lis3dh.h"
 
 
@@ -36,7 +36,7 @@ lis3dh_t *lis3dh_init4wire(int pinSCK, int pinSDI, int pinSDO, int pinCS)
   if (!(device = (lis3dh_t *)malloc(sizeof(lis3dh_t))))
         return NULL;
 
-  
+  // Store IO pins
   device->sdi_pin = pinSDI;
   device->sdo_pin = pinSDO; // Set the same for 3-wire SPI mode
   device->sck_pin = pinSCK;
@@ -73,6 +73,16 @@ lis3dh_t *lis3dh_init4wire(int pinSCK, int pinSDI, int pinSDO, int pinCS)
   lis3dh_setResolution(device, 12); // 8, 10 or 12 (bit)
   lis3dh_setRange(device, 2);       // 2, 4, 8 or 16 (g)
 
+  pause(100);
+  
+  
+  // Initialise tilt running averages based on current position of sensor
+  lis3dh_accel_mg(device, &device->tiltavgX, &device->tiltavgY, &device->tiltavgZ);
+  
+  // Set tilt moving average filter. Value represents the % of new data, for example 75 would represent 75% of new data, 25% old data    
+  device->tiltavg_factor = 100; // default to 100% of new data (ie. filter is off)
+       
+  
   return device;
 
 }

Learn/Simple Libraries/Sensor/liblis3dh/init.c

@@ -34,8 +34,8 @@ lis3dh *LIS3DH;
 int main()  // Main function
 {
 
-  int x, y, z;
-  
+  int x, y, z, ax, ay, az, motion;
+    
   pause(1000); // Start-up pause for debug terminal
   term_cmd(CLS);
   term_cmd(HOME);
@@ -44,6 +44,8 @@ int main()  // Main function
 
 
   LIS3DH = lis3dh_init(8, 7, 6); // pinSCK, pinSDI, pinCS
+  
+    
   pause(100);
 
   print("%c \r", CLREOL);
@@ -67,6 +69,10 @@ int main()  // Main function
 
   print("Acceleration range is +-%dg, Resolution is %d bit %c \r\r", lis3dh_getRange(LIS3DH), lis3dh_getResolution(LIS3DH), CLREOL);
 
+
+  
+  //lis3dh_tiltConfig(LIS3DH, 75); // Set tilt sensor moving average factor (low-pass filter)
+    
 
   while(1) {
 
@@ -100,9 +106,17 @@ int main()  // Main function
     print(" temp : %dC, sensor relative value is %d %c \r", lis3dh_temp_C(LIS3DH), lis3dh_tempRaw(LIS3DH), CLREOL);  // Display measurements
 
 
+    // Angles
+    if (lis3dh_tilt(LIS3DH, &ax, &ay, &az, &motion)) {
+      
+      print(" tilt : ax = %d, ay = %d, az = %d, motion = %d%c \r", ax, ay, az, motion, CLREOL );  // Display measurements
+     
+    } else { print(" tilt : data not ready %c \r", CLREOL ); } 
+    
+     
     // Debug terminal adjustment        
 
-    print("%c%c%c%c%c", CRSRUP, CRSRUP, CRSRUP, CRSRUP, CRSRUP); // Terminal up two lines, so results write back over same two lines when viewing on SimpleIDE Terminal or Parallax Serial Terminal 
+    print("%c%c%c%c%c%c", CRSRUP, CRSRUP, CRSRUP, CRSRUP, CRSRUP, CRSRUP); // Terminal up two lines, so results write back over same two lines when viewing on SimpleIDE Terminal or Parallax Serial Terminal 
 
 
     pause(250); // Minimum pause must be ODR * 2 in milliseconds (Examples: 50Hz ODR = 40ms pause, 400Hz ODR = 5ms pause)

Learn/Simple Libraries/Sensor/liblis3dh/liblis3dh.c

@@ -19,8 +19,9 @@ temp.c
 setADCmode.c
 adc.c
 adc_mV.c
+tilt.c
 >compiler=C
->memtype=cmm main ram compact
+>memtype=lmm main ram
 >optimize=-Os
 >-m32bit-doubles
 >-Wall

Learn/Simple Libraries/Sensor/liblis3dh/liblis3dh.side

@@ -122,7 +122,12 @@ extern "C" {
 typedef struct lis3dh_st
 {
   volatile int tempcalC; // for degrees Celcius
-    
+  
+  volatile int tiltavgX;
+  volatile int tiltavgY;
+  volatile int tiltavgZ;
+  volatile int tiltavg_factor;
+  
   int sdi_pin;
   int sdo_pin;
   int sck_pin;
@@ -148,6 +153,8 @@ typedef lis3dh_t lis3dh;
  */
 
 
+                      
+
 /**
  * @brief Initialize the sensor with typical configuration for reading axis and adc. Uses 3-Wire SPI mode
  *
@@ -541,6 +548,53 @@ int lis3dh_getAccel_mg(lis3dh_t *device, int axis);
 
 
 
+/**
+ * @brief Gets tilt angle measurements for each axis, and magnitude of motion.
+ *
+ * @details Angle to each axis in degrees, 
+                  X relative to ground
+                  Y relative to ground
+                  Z relative to gravity.
+            Motion is the sum of g-force on all axis relative to gravity at ground level (1G). 
+                  0 is motionless, larger positve or negative values represent more intense motion.
+                  The motion value could be used on it's own for projects requiring vibration sensing.
+            
+ * 
+ * @param device Pointer to the sensor device structure
+ *
+ * @param *ax Variable to store angle of x axis relative to ground.
+ * 
+ * @param *ay Variable to store angle of y axis relative to ground.
+ * 
+ * @param *az Variable to store angle of z axis relative to gravity.
+ *
+ * @param *motion Variable to store positive or negative value representing intensity of motion, with 0 being motionless at ground level.
+ * 
+ * @returns 1 if new data is available, 0 if no new data is available, or invalid request.
+ * 
+ */
+int lis3dh_tilt(lis3dh_t *device, int *ax, int *ay, int *az, int *motion);
+
+
+/**
+ * @brief Optional configuration for tilt sensor.
+ *
+ * @details Values stored in RAM. Reasonable defaults are set by the library.
+ * 
+ * @param device Pointer to the sensor device structure
+ *
+ * @param avg_factor Percentage of new data added to tilt readings low pass filter (moving average).
+ *                   Valid values are 0 to 100. (Setting 0 or 100 will disable the filter.
+ *                   For example, if avg_factor is 75, moving average calculation will include 75% new data and 25% existing data.
+ *                   Default value = 100 (moving average low pass filter disabled).
+ *
+ * @returns 1 if operation successful, 0 if operation failed (invalid values).
+ * 
+ */
+int lis3dh_tiltConfig(lis3dh_t *device, int avg_factor); 
+
+
+
 /**
  * @brief write a byte value to an LIS3DH register
  *

Learn/Simple Libraries/Sensor/liblis3dh/lis3dh.h

@@ -0,0 +1,144 @@
+
+/*
+ * @file tilt.c
+ *
+ * @author Michael Mulholland
+ *
+ * @version 1.0.0
+ *
+ * @copyright
+ * Copyright (C) Parallax, Inc. 2019. All Rights MIT Licensed.
+ *
+ * @brief Gets tilt angle measurements for all axis for the Parallax LIS3DH 3-Axis Accelerometer Module with ADC.
+ * 
+ * @detail Resolution is user-configured in the sensor as 8, 10 or 12 bit. (Refer to setResolution and getResolution functions)
+ *         Recommended to use 2g acceleration range (setRange) for tilt sensing
+ * 
+ * @returns 1 if data available and angles for all 3 axis (x, y, z). Otherwise returns 0.
+ * 
+ */
+
+
+#include "simpletools.h"
+#include "lis3dh.h"
+
+
+
+// Helper function for Tilt angle value limiting
+
+int lis3dh_limitangle(int angle) {
+  
+  if (angle < -90) { return -90; }
+  if (angle >  90) { return  90; }
+  return angle;
+  
+}
+
+// Helper function to apply scale and rounding to tilt angles
+
+int lis3dh_scaleresult(int value) {
+  
+  int i, r;
+  
+  i = value / 100;
+  r = value - (i * 100);
+  
+  return (r > 49) ? ++i : i;
+    
+}
+
+  
+int lis3dh_tilt(lis3dh_t *device, int *ax, int *ay, int *az, int *motion)
+{
+        
+  int x, y, z;
+  int avg_factor = device->tiltavg_factor;
+    
+  if (lis3dh_accel_mg(device, &x, &y, &z)) {
+    
+    // Calculate moving average (low pass filter)
+    // Setting the avg_factor value to 0 or 100 will disable the filter.
+    
+    if ((avg_factor > 0) && (avg_factor < 100)) {
+      
+        x = lis3dh_scaleresult((x * avg_factor) + (device->tiltavgX * (100 - avg_factor )));
+        y = lis3dh_scaleresult((y * avg_factor) + (device->tiltavgY * (100 - avg_factor )));
+        z = lis3dh_scaleresult((z * avg_factor) + (device->tiltavgZ * (100 - avg_factor )));
+        
+        device->tiltavgX = x; // Write back averages for next time
+        device->tiltavgY = y;
+        device->tiltavgZ = z;
+    
+    }   
+    
+
+    // Calculate angle to each axis in radians
+    
+    // X relative to ground
+    // Y relative to ground
+    // Z relative to gravity
+    
+    float y_radians = atan(((float)y/(sqrt(x*x + z*z))));
+    float x_radians = atan(((float)x/(sqrt(y*y + z*z))));
+    float z_radians = atan((sqrt(x*x + y*y) / z));
+    
+    // Convert angles from radians to degrees
+    // 1 radian × 180/pi = 57.296°
+
+    *ay = lis3dh_limitangle( (int) (y_radians * 57.3) );
+    *ax = lis3dh_limitangle( (int) (x_radians * 57.3) );
+    *az = lis3dh_limitangle( (int) (z_radians * 57.3) );
+    
+    // Calculate motion value; 0 at 1G, increases or decreases with motion detected (sign represents dominant direction)
+    *motion = (int) (sqrt(x*x + y*y + z*z)) - 1000; // Deduct 1G (1000 milliG's) from result to offset from ground level.
+  
+  
+    return 1; // OK !
+    
+  }
+  
+  return 0; // Return 0 if no data available                                       
+  
+}
+
+
+
+int lis3dh_tiltConfig(lis3dh_t *device, int avg_factor) {
+                        
+  if ((avg_factor < 0) || (avg_factor > 100)) 
+  { 
+    return 0; // Invalid ratio
+  }
+  
+  
+  device->tiltavg_factor = avg_factor;
+  return 1;  // Configuration values accepted OK
+    
+}
+
+    
+
+/**
+ * TERMS OF USE: MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+
+

Learn/Simple Libraries/Sensor/liblis3dh/lmm/liblis3dh.a

@@ -1 +1 @@
-v1.4.136
+v1.4.137