LSM9DS1.h

/******************************************************************************
SFE_LSM9DS1.h
SFE_LSM9DS1 Library Header File
Jim Lindblom @ SparkFun Electronics
Original Creation Date: February 27, 2015
https://github.com/sparkfun/LSM9DS1_Breakout
 
2020-2022, Bernd Porr, mail@berndporr.me.uk
 
This file prototypes the LSM9DS1 class, implemented in SFE_LSM9DS1.cpp. In
addition, it defines every register in the LSM9DS1 (both the Gyro and Accel/
Magnetometer registers).
 
Development environment specifics:
    Hardware Platform: Raspberry PI
    LSM9DS1
 
This code is beerware; if you see me (or any other SparkFun employee) at the
local, and you've found our code helpful, please buy us a round!
 
Distributed as-is; no warranty is given.
******************************************************************************/
#ifndef __LSM9DS1_H__
#define __LSM9DS1_H__
 
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <thread>
#include "LSM9DS1_Registers.h"
#include "LSM9DS1_Types.h"
#include <pigpio.h>
 
static const char could_not_open_i2c[] = "Could not open I2C.\n";
 
#define ISR_TIMEOUT 1000
 
#define LSM9DS1_AG_ADDR 0x6B
#define LSM9DS1_M_ADDR  0x1E
#define LSM9DS1_DEFAULT_I2C_BUS 1
#define LSM9DS1_DRDY_GPIO 22
 
struct DeviceSettings
{
    uint8_t agAddress = LSM9DS1_AG_ADDR;
 
    uint8_t mAddress = LSM9DS1_M_ADDR;
 
    unsigned i2c_bus = LSM9DS1_DEFAULT_I2C_BUS;
 
    unsigned drdy_gpio = LSM9DS1_DRDY_GPIO;
 
    bool initPIGPIO = true; // inits pigpio
};
 
struct AccelSettings
{
    enum Scale
        {
            A_SCALE_2G = 2,
            A_SCALE_16G = 16,
            A_SCALE_4G = 4,
            A_SCALE_8G = 8
        };
 
    Scale scale = A_SCALE_16G;
    
    uint8_t enableX = true; 
    uint8_t enableY = true; 
    uint8_t enableZ = true; 
 
    enum Abw
        {
            A_ABW_408 = 0,      
            A_ABW_211 = 1,      
            A_ABW_105 = 2,      
            A_ABW_50  = 3,      
            A_ABW_OFF = -1          
        };
 
    Abw bandwidth = A_ABW_OFF;
    
    uint8_t highResEnable = false;
    uint8_t highResBandwidth = 0;
};
 
struct GyroSettings
{
    enum Scale
        {
            G_SCALE_245DPS = 245,   
            G_SCALE_500DPS = 500,   
            G_SCALE_2000DPS = 2000  
        };
 
    Scale scale = G_SCALE_245DPS;
 
    enum SampleRate
        {
            G_ODR_14_9 = 1, 
            G_ODR_59_5 = 2, 
            G_ODR_119 = 3,  
            G_ODR_238 = 4,  
            G_ODR_476 = 5,  
            G_ODR_952 = 6   
        };
    
        SampleRate sampleRate = G_ODR_14_9;
    
    uint8_t enableX = true; 
    uint8_t enableY = true; 
    uint8_t enableZ = true; 
 
    uint8_t bandwidth = 0;
    uint8_t lowPowerEnable = false;
    uint8_t HPFEnable = false;  
    uint8_t HPFCutoff = 0;
    uint8_t flipX = false;
    uint8_t flipY = false;
    uint8_t flipZ = false;
    uint8_t orientation = 0;
    uint8_t latchInterrupt = true;
};
 
struct MagSettings
{
    uint8_t enabled = true;
 
    enum Scale
        {
            M_SCALE_4GS = 4,    
            M_SCALE_8GS = 8,    
            M_SCALE_12GS = 12,  
            M_SCALE_16GS = 16,  
        };
 
    Scale scale = M_SCALE_16GS;
    
        enum SampleRate
        {
            M_ODR_0625, // 0.625 Hz (0)
            M_ODR_125,  // 1.25 Hz (1)
            M_ODR_250,  // 2.5 Hz (2)
            M_ODR_5,    // 5 Hz (3)
            M_ODR_10,   // 10 Hz (4)
            M_ODR_20,   // 20 Hz (5)
            M_ODR_40,   // 40 Hz (6)
            M_ODR_80    // 80 Hz (7)
        };
 
