LIS3MDL library for Arduino

www.pololu.com

Summary

This is a library for the Arduino IDE that helps interface with ST's LIS3MDL 3-axis magnetometer via I²C. It makes it simple to configure the LIS3MDL and read the raw magnetometer data from these boards:

• LIS3MDL 3-axis magnetometer carrier
• MinIMU-9 v6 (LSM6DSO and LIS3MDL carrier)
• AltIMU-10 v6 (LSM6DSO, LIS3MDL, and LPS22DF Carrier)
• MinIMU-9 v5 (LSM6DS33 and LIS3MDL carrier)
• AltIMU-9 v5 (LSM6DS33, LIS3MDL, and LPS25H carrier)

Supported platforms

This library is designed to work with the Arduino IDE versions 1.6.x or later; we have not tested it with earlier versions. This library should support any Arduino-compatible board, including the Pololu A-Star 32U4 controllers.

Getting started

Hardware

An LIS3MDL carrier can be purchased from Pololu's website. Before continuing, careful reading of the product page as well as the LIS3MDL datasheet and application note is recommended.

Make the following connections between the Arduino and the LIS3MDL board:

5V Arduino boards

(including Arduino Uno, Leonardo, Mega; Pololu A-Star 32U4)

Arduino   LIS3MDL board
-------   -------------
     5V - VIN
    GND - GND
    SDA - SDA
    SCL - SCL

3.3V Arduino boards

(including Arduino Due)

Arduino   LIS3MDL board
-------   -------------
    3V3 - VIN
    GND - GND
    SDA - SDA
    SCL - SCL

Software

If you are using version 1.6.2 or later of the Arduino software (IDE), you can use the Library Manager to install this library:

1. In the Arduino IDE, open the "Sketch" menu, select "Include Library", then "Manage Libraries...".
2. Search for "LIS3MDL".
3. Click the LIS3MDL entry in the list.
4. Click "Install".

If this does not work, you can manually install the library:

1. Download the latest release archive from GitHub and decompress it.
2. Rename the folder "lis3mdl-arduino-master" to "LIS3MDL".
3. Move the "LIS3MDL" folder into the "libraries" directory inside your Arduino sketchbook directory. You can view your sketchbook location by opening the "File" menu and selecting "Preferences" in the Arduino IDE. If there is not already a "libraries" folder in that location, you should make the folder yourself.
4. After installing the library, restart the Arduino IDE.

Examples

Several example sketches are available that show how to use the library. You can access them from the Arduino IDE by opening the "File" menu, selecting "Examples", and then selecting "LIS3MDL". If you cannot find these examples, the library was probably installed incorrectly and you should retry the installation instructions above.

Library reference

• vector<int16_t> m
  The last values read from the magnetometer.

• uint8_t last_status
  The status of the last I²C write transmission. See the Wire.endTransmission() documentation for return values.

• LIS3MDL(void)
  Constructor.

• bool init(deviceType device, sa0State sa0)
  Initializes the library with the device being used (device_LIS3MDL or device_auto) and the state of the SA1 pin (sa1_low, sa1_high, or sa1_auto), which determines the second-least significant bit of the I²C slave address. Constants for these arguments are defined in LIS3MDL.h. Both of these arguments are optional; if they are not specified, the library will try to automatically detect the device address. A boolean is returned indicating whether the type of device was successfully determined (if necessary).

• void getDeviceType(void)
  Returns the device type specified to or detected by init().

• void enableDefault(void)
  Turns on the magnetometer and enables a consistent set of default settings.

  This function will reset the magnetometer to ±4 gauss full scale. See the comments in LIS3MDL.cpp for a full explanation of the settings.

• void writeReg(uint8_t reg, uint8_t value)
  Writes a sensor register with the given value.

  Register address constants are defined by the regAddr enumeration type in LIS3MDL.h.
  Example use: mag.writeReg(LIS3MDL::CTRL_REG1, 0x70);

• uint8_t readReg(uint8_t reg)
  Reads a sensor register and returns the value read.

• void read(void)
  Takes a reading from the magnetometer and stores the values in the vector m. Conversion of the readings to units of gauss depends on the magnetometer's selected gain (full scale setting).

• void setTimeout(uint16_t timeout)
  Sets a timeout period in milliseconds after which the read functions will abort if the sensor is not ready. A value of 0 disables the timeout.

• uint16_t getTimeout(void)
  Returns the current timeout period setting.

• bool timeoutOccurred(void)
  Indicates whether a read timeout has occurred since the last call to timeoutOccurred().

Version history

• 2.0.0 (2023-06-13): Removed timeout functionality that did not work as intended. Changed enableDefault() to enable BDU. Added HeadingWithLSM6 example.
• 1.0.0 (2016-01-19): Original release.