h1. Arduino library for the Pololu LSM303DLH carrier board

Version: 1.1.1
Release Date: 2011-09-14
"www.pololu.com":http://www.pololu.com/

h2. Not recommended

This library is no longer recommended. It has been superseded by the more general "LSM303 library":https://github.com/pololu/LSM303, which also supports Arduino 1.0.

h2. Summary

This is a library for the "Arduino":http://pololu.com/catalog/product/1616 that interfaces with the Pololu "LSM303DLH 3D compass and accelerometer carrier":http://www.pololu.com/catalog/product/1250. It makes it simple to read the raw accelerometer and magnetometer data, and it has a function for computing the tilt-compensated heading for those looking to use this sensor as a tilt-compensated compass.

h2. Getting Started

h3. Software

Download the archive from "GitHub":https://github.com/pololu/LSM303DLH, decompress it, and drag the "LSM303DLH" folder to your arduino-00xx/libraries directory. Then restart the Arduino environment, so the libraries can be updated to include the LSM303DLH library and its examples.

h3. Hardware

The board for the LSM303DLH can be purchased on "Pololu's website":http://www.pololu.com/catalog/product/1250.

Make the following connections with wires between the Arduino and the LSM303DLH:

pre. Arduino Uno/Duemilanove     LSM303DLH Carrier
                    5V  ->  VIN
                   GND  ->  GND
          Analog Pin 5  ->  SCL
          Analog Pin 4  ->  SDA

pre. Arduino Mega                LSM303DLH Carrier
                    5V  ->  VIN
                   GND  ->  GND
         Analog Pin 21  ->  SCL
         Analog Pin 20  ->  SDA

h2. Example Programs

Open an example code sketch by selecting File->Examples->LSM303DLH->example_name

h3. 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:

pre. 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

h3. 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 LSM303DLH through every possible orientation.

h3. 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.

h2. 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()@.

- @LSM303DLH(void)@ := Constructor; initializes @m_min@ and @m_max@ with placeholder values.
- @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 LSM303DLH.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(byte reg)@ := Reads a magnetometer register and returns the value read.
- @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@.
- @int heading(void)@ := Returns the tilt-compensated heading in degrees headed away from the negative Y axis.
- @int heading(vector from)@ := Returns the tilt-compensated heading in degrees headed away from the from vector.