    SampleRate sampleRate = M_ODR_80;
    
    uint8_t tempCompensationEnable = false;
 
    uint8_t XYPerformance = 3;
    uint8_t ZPerformance = 3;
    uint8_t lowPowerEnable = false;
};
 
struct TemperatureSettings
{
    uint8_t enabled = true;
};
 
enum lsm9ds1_axis {
           X_AXIS,
           Y_AXIS,
           Z_AXIS,
           ALL_AXIS
};
 
struct LSM9DS1Sample {
    float ax = 0;
 
    float ay = 0;
 
    float az = 0;
 
    float gx = 0;
 
    float gy = 0;
 
    float gz = 0;
 
    float mx = 0;
 
    float my = 0;
 
    float mz = 0;
 
    float temperature = 0;
};
 
class LSM9DS1callback {
public:
        virtual void hasSample(LSM9DS1Sample sample) = 0;
};
 
class LSM9DS1
{
public:
    LSM9DS1(DeviceSettings deviceSettings = DeviceSettings());
        
    void begin(GyroSettings gyroSettings = GyroSettings(),
           AccelSettings accelSettings = AccelSettings(),
           MagSettings magSettings = MagSettings(),
           TemperatureSettings temperatureSettings = TemperatureSettings()
           );
    
    void end();
 
    ~LSM9DS1() {
        end();
    }
 
    void setCallback(LSM9DS1callback* cb) {
        lsm9ds1Callback = cb;
    }
 
    bool accelAvailable();
    
    bool gyroAvailable();
    
    bool tempAvailable();
    
        bool magAvailable(lsm9ds1_axis axis = ALL_AXIS);
    
    int16_t readGyro(lsm9ds1_axis axis);
    
    int16_t readAccel(lsm9ds1_axis axis);
    
    int16_t readMag(lsm9ds1_axis axis);
 
    void magOffset(uint8_t axis, int16_t offset);
    
    float calcGyro(int16_t gyro);
    
    float calcAccel(int16_t accel);
    
    float calcMag(int16_t mag);
    
    void setGyroScale(GyroSettings::Scale gScl);
 
    void setAccelScale(AccelSettings::Scale aScl);
    
    void setMagScale(MagSettings::Scale mScl);
    
    uint8_t getGyroIntSrc();
    
    uint8_t getAccelIntSrc();
    
    uint8_t getMagIntSrc();
    
    uint8_t getInactivity();
    
    uint8_t getFIFOSamples();
        
 
private:
    // gRes, aRes, and mRes store the current resolution for each sensor. 
    // Units of these values would be DPS (or g's or Gs's) per ADC tick.
    // This value is calculated as (sensor scale) / (2^15).
    float gRes, aRes, mRes;
    
    // initGyro() -- Sets up the gyroscope to begin reading.
    // This function steps through all five gyroscope control registers.
    // Upon exit, the following parameters will be set:
    //    - CTRL_REG1_G = 0x0F: Normal operation mode, all axes enabled. 
    //        95 Hz ODR, 12.5 Hz cutoff frequency.
    //    - CTRL_REG2_G = 0x00: HPF set to normal mode, cutoff frequency
    //        set to 7.2 Hz (depends on ODR).
    //    - CTRL_REG3_G = 0x88: Interrupt enabled on INT_G (set to push-pull and
    //        active high). Data-ready output enabled on DRDY_G.
    //    - CTRL_REG4_G = 0x00: Continuous update mode. Data LSB stored in lower
    //        address. Scale set to 245 DPS.
    //    - CTRL_REG5_G = 0x00: FIFO disabled. HPF disabled.
    void initGyro();
    
    // readGyro() -- Read the gyroscope output registers.
    // This function will read all six gyroscope output registers.
    // The readings are stored in the class' gx, gy, and gz variables. Read
    // those _after_ calling readGyro().
    void readGyro();
    
