lsm9ds1 library  0.5
Library for the Parallax LSM9DS1 IMU module
Macros | Functions
lsm9ds1.h File Reference

This Propeller C library was created for the Parallax 9-axis IMU Sensor, based on the STMicroelectronics LSM9DS1 inertial motion sensor chip. More...

Go to the source code of this file.

Macros

#define X_AXIS   0
 
#define Y_AXIS   1
 
#define Z_AXIS   2
 
#define ALL_AXIS   3
 
#define CELSIUS   0
 
#define FAHRENHEIT   1
 
#define KELVIN   2
 

Functions

int imu_init (int pinSCL, int pinSDIO, int pinAG, int pinM)
 Initializes the LSM9DS1 IMU module. More...
 
void imu_calibrateAG ()
 Calibrates the Accelerometer and Gyroscope on the LSM9DS1 IMU module. More...
 
void imu_calibrateMag ()
 Calibrates the Magnetometer on the LSM9DS1 IMU module. More...
 
void imu_getMagCalibration (int *mxBias, int *myBias, int *mzBias)
 Retrieves the Magnetometer's calibration biases. More...
 
void imu_getAccelCalibration (int *axBias, int *ayBias, int *azBias)
 Retrieves the Accelreometer's calibration biases. More...
 
void imu_getGyroCalibration (int *gxBias, int *gyBias, int *gzBias)
 Retrieves the Gyroscope's calibration biases. More...
 
void imu_setMagCalibration (int mxBias, int myBias, int mzBias)
 Sets the Magnetometer's calibration biases. More...
 
void imu_setAccelCalibration (int axBias, int ayBias, int azBias)
 Sets the Accelerometer's calibration biases. More...
 
void imu_setGyroCalibration (int gxBias, int gyBias, int gzBias)
 Sets the Gyroscope's calibration biases. More...
 
unsigned char imu_accelAvailable ()
 Polls the Accelerometer status register to check if new data is available. More...
 
unsigned char imu_gyroAvailable ()
 Polls the Gyroscope status register to check if new data is available. More...
 
unsigned char imu_tempAvailable ()
 Polls the Thermometer status register to check if new data is available. More...
 
unsigned char imu_magAvailable ()
 Polls the Magnetometer status register to check if new data is available. More...
 
void imu_readGyro (int *gx, int *gy, int *gz)
 Reads the Gyroscope output registers. More...
 
void imu_readAccel (int *ax, int *ay, int *az)
 Reads the Accelerometer output registers. More...
 
void imu_readMag (int *mx, int *my, int *mz)
 Reads the Magnetometer output registers. More...
 
void imu_readTemp (int *temperature)
 Reads the Temperature output registers. More...
 
void imu_readGyroCalculated (float *gx, float *gy, float *gz)
 Reads the Gyroscope output registers and scales the outputs to degrees of rotation per second (DPS). More...
 
void imu_readAccelCalculated (float *ax, float *ay, float *az)
 Reads the Accelerometer output registers and scales the outputs to g's (1 g = 9.8 m/s/s). More...
 
void imu_readMagCalculated (float *mx, float *my, float *mz)
 Reads the Magnetometer output registers and scales the outputs to gauss'. More...
 
void imu_readTempCalculated (float *temperature, char tempUnit)
 Reads the Thermometer output registers and scales the outputs to degrees Celsius, Fahrenheit, or Kelvin. More...
 
void imu_setGyroScale (unsigned int gScl)
 Sets the full-scale range of the Gyroscope. More...
 
void imu_setAccelScale (unsigned char aScl)
 Sets the full-scale range of the Accelerometer. More...
 
void imu_setMagScale (unsigned char mScl)
 Sets the full-scale range of the Magnetometer. More...
 
int imu_getGyroScale ()
 Retrieves the full-scale range of the Gyroscope. More...
 
int imu_getAccelScale ()
 Retrieves the full-scale range of the Accelerometer. More...
 
int imu_getMagScale ()
 Retrieves the full-scale range of the Magnetometer. More...
 
