Arduino library for Pololu LSM303 boards

Version: 1.4.4
Release Date: 2013-07-22
www.pololu.com

Summary

This is a library for the Arduino that interfaces with LSM303DLH, LSM303DLM, and LSM303DLHC compasses and accelerometers on Pololu boards. It makes it simple to read the raw accelerometer and magnetometer data from these boards:

• LSM303DLHC 3D compass and accelerometer carrier
• LSM303DLM 3D compass and accelerometer carrier
• MinIMU-9 v2 (L3GD20 and LSM303DLHC carrier)
• AltIMU-10 (L3GD20, LSM303DLHC, and LSM331AP carrier)
• LSM303DLH 3D compass and accelerometer carrier (discontinued)
• MinIMU-9 (L3G4200D and LSM303DLM carrier) (discontinued)
• MinIMU-9 (L3G4200D and LSM303DLH carrier) (discontinued)

The library also includes a function for computing the tilt-compensated heading for those looking to use the LSM303 as a tilt-compensated compass.

Getting Started

Software

Download the archive from GitHub, decompress it, and move the “LSM303” folder into the “libraries” subdirectory inside your Arduino sketchbook directory. You can view your sketchbook location by selecting File→Preferences in the Arduino environment; if there is not already a “libraries” folder in that location, you should create it yourself. After installing the library, restart the Arduino environment so it can find the LSM303 library and its examples.

Hardware

Make the following connections with wires between the Arduino and the LSM303 board:

Arduino Uno/Duemilanove     LSM303 board
                    5V  ->  VIN
                   GND  ->  GND
          Analog Pin 5  ->  SCL
          Analog Pin 4  ->  SDA

Arduino Mega                LSM303 board
                    5V  ->  VIN
                   GND  ->  GND
        Digital Pin 21  ->  SCL
        Digital Pin 20  ->  SDA

Example Programs

Open an example code sketch by selecting File→Examples→LSM303→example_name

Serial

This program continuously reads the accelerometer and magnetometer, communicating the readings over the serial interface. You can display the readings with the Arduino Serial Monitor.

Example output:

A X: -151 Y: 848 Z: -509 M X: 281 Y: -442 Z: 87
A X: -147 Y: 847 Z: -509 M X: 266 Y: -446 Z: 78
A X: -147 Y: 849 Z: -508 M X: 280 Y: -450 Z: 81

Calibrate

This program is similar to the Serial example, but instead of printing the most recent readings, it prints a running minimum and maximum of the readings from each magnetometer axis. These values can be used to calibrate the heading() functions and the Heading example after moving the LSM303 through every possible orientation.

Heading

This program uses readings from the accelerometer and magnetometer to calculate a tilt-compensated compass heading (in degrees relative to the negative Y axis), which is communicated serially and can be displayed with the Arduino Serial Monitor. For the most accurate results, you should replace the values of m_min and m_max assigned in the setup() function with your own values obtained from the Calibrate example.

Library Reference

vector a

The last values read from the accelerometer.

vector m

The last values read from the magnetometer.

vector m_min

Lower bounds (minimum values) for the magnetometer readings on each axis; set this appropriately to calibrate heading().

vector m_max

Upper bounds (maximum values) for the magnetometer readings on each axis; set this appropriately to calibrate heading().

byte last_status

The status of the last I2C transmission. See the Wire.endTransmission() documentation for return values.

magGain magGain_?

Enum of values available as gain settings for the magnetometer.

LSM303(void)

Constructor; initializes m_min and m_max with placeholder values.

void init(byte device, byte sa0_a)

Initializes the library with the device being used (LSM303DLH, LSM303DLM, or LSM303DLHC) and the state of the SA0_A (accelerometer slave address least significant bit) pin. Constants for these arguments are defined in LSM303.h. Both of these arguments are optional; if they are not specified, the library will try to automatically detect the device and accelerometer address. However, the automatic detection might fail if you do not use the Pololu boards’ default accelerometer address, so you should specify your particular device if you change the state of the SA0_A pin.
Note: Automatic detection of the device type currently does not work with the Arduino Due because of issues with its Wire library. To work around this, specify the device and SA0_A state manually (e.g. init(LSM303DLM_DEVICE, LSM303_SA0_A_HIGH)).

byte getDeviceType(void)

Returns the device type detected by init().

void enableDefault(void)

Turns on the accelerometer and magnetometer in the default configuration. (This function was previously called enable().)

void writeAccReg(byte reg, byte value)

Writes an accelerometer register with the given value. Register address constants are defined in LSM303.h.

byte readAccReg(byte reg)

Reads an accelerometer register and returns the value read.

void writeMagReg(byte reg, byte value)

Writes a magnetometer register with the given value.

byte readMagReg(int reg)

Reads a magnetometer register and returns the value read. If the magnetometer Y and Z registers are read using register address constants beginning with LSM303_, this function will automatically use the correct register addresses depending on the device type.

void setMagGain(LSM303::magGain value)

Allows you to set the gain for the magnetometer, includes possible values as an enum.

void readAcc(void)

Takes a reading from the accelerometer and stores the values in the vector a.

void readMag(void)

Takes a reading from the magnetometer and stores the values in the vector m.

void read(void)

Takes a reading from both the accelerometer and magnetometer and stores the values in the vectors a and m.

void setTimeout(unsigned int timeout)

Sets a timeout period for readAcc() and readMag(), in milliseconds, after which they will abort if no data is received. A value of 0 disables the timeout.

unsigned int getTimeout(void)

Returns the current timeout period setting.

bool timeoutOccurred(void)

Returns a boolean indicating whether the last call to readAcc() or readMag() timed out.

int heading(void)

Returns the tilt-compensated heading of the negative Y axis in degrees (the angular difference in the horizontal plane between -Y and north).

int heading(vector from)

Returns the tilt-compensated heading of the given vector in degrees (the angular difference in the horizontal plane between from and north).

Differences from the LSM303DLH library

This library is very similar to our earlier LSM303DLH library, which is not compatible with the LSM303DLM or LSM303DLHC. Besides the name change, the main difference in this library is that you need to call the init() function before using any of the other library functions, typically from within the Arduino setup() function. While the older library only works with the Pololu boards’ default accelerometer slave address of 0011000b, this library allows you to specify the slave address with the init() function.

Version History

• 1.4.4 (2013-07-22): Corrected comments explaining heading() function.
• 1.4.3 (2013-03-15): Enable high resolution mode for LSM303DLHC accelerometer in enableDefault().
• 1.4.2 (2012-10-31): Cast sensor readings to 16-bit ints for better portability.
• 1.4.1 (2012-07-06): Added getDeviceType() function for programs that need to autodetect devices and distinguish between them.
• 1.4.0 (2012-05-24): Added magnetometer gain functions and reading timeout feature; thanks to Joshua Hogendorn and Eric Brundick for these contributions. Added keywords.txt and changed file extensions of examples to .ino.
• 1.3.0 (2011-12-12): Arduino 1.0 compatibility.
• 1.2.0 (2011-11-15): Original release. (numbered to avoid confusion with our earlier LSM303DLH library)