    // initAccel() -- Sets up the accelerometer to begin reading.
    // This function steps through all accelerometer related control registers.
    // Upon exit these registers will be set as:
    //    - CTRL_REG0_XM = 0x00: FIFO disabled. HPF bypassed. Normal mode.
    //    - CTRL_REG1_XM = 0x57: 100 Hz data rate. Continuous update.
    //        all axes enabled.
    //    - CTRL_REG2_XM = 0x00:  2g scale. 773 Hz anti-alias filter BW.
    //    - CTRL_REG3_XM = 0x04: Accel data ready signal on INT1_XM pin.
    void initAccel();
    
    // readAccel() -- Read the accelerometer output registers.
    // This function will read all six accelerometer output registers.
    // The readings are stored in the class' ax, ay, and az variables. Read
    // those _after_ calling readAccel().
    void readAccel();
    
    // initMag() -- Sets up the magnetometer to begin reading.
    // This function steps through all magnetometer-related control registers.
    // Upon exit these registers will be set as:
    //    - CTRL_REG4_XM = 0x04: Mag data ready signal on INT2_XM pin.
    //    - CTRL_REG5_XM = 0x14: 100 Hz update rate. Low resolution. Interrupt
    //        requests don't latch. Temperature sensor disabled.
    //    - CTRL_REG6_XM = 0x00:  2 Gs scale.
    //    - CTRL_REG7_XM = 0x00: Continuous conversion mode. Normal HPF mode.
    //    - INT_CTRL_REG_M = 0x09: Interrupt active-high. Enable interrupts.
    void initMag();
    
    // readMag() -- Read the magnetometer output registers.
    // This function will read all six magnetometer output registers.
    // The readings are stored in the class' mx, my, and mz variables. Read
    // those _after_ calling readMag().
    void readMag();
    
    // readTemp() -- Read the temperature output register.
    // This function will read two temperature output registers.
    // The combined readings are stored in the class' temperature variables. Read
    // those _after_ calling readTemp().
    void readTemp();
    
    // gReadByte() -- Reads a byte from a specified gyroscope register.
    // Input:
    //     - subAddress = Register to be read from.
    // Output:
    //     - An 8-bit value read from the requested address.
    uint8_t mReadByte(uint8_t subAddress);
    
    // gReadBytes() -- Reads a number of bytes -- beginning at an address
    // and incrementing from there -- from the gyroscope.
    // Input:
    //     - subAddress = Register to be read from.
    //     - * dest = A pointer to an array of uint8_t's. Values read will be
    //        stored in here on return.
    //    - count = The number of bytes to be read.
    // Output: No value is returned, but the `dest` array will store
    //     the data read upon exit.
    void mReadBytes(uint8_t subAddress, uint8_t * dest, uint8_t count);
    
    // gWriteByte() -- Write a byte to a register in the gyroscope.
    // Input:
    //    - subAddress = Register to be written to.
    //    - data = data to be written to the register.
    void mWriteByte(uint8_t subAddress, uint8_t data);
    
    // xmReadByte() -- Read a byte from a register in the accel/mag sensor
    // Input:
    //    - subAddress = Register to be read from.
    // Output:
    //    - An 8-bit value read from the requested register.
    uint8_t xgReadByte(uint8_t subAddress);
    
    // xmReadBytes() -- Reads a number of bytes -- beginning at an address
    // and incrementing from there -- from the accelerometer/magnetometer.
    // Input:
    //     - subAddress = Register to be read from.
    //     - * dest = A pointer to an array of uint8_t's. Values read will be
    //        stored in here on return.
    //    - count = The number of bytes to be read.
    // Output: No value is returned, but the `dest` array will store
    //     the data read upon exit.
    void xgReadBytes(uint8_t subAddress, uint8_t * dest, uint8_t count);
    
    // xmWriteByte() -- Write a byte to a register in the accel/mag sensor.
    // Input:
    //    - subAddress = Register to be written to.
    //    - data = data to be written to the register.
    void xgWriteByte(uint8_t subAddress, uint8_t data);
    
    // calcgRes() -- Calculate the resolution of the gyroscope.
    // This function will set the value of the gRes variable. gScale must
    // be set prior to calling this function.
    void calcgRes();
    
    // calcmRes() -- Calculate the resolution of the magnetometer.
    // This function will set the value of the mRes variable. mScale must
    // be set prior to calling this function.
    void calcmRes();
    
    // calcaRes() -- Calculate the resolution of the accelerometer.
    // This function will set the value of the aRes variable. aScale must
    // be set prior to calling this function.
    void calcaRes();
    