void imu_clearAccelInterrupt ()
 Clears out any interrupts set up on the Accelerometer and resets all Accelerometer interrupt registers to their default values. More...
 
void imu_clearGyroInterrupt ()
 Clears out any interrupts set up on the Gyroscope and resets all Gyroscope interrupt registers to their default values. More...
 
void imu_clearMagInterrupt ()
 Clears out any interrupts set up on the Magnetometer and resets all Magnetometer interrupt registers to their default values. More...
 
void imu_setAccelInterrupt (char axis, float threshold, char duration, char overUnder, char andOr)
 Configures the Accelerometer interrupt output to the INT_A/G pin. More...
 
void imu_setGyroInterrupt (char axis, float threshold, char duration, char overUnder, char andOr)
 Configures the Gyroscope interrupt output to the INT_A/G pin. More...
 
void imu_setMagInterrupt (char axis, float threshold, char lowHigh)
 Configures the Magnetometer interrupt output to the INT_M pin. More...
 

Detailed Description

This Propeller C library was created for the Parallax 9-axis IMU Sensor, based on the STMicroelectronics LSM9DS1 inertial motion sensor chip.

Author
Matthew Matz
Version
0.5

Function Documentation

unsigned char imu_accelAvailable ( )

Polls the Accelerometer status register to check if new data is available.

Returns
1 if new data is available, 0 if no new data is available.
void imu_calibrateAG ( )

Calibrates the Accelerometer and Gyroscope on the LSM9DS1 IMU module.

This is a function that uses the FIFO to accumulate sample of accelerometer and gyro data, averages them, scales them to gs and deg/s, respectively, and then passes the biases to variables in the library for subtraction from all subsequent data. Results in a more accurate measurement in general and can remove errors due to imprecise or varying initial placement.

Note
Accel/Gyro Calibration values are NOT stored in the LSM9DS1. They can be retireved and set using other functions in this library.
void imu_calibrateMag ( )

Calibrates the Magnetometer on the LSM9DS1 IMU module.

This is a function accumulates samples from the magnetometer, averages them, and then passes the biases back to the LSM9DS1 for subtraction from all subsequent data. Results in a more accurate measurement in general and can remove errors due to imprecise or varying initial placement. The calibration function uses the accelerometer to verify that each of the 3 axes has been pointed straight up and straight down slowly enough to get good magnetometer readings in each dimension.

Note
Mag Calibration values ARE stored in the LSM9DS1 and variables that can be retireved and set using other functions in this library.
void imu_clearAccelInterrupt ( )

Clears out any interrupts set up on the Accelerometer and resets all Accelerometer interrupt registers to their default values.

Note
Interrupt settings are non-volatile and will persist after a power-cycle or brown out.
void imu_clearGyroInterrupt ( )

Clears out any interrupts set up on the Gyroscope and resets all Gyroscope interrupt registers to their default values.

Note
Interrupt settings are non-volatile and will persist after a power-cycle or brown out.
void imu_clearMagInterrupt ( )

Clears out any interrupts set up on the Magnetometer and resets all Magnetometer interrupt registers to their default values.

Note
Interrupt settings are non-volatile and will persist after a power-cycle or brown out.
void imu_getAccelCalibration ( int *  axBias,
int *  ayBias,
int *  azBias 
)

Retrieves the Accelreometer's calibration biases.

This function retrieves the calibration biases for each Accelreometer axis. Biases can be retrieved after a Accelreometer calibration has been performed.

Note
An Accel/Gyro Calibration must be preformed before calling this function. This function retireves the biases from RAM (so they are lost if the Propeller is powered off).
Parameters
*axBiasvariable to store Accelreometer x-axis bias into.
*ayBiasvariable to store Accelreometer y-axis bias into.
*azBiasvariable to store Accelreometer z-axis bias into.
int imu_getAccelScale ( )

Retrieves the full-scale range of the Accelerometer.

This function can be called to get the scale of the Accelerometer.

Returns
Value of the Accelerometer scale. 2, 4, 8, or 16 g's.
void imu_getGyroCalibration ( int *  gxBias,
int *  gyBias,
int *  gzBias 
)

