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 Accelerometer'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

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 samples of accelerometer and gyro data, average them, scale them to g's and deg/s, respectively, and then passes the biases to variables in the library for subtraction from all subsequent data. This 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 function accumulates samples from the magnetometer, averages them, and then passes the biases back to the LSM9DS1 for subtraction from all subsequent data. This 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 Accelerometer's calibration biases.

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

Note

An Accel/Gyro Calibration must be performed before calling this function. This function retrieves the biases from RAM (so they are lost if the Propeller is powered off).

Parameters

*axBias	variable to store Accelerometer x-axis bias into.
*ayBias	variable to store Accelerometer y-axis bias into.
*azBias	variable to store Accelerometer 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 performed before calling this function. This function retrieves 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 Magnetometer Calibration must be performed before calling this function. This function retrieves 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 Gyroscope 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 if 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 in 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 readings 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 to.

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 threshold 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 approximately 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 axes 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 to.

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 degrees per second) for triggering an interrupt. The Gyroscope interrupt thresholds can be positive or negative, so it triggers on rotations occuring in one direction. The threshold 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 approximately 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) the threshold.
andOr	If interrupts for multiple axes have been set, this sets whether the interrupts for the individual axes 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 Magnetometer's 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 to.

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 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.
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 4, 8, 12, or 16 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.