    // I2CwriteByte() -- Write a byte out of I2C to a register in the device
    // Input:
    //    - address = The 7-bit I2C address of the slave device.
    //    - subAddress = The register to be written to.
    //    - data = Byte to be written to the register.
    void I2CwriteByte(uint8_t address, uint8_t subAddress, uint8_t data);
    
    // I2CreadByte() -- Read a single byte from a register over I2C.
    // Input:
    //    - address = The 7-bit I2C address of the slave device.
    //    - subAddress = The register to be read from.
    // Output:
    //    - The byte read from the requested address.
    uint8_t I2CreadByte(uint8_t address, uint8_t subAddress);
    
    // I2CreadBytes() -- Read a series of bytes, starting at a register via SPI
    // Input:
    //    - address = The 7-bit I2C address of the slave device.
    //    - subAddress = The register to begin reading.
    //     - * dest = Pointer to an array where we'll store the readings.
    //    - count = Number of registers to be read.
    // Output: No value is returned by the function, but the registers read are
    //         all stored in the *dest array given.
    uint8_t I2CreadBytes(uint8_t address, uint8_t subAddress, uint8_t * dest, uint8_t count);
 
    // Callback interface which is registered with the main program.
    LSM9DS1callback* lsm9ds1Callback = nullptr;
 
    // Callback function in this class context which is called by the
    // static low level interrupt handler gpioISR.
    void dataReady();
 
    // Static low level callback handler registered with from pigpio
    // The userdata contains a pointer to this class instance.
    static void gpioISR(int gpio, int level, uint32_t tick, void* userdata)
    {
        if (level) {
            ((LSM9DS1*)userdata)->dataReady();
        }
    }
    
    // setGyroODR() -- Set the output data rate and bandwidth of the gyroscope
    // Input:
    //    - gRate = The desired output rate and cutoff frequency of the gyro.
    void setGyroODR(GyroSettings::SampleRate gRate);
    
    // setAccelODR() -- Set the output data rate of the accelerometer
    // Input:
    //    - aRate = The desired output rate of the accel.
    void setAccelODR(uint8_t aRate);     
    
    // setMagODR() -- Set the output data rate of the magnetometer
    // Input:
    //    - mRate = The desired output rate of the mag.
    void setMagODR(MagSettings::SampleRate mRate);
    
    // configInactivity() -- Configure inactivity interrupt parameters
    // Input:
    //    - duration = Inactivity duration - actual value depends on gyro ODR
    //    - threshold = Activity Threshold
    //    - sleepOn = Gyroscope operating mode during inactivity.
    //      true: gyroscope in sleep mode
    //      false: gyroscope in power-down
    void configInactivity(uint8_t duration, uint8_t threshold, bool sleepOn);
    
    // configAccelInt() -- Configure Accelerometer Interrupt Generator
    // Input:
    //    - generator = Interrupt axis/high-low events
    //      Any OR'd combination of ZHIE_XL, ZLIE_XL, YHIE_XL, YLIE_XL, XHIE_XL, XLIE_XL
    //    - andInterrupts = AND/OR combination of interrupt events
    //      true: AND combination
    //      false: OR combination
    void configAccelInt(uint8_t generator, bool andInterrupts = false);
    
    // configAccelThs() -- Configure the threshold of an accelereomter axis
    // Input:
    //    - threshold = Interrupt threshold. Possible values: 0-255.
    //      Multiply by 128 to get the actual raw accel value.
    //    - axis = Axis to be configured. Either X_AXIS, Y_AXIS, or Z_AXIS
    //    - duration = Duration value must be above or below threshold to trigger interrupt
    //    - wait = Wait function on duration counter
    //      true: Wait for duration samples before exiting interrupt
    //      false: Wait function off
    void configAccelThs(uint8_t threshold, lsm9ds1_axis axis, uint8_t duration = 0, bool wait = 0);
    
    // configGyroInt() -- Configure Gyroscope Interrupt Generator
    // Input:
    //    - generator = Interrupt axis/high-low events
    //      Any OR'd combination of ZHIE_G, ZLIE_G, YHIE_G, YLIE_G, XHIE_G, XLIE_G
    //    - aoi = AND/OR combination of interrupt events
    //      true: AND combination
    //      false: OR combination
    //    - latch: latch gyroscope interrupt request.
    void configGyroInt(uint8_t generator, bool aoi, bool latch);
    
