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	__LSM9DS1_IMU_SENSOR_H__
#define	ACT_THS   0x04
#define	ACT_DUR   0x05
#define	INT_GEN_CFG_XL   0x06
#define	INT_GEN_THS_X_XL   0x07
#define	INT_GEN_THS_Y_XL   0x08
#define	INT_GEN_THS_Z_XL   0x09
#define	INT_GEN_DUR_XL   0x0A
#define	REFERENCE_G   0x0B
#define	INT1_CTRL   0x0C
#define	INT2_CTRL   0x0D
#define	WHO_AM_I_XG   0x0F
#define	CTRL_REG1_G   0x10
#define	CTRL_REG2_G   0x11
#define	CTRL_REG3_G   0x12
#define	ORIENT_CFG_G   0x13
#define	INT_GEN_SRC_G   0x14
#define	OUT_TEMP_L   0x15
#define	OUT_TEMP_H   0x16
#define	STATUS_REG_0   0x17
#define	OUT_X_L_G   0x18
#define	OUT_X_H_G   0x19
#define	OUT_Y_L_G   0x1A
#define	OUT_Y_H_G   0x1B
#define	OUT_Z_L_G   0x1C
#define	OUT_Z_H_G   0x1D
#define	CTRL_REG4   0x1E
#define	CTRL_REG5_XL   0x1F
#define	CTRL_REG6_XL   0x20
#define	CTRL_REG7_XL   0x21
#define	CTRL_REG8   0x22
#define	CTRL_REG9   0x23
#define	CTRL_REG10   0x24
#define	INT_GEN_SRC_XL   0x26
#define	STATUS_REG_1   0x27
#define	OUT_X_L_XL   0x28
#define	OUT_X_H_XL   0x29
#define	OUT_Y_L_XL   0x2A
#define	OUT_Y_H_XL   0x2B
#define	OUT_Z_L_XL   0x2C
#define	OUT_Z_H_XL   0x2D
#define	FIFO_CTRL   0x2E
#define	FIFO_SRC   0x2F
#define	INT_GEN_CFG_G   0x30
#define	INT_GEN_THS_XH_G   0x31
#define	INT_GEN_THS_XL_G   0x32
#define	INT_GEN_THS_YH_G   0x33
#define	INT_GEN_THS_YL_G   0x34
#define	INT_GEN_THS_ZH_G   0x35
#define	INT_GEN_THS_ZL_G   0x36
#define	INT_GEN_DUR_G   0x37
#define	OFFSET_X_REG_L_M   0x05
#define	OFFSET_X_REG_H_M   0x06
#define	OFFSET_Y_REG_L_M   0x07
#define	OFFSET_Y_REG_H_M   0x08
#define	OFFSET_Z_REG_L_M   0x09
#define	OFFSET_Z_REG_H_M   0x0A
#define	WHO_AM_I_M   0x0F
#define	CTRL_REG1_M   0x20
#define	CTRL_REG2_M   0x21
#define	CTRL_REG3_M   0x22
#define	CTRL_REG4_M   0x23
#define	CTRL_REG5_M   0x24
#define	STATUS_REG_M   0x27
#define	OUT_X_L_M   0x28
#define	OUT_X_H_M   0x29
#define	OUT_Y_L_M   0x2A
#define	OUT_Y_H_M   0x2B
#define	OUT_Z_L_M   0x2C
#define	OUT_Z_H_M   0x2D
#define	INT_CFG_M   0x30
#define	INT_SRC_M   0x30
#define	INT_THS_L_M   0x32
#define	INT_THS_H_M   0x33
#define	WHO_AM_I_AG_RSP   0x68
#define	WHO_AM_I_M_RSP   0x3D
#define	FIFO_OFF   0
#define	FIFO_THS   1
#define	FIFO_CONT_TRIGGER   3
#define	FIFO_OFF_TRIGGER   4
#define	FIFO_CONT   5
#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 overPos, char underNeg, char lowHigh)
	Configures the Magnetometer interrupt output to the INT_M pin. More...
void	imu_SPIwriteByte (unsigned char csPin, unsigned char subAddress, unsigned char data)
	Writes a byte to the specified LSM9DS1 register.
void	imu_SPIreadBytes (unsigned char csPin, unsigned char subAddress, unsigned char *dest, unsigned char count)
	Reads a specified number of bytes from the specified LSM9DS1 register.

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

Copyright

Copyright (C) Parallax, Inc. 2016. All Rights MIT Licensed.

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.

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

*axBias	variable to store Accelreometer x-axis bias into.
*ayBias	variable to store Accelreometer y-axis bias into.
*azBias	variable 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

*gxBias	variable to store Gyroscope x-axis bias into.
*gyBias	variable to store Gyroscope y-axis bias into.
*gzBias	variable 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

*mxBias	variable to store Magnetometer x-axis bias into.
*myBias	variable to store Magnetometer y-axis bias into.
*mzBias	variable 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

pinSCL	I/O Pin connected to the module's SCL pin.
pinSDIO	I/O Pin connected to the module's SDIO pin.
pinAG	I/O Pin connected to the module's CS_AG pin.
pinM	I/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

*ax	Variable to store Raw x-axis Accelerometer reading into.
*ay	Variable to store Raw y-axis Accelerometer reading into.
*az	Variable 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

*ax	Variable to store scaled x-axis Accelerometer reading into.
*ay	Variable to store scaled y-axis Accelerometer reading into.
*az	Variable 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

*gx	Variable to store Raw x-axis Gyroscope reading into.
*gy	Variable to store Raw y-axis Gyroscope reading into.
*gz	Variable 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

*gx	Variable to store scaled x-axis Gyroscope reading into.
*gy	Variable to store scaled y-axis Gyroscope reading into.
*gz	Variable 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

*mx	Variable to store Raw x-axis Magnetometer reading into.
*my	Variable to store Raw y-axis Magnetometer reading into.
*mz	Variable 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

*mx	Variable to store scaled x-axis Magnetometer reading into.
*my	Variable to store scaled y-axis Magnetometer reading into.
*mz	Variable 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

*temperature

Variable 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

*temperature	Variable to store scaled Thermometer reading into.
tempUnit	Value 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

axBias	Value to set Accelerometer x-axis bias to.
ayBias	Value to set Accelerometer y-axis bias to.
azBias	Value 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

axis	Sets 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).
threshold	Sets 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.
duration	Sets 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.
overUnder	Sets whether the interrupt is triggered when the acceleration is a greater (1) or lesser (0) magnitude than the threshold.
andOr	If 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

aScl	Value 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

gxBias	Value to set Gyroscope x-axis bias to.
gyBias	Value to set Gyroscope y-axis bias to.
gzBias	Value 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

axis	Sets 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).
threshold	Sets 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.
duration	Sets 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.
overUnder	Sets whether the interrupt is triggered when the rotational speed is above (1) or below (0) than the threshold.
andOr	If 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

gScl	Value 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

mxBias	Value to set Magnetometer x-axis bias to.
myBias	Value to set Magnetometer y-axis bias to.
mzBias	Value 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

axis	Sets 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).
threshold	Sets the threshold (as a floating point value in Degrees Per Second) 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.
overPos	If set (1), the interrupt triggers when the magnetic field strength is larger than the threshold in the positive direction.
underNeg	If set (1), the interrupt triggers when the magnetic field strength is larger (more negative) than the threshold in the negative direction.
lowHigh	When 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

mScl	Value 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.