Retrieves the Gyroscope's calibration biases.

This function retrieves the calibration biases for each Gyroscope axis. Biases can be retrieved after a Gyroscope calibration has been performed.

Note
An Accel/Gyro Calibration must be preformed before calling this function. This function retireves the biases from RAM (so they are lost if the Propeller is powered off).
Parameters
*gxBiasvariable to store Gyroscope x-axis bias into.
*gyBiasvariable to store Gyroscope y-axis bias into.
*gzBiasvariable to store Gyroscope z-axis bias into.
int imu_getGyroScale ( )

Retrieves the full-scale range of the Gyroscope.

This function can be called to get the scale of the Gyroscope.

Returns
Value of the Gyroscope scale. 245, 500, or 2000 DPS.
void imu_getMagCalibration ( int *  mxBias,
int *  myBias,
int *  mzBias 
)

Retrieves the Magnetometer's calibration biases.

This function retrieves the calibration biases for each Magnetometer axis. Biases can be retrieved after a Magnetometer calibration has been performed.

Note
A Magmetometer Calibration must be preformed before calling this function. This function retireves the biases from RAM (so they are lost if the Propeller is powered off).
Parameters
*mxBiasvariable to store Magnetometer x-axis bias into.
*myBiasvariable to store Magnetometer y-axis bias into.
*mzBiasvariable to store Magnetometer z-axis bias into.
int imu_getMagScale ( )

Retrieves the full-scale range of the Magnetometer.

This function can be called to get the scale of the Magnetometer.

Returns
Value of the Magnetometer scale. 4, 8, 12, or 16 gauss.
unsigned char imu_gyroAvailable ( )

Polls the Gyroscope status register to check if new data is available.

Returns
1 if new data is available, 0 if no new data is available.
int imu_init ( int  pinSCL,
int  pinSDIO,
int  pinAG,
int  pinM 
)

Initializes the LSM9DS1 IMU module.

This function initializes the LSM9DS1 IMU module. It sets the chip to 3-wire SPI mode and starts up the accelerometer, gyroscope, and magnetometer.

Note
Defaults the Accelerometer scale to +/-8g, the Gryoscope scale to +/- 500 DPS, and the Magnetometer scale to +/-12 gauss.
Parameters
pinSCLI/O Pin connected to the module's SCL pin.
pinSDIOI/O Pin connected to the module's SDIO pin.
pinAGI/O Pin connected to the module's CS_AG pin.
pinMI/O Pin connected to the module's CS_M pin.
Returns
0x683D if both the Accel/Gyro and Mag start up successfully, or 0 of neither sensor starts.
unsigned char imu_magAvailable ( )

Polls the Magnetometer status register to check if new data is available.

Returns
1 if new data is available, 0 if no new data is available.
void imu_readAccel ( int *  ax,
int *  ay,
int *  az 
)

Reads the Accelerometer output registers.

This function will read all six Accelerometer output registers. The readings are stored in the specified variables.

Parameters
*axVariable to store Raw x-axis Accelerometer reading into.
*ayVariable to store Raw y-axis Accelerometer reading into.
*azVariable to store Raw z-axis Accelerometer reading into.
void imu_readAccelCalculated ( float *  ax,
float *  ay,
float *  az 
)

Reads the Accelerometer output registers and scales the outputs to g's (1 g = 9.8 m/s/s).

This function will read all six Accelerometer output registers. The scaled readings in g's are stored in the specified variables.

Parameters
*axVariable to store scaled x-axis Accelerometer reading into.
*ayVariable to store scaled y-axis Accelerometer reading into.
*azVariable to store scaled z-axis Accelerometer reading into.
void imu_readGyro ( int *  gx,
int *  gy,
int *  gz 
)

Reads the Gyroscope output registers.

This function will read all six Gyroscope output registers. The readings are stored in the specified variables.

Parameters
*gxVariable to store Raw x-axis Gyroscope reading into.
*gyVariable to store Raw y-axis Gyroscope reading into.
*gzVariable to store Raw z-axis Gyroscope reading into.
void imu_readGyroCalculated ( float *  gx,
float *  gy,
float *  gz 
)