    // configGyroThs() -- Configure the threshold of a gyroscope axis
    // Input:
    //    - threshold = Interrupt threshold. Possible values: 0-0x7FF.
    //      Value is equivalent to raw gyroscope value.
    //    - axis = Axis to be configured. Either X_AXIS, Y_AXIS, or Z_AXIS
    //    - duration = Duration value must be above or below threshold to trigger interrupt
    //    - wait = Wait function on duration counter
    //      true: Wait for duration samples before exiting interrupt
    //      false: Wait function off
    void configGyroThs(int16_t threshold, lsm9ds1_axis axis, uint8_t duration, bool wait);
    
    // configInt() -- Configure INT1 or INT2 (Gyro and Accel Interrupts only)
    // Input:
    //    - interrupt = Select INT1 or INT2
    //      Possible values: XG_INT1 or XG_INT2
    //    - generator = Or'd combination of interrupt generators.
    //      Possible values: INT_DRDY_XL, INT_DRDY_G, INT1_BOOT (INT1 only), INT2_DRDY_TEMP (INT2 only)
    //      INT_FTH, INT_OVR, INT_FSS5, INT_IG_XL (INT1 only), INT1_IG_G (INT1 only), INT2_INACT (INT2 only)
    //    - activeLow = Interrupt active configuration
    //      Can be either INT_ACTIVE_HIGH or INT_ACTIVE_LOW
    //    - pushPull =  Push-pull or open drain interrupt configuration
    //      Can be either INT_PUSH_PULL or INT_OPEN_DRAIN
    void configInt(interrupt_select interupt, uint8_t generator,
               h_lactive activeLow = INT_ACTIVE_LOW, pp_od pushPull = INT_PUSH_PULL);
                   
    // configMagInt() -- Configure Magnetometer Interrupt Generator
    // Input:
    //    - generator = Interrupt axis/high-low events
    //      Any OR'd combination of ZIEN, YIEN, XIEN
    //    - activeLow = Interrupt active configuration
    //      Can be either INT_ACTIVE_HIGH or INT_ACTIVE_LOW
    //    - latch: latch gyroscope interrupt request.
    void configMagInt(uint8_t generator, h_lactive activeLow, bool latch = true);
    
    // configMagThs() -- Configure the threshold of a gyroscope axis
    // Input:
    //    - threshold = Interrupt threshold. Possible values: 0-0x7FF.
    //      Value is equivalent to raw magnetometer value.
    void configMagThs(uint16_t threshold);
    
    // sleepGyro() -- Sleep or wake the gyroscope
    // Input:
    //    - enable: True = sleep gyro. False = wake gyro.
    void sleepGyro(bool enable = true);
    
    // enableFIFO() - Enable or disable the FIFO
    // Input:
    //    - enable: true = enable, false = disable.
    void enableFIFO(bool enable = true);
    
    // setFIFO() - Configure FIFO mode and Threshold
    // Input:
    //    - fifoMode: Set FIFO mode to off, FIFO (stop when full), continuous, bypass
    //      Possible inputs: FIFO_OFF, FIFO_THS, FIFO_CONT_TRIGGER, FIFO_OFF_TRIGGER, FIFO_CONT
    //    - fifoThs: FIFO threshold level setting
    //      Any value from 0-0x1F is acceptable.
    void setFIFO(fifoMode_type fifoMode, uint8_t fifoThs);
    
    DeviceSettings device;
    MagSettings mag;
    GyroSettings gyro;
    AccelSettings accel;
    TemperatureSettings temp;
 
    // We'll store the gyro, accel, and magnetometer readings in a series of
    // public class variables. Each sensor gets three variables -- one for each
    // axis. Call readGyro(), readAccel(), and readMag() first, before using
    // these variables!
    // These values are the RAW signed 16-bit readings from the sensors.
    int16_t gx = 0, gy = 0, gz = 0; // x, y, and z axis readings of the gyroscope
    int16_t ax = 0, ay = 0, az = 0; // x, y, and z axis readings of the accelerometer
    int16_t mx = 0, my = 0, mz = 0; // x, y, and z axis readings of the magnetometer
    int16_t temperature = 0; // Chip temperature
 
};
 
#endif // SFE_LSM9DS1_H //