Reads the Gyroscope output registers and scales the outputs to degrees of rotation per second (DPS).

This function will read all six Gyroscope output registers. The scaled readings ins DPS are stored in the specified variables.

Parameters
*gxVariable to store scaled x-axis Gyroscope reading into.
*gyVariable to store scaled y-axis Gyroscope reading into.
*gzVariable to store scaled z-axis Gyroscope reading into.
void imu_readMag ( int *  mx,
int *  my,
int *  mz 
)

Reads the Magnetometer output registers.

This function will read all six Magnetometer output registers. The readings are stored in the specified variables.

Parameters
*mxVariable to store Raw x-axis Magnetometer reading into.
*myVariable to store Raw y-axis Magnetometer reading into.
*mzVariable to store Raw z-axis Magnetometer reading into.
void imu_readMagCalculated ( float *  mx,
float *  my,
float *  mz 
)

Reads the Magnetometer output registers and scales the outputs to gauss'.

This function will read all six Magnetometer output registers. The scaled readings in gauss' are stored in the specified variables.

Parameters
*mxVariable to store scaled x-axis Magnetometer reading into.
*myVariable to store scaled y-axis Magnetometer reading into.
*mzVariable to store scaled z-axis Magnetometer reading into.
void imu_readTemp ( int *  temperature)

Reads the Temperature output registers.

This function will read all six Temperature output registers. The readings are stored in the specified variables.

Parameters
*temperatureVariable to store Raw Temperature reading into.
void imu_readTempCalculated ( float *  temperature,
char  tempUnit 
)

Reads the Thermometer output registers and scales the outputs to degrees Celsius, Fahrenheit, or Kelvin.

This function reads the Thermometer output registers. The scaled reading in are stored in the specified variables.

Parameters
*temperatureVariable to store scaled Thermometer reading into.
tempUnitValue to set the unit to scale the output to. Acceptable values are CELSIUS (0), FAHRENHEIT (1), KELVIN (2).
void imu_setAccelCalibration ( int  axBias,
int  ayBias,
int  azBias 
)

Sets the Accelerometer's calibration biases.

This function sets the calibration biases for each Accelerometer axis. Biases can be retrieved after the Accelerometer calibration has been set.

Note
Accelerometer Calibration values ARE NOT stored in the LSM9DS1 and will not persist after a power cycle.
Parameters
axBiasValue to set Accelerometer x-axis bias to.
ayBiasValue to set Accelerometer y-axis bias to.
azBiasValue to set Accelerometer z-axis bias tp.
void imu_setAccelInterrupt ( char  axis,
float  threshold,
char  duration,
char  overUnder,
char  andOr 
)

Configures the Accelerometer interrupt output to the INT_A/G pin.

Note
Interrupt settings are non-volatile and will persist after a power-cycle or brown out.
Parameters
axisSets which axis (or all axes) to be configured to send out an interrupt. Values can be X_AXIS (0), Y_AXIS (1), Z_AXIS (2), or ALL_AXIS (3).
thresholdSets the threshold magnitude (as a floating point value in g's) for triggering an interrupt. The Accelerometer interrupt threshold is an absolute value, so it triggers on accelerations crossing the threshold in both the positive and negative directions. The thershold can be up to 50% of the full scale value.
durationSets how long the INT_A/G pin is held high once an interrupt is triggered. The duration is measured in samples - since samples are taken approximetly every 10ms, a duration of 100 is roughly 1 second. The duration can be any integer value from 0 to 255.
overUnderSets whether the interrupt is triggered when the acceleration is a greater (1) or lesser (0) magnitude than the threshold.
andOrIf interrupts for multiple axis have been set, this sets whether the interrupts for the individual axis must all be triggered (AND condition - 1), or if only one of them has to be triggered (OR condition - 0).

void imu_setAccelScale ( unsigned char  aScl)

Sets the full-scale range of the Accelerometer.

This function can be called to set the scale of the Accelerometer to 2, 4, 8, or 16 g's.

Parameters
aSclValue of the desired Accelerometer scale. Must be 2, 4, 8, or 16.
void imu_setGyroCalibration ( int  gxBias,
int  gyBias,
int  gzBias 
)

Sets the Gyroscope's calibration biases.

This function sets the calibration biases for each Gyroscope axis. Biases can be retrieved after the Gyroscope calibration has been set.

Note
Gyroscope Calibration values ARE NOT stored in the LSM9DS1 and will not persist after a power cycle.
Parameters
gxBiasValue to set Gyroscope x-axis bias to.
gyBiasValue to set Gyroscope y-axis bias to.
gzBiasValue to set Gyroscope z-axis bias tp.
void imu_setGyroInterrupt ( char  axis,
float  threshold,
char  duration,
char  overUnder,
char  andOr 
)

Configures the Gyroscope interrupt output to the INT_A/G pin.

Note
Interrupt settings are non-volatile and will persist after a power-cycle or brown out.
Parameters
axisSets which axis (or all axes) to be configured to send out an interrupt. Values can be X_AXIS (0), Y_AXIS (1), Z_AXIS (2), or ALL_AXIS (3).
thresholdSets the threshold (as a floating point value in gauss) for triggering an interrupt. The Gyroscope interrupt thresholds can be positive or negative, so it triggers on rotations occuring in one direction. The thershold can be up to 50% of the full scale value.
durationSets how long the INT_A/G pin is held high once an interrupt is triggered. The duration is measured in samples - since samples are taken approximetly every 10ms, a duration of 100 is roughly 1 second. The duration can be any integer value from 0 to 255.
overUnderSets whether the interrupt is triggered when the rotational speed is above (1) or below (0) than the threshold.
andOrIf interrupts for multiple axis have been set, this sets whether the interrupts for the individual axis must all be triggered (AND condition - 1), or if only one of them has to be triggered (OR condition - 0).

void imu_setGyroScale ( unsigned int  gScl)

Sets the full-scale range of the Gyroscope.

This function can be called to set the scale of the Gyroscope to 245, 500, or 2000 degrees per second.

Parameters
gSclValue of the desired Gyroscope scale. Must be 245, 500, or 2000.
void imu_setMagCalibration ( int  mxBias,
int  myBias,
int  mzBias 
)

Sets the Magnetometer's calibration biases.

This function sets the calibration biases for each Magnetometer axis. Biases can be retrieved after the Magnetometers calibration has been set.

Note
Mag Calibration values ARE stored in the LSM9DS1 and will persist after a power cycle.
Parameters
mxBiasValue to set Magnetometer x-axis bias to.
myBiasValue to set Magnetometer y-axis bias to.
mzBiasValue to set Magnetometer z-axis bias tp.
void imu_setMagInterrupt ( char  axis,
float  threshold,
char  overPos,
char  underNeg,
char  lowHigh 
)

Configures the Magnetometer interrupt output to the INT_M pin.

Note
Interrupt settings are non-volatile and will persist after a power-cycle or brown out.
Parameters
axisSets which axis (or all axes) to be configured to send out an interrupt. Values can be X_AXIS (0), Y_AXIS (1), Z_AXIS (2), or ALL_AXIS (3).
thresholdSets the threshold (as a floating point value in Gauss) for triggering an interrupt. The Magnetometer interrupt threshold is an absolute value, so it sets triggers for magnetic field strengths crossing the threshold in both positive and negative directions. The threshold can be up to 50% of the full scale value.
lowHighWhen the interrupt is triggered, sets the INT_M pin high (1) or low (0).

void imu_setMagScale ( unsigned char  mScl)

Sets the full-scale range of the Magnetometer.

This function can be called to set the scale of the Magnetometer to 2, 4, 8, or 12 gauss.

Parameters
mSclValue of the desired Magnetometer scale. Must be 4, 8, 12 or 16.
unsigned char imu_tempAvailable ( )

Polls the Thermometer status register to check if new data is available.

Returns
1 if new data is available, 0 if no new data is available.