Skip to main content

LIS3MDL

Latest Version: 2.0.0

This class allows your device to drive the LIS3MDL Magnetometer (datasheet / application note). This device is a low-power, highly configurable three-axis magnetic sensor with support for user-defined interrupts.

The sensor supports I²C and SPI interfaces. This library currently only supports the I²C interface.

You can view the library’s source code on GitHub. Click here to see information on other versions of this library.

To add this library to your project, add #require "LIS3MDL.class.nut:2.0.0" to the top of your device code.

Examples and Hardware

For an example of this hardware integrated in a reference design, see the Nora overview in the Electric Imp Dev Center.

Class Usage

Constructor: LIS3MDL(i2cBus[, i2cAddress])

Creates and initializes an object representing the LIS3MDL magnetometer. This device must be configured with setConversionMode() before its sensors can be read.

Parameter Type Default Value Description
i2cBus hardware.i2c N/A A pre-configured I²C object
i2cAddress Byte 0x1C The LIS3MDL’s 8-bit I²C address

 Example

#require "LIS3MDL.class.nut:2.0.0"

local i2c = hardware.i2c89;
i2c.configure(CLOCK_SPEED_400_KHZ);

// Use alternate I2C address - SA1 pin tied high
magnetometer <- LIS3MDL(i2c, 0x3C);

Class Methods

setScale(scale)

Sets the full-scale range that the LIS3MDL should measure values across and returns the actual scale selected. Supported scale values are 4, 8, 12 and 16. Each value represents a maximum magnitude measured in gauss (eg. 4 represents a ±4 gauss range).

This input must be one of the four allowable values. Any other input value will be rounded down to the nearest legal value. The device starts with a full-scale range of 4 gauss by default.

magnetometer.setScale(8);

setDataRate(dataRate)

Sets the rate at which the LIS3MDL prepares new data readings and returns the actual data rate selected (or LIS3MDL.DATA_RATE_FAST when applicable). See table below for supported data rates. If an unsupported data rate is selected, the data rate will be rounded down to the closest supported rate. The device starts with a data rate of 40Hz by default — a different rate than that specified in the datasheet.

Rate Description
0.625 Hz value
1.25 Hz value
2.5 Hz value
5 Hz value
10 Hz value
20 Hz value
40 Hz value
80 Hz value
LIS3MDL.DATA_RATE_FAST Data rates between 155Hz and 1kHz are determined by the operating mode, as described below.

 
Example

// Set data rate to 2.5Hz
local rate = magnetometer.setDataRate(2.5);
server.log("Magnetometer is running at " + rate + "Hz");

Fast Data Rate Configuration

Data rates under this setting are dependent on the operating mode set with setPerformance().

Performance Rating Data Rate (Hz)
Ultra-high performance 155
High-performance 300
Medium-performance 560
Low-power 1000

setPerformance(performanceRating)

Sets the performance versus power trade-off used when measuring on the three axes. Increased performance will result in less noise, which lowers the threshold for the minimum detectable field. It will also result in longer start-up times. The device starts in low-power mode by default.

The parameter performanceRating is an integer between 0 and 3, assigned as follows:

performanceRating Meaning Time to First Read
0 Low power 1.2ms
1 Medium performance 1.65ms
2 High performance 3.23ms
3 Ultra-high performance 6.4ms

 
Example

// Set data rate to 155 Hz
magnetometer.setPerformance(3);
magnetometer.setDataRate(LIS3MDL.DATA_RATE_FAST);

setLowPower(state)

Switches the LIS3MDL in or out of low-power mode. In low-power mode, the output data rate is dropped to 0.625Hz and the system performs the minimum number of averages in its calculations. Switching back out of low-power mode will restore the previous output data rate. The device starts with low-power mode disabled.

// A very low-power magnetic field polling snippet

// Enable the LIS3MDL
magnetometer.setConversionMode(LIS3MDL.CONTINUOUS_MODE);

// Use the LIS3MDL in low power mode
magnetometer.setLowPower(true);

// Configure the Imp to wake from deep sleep on the LIS3MDL interrupt pin
hardware.pin1.configure(DIGITAL_IN_WAKEUP, function() {
    // Take a reading
    magnetometer.readAxes(function(reading) {
        server.log("x: " + reading.x + " y: " + reading.y + " z: " + reading.z);
    });
});

// Configure the LIS3MDL to wake the Imp from deep sleep mode if a magnetic field over 3 gauss is detected.
magnetometer.configureInterrupt(true, 3, LIS3MDL.AXIS_X);

// Put the Imp in deep sleep for one day.
imp.deepsleepfor(86400);

setConversionMode(mode)

Use setConversionMode() to enable measurements on all three axes. Available modes are tabled below. The device is started in LIS3MDL.SHUT_DOWN_MODE by default.

Note Powering down with this method does not completely disable the device. When powered down, all registers are still accessible, but the sensor will not collect new readings and calls to readAxes() will always return the same value.

mode Description
LIS3MDL.SHUT_DOWN_MODE Powers down the magnetic sensor
LIS3MDL.ONE_SHOT_MODE Immediately take a single measurement then returns to shut-down mode (LIS3MDL.SHUT_DOWN_MODE). One-shot mode must be used with sampling frequency from 0.625 Hz to 80Hz
LIS3MDL.CONTINUOUS_MODE Takes continuous measurements

 
Example

// Take a single reading
magnetometer.setConversionMode(LIS3MDL.ONE_SHOT_MODE);
server.log(magnetometer.readAxes().x);
imp.sleep(1);

// This log will show the same value as before
server.log(magnetometer.readAxes().x);

readAxes([callback])

The readAxes() method reads and returns the latest measurement from the magnetic field sensor. The reading is in the form of a table with x, y and z keys. The value from the sensor reading is automatically scaled to gauss.

The readAxes() method takes an optional callback for asynchronous operation. If a callback is specified, then the reading table will be passed to the callback as the only parameter. If not, the method will block until the reading had been taken, and the table will be returned.

Synchronous Example

magnetometer.setConversionMode(LIS3MDL.ONE_SHOT_MODE);
local reading = magnetometer.readAxes();
server.log("x: " + reading.x + " y: " + reading.y + " z: " + reading.z);

Asynchronous Example

magnetometer.setConversionMode(LIS3MDL.ONE_SHOT_MODE);
magnetometer.readAxes(function(reading) {
    server.log("x: " + reading.x + " y: " + reading.y + " z: " + reading.z);
});

readStatus()

Parses and returns the value of the LIS3MDL’s status register. A table is returned with following keys and booleans as values:

Key Description
ZYXOR Whether a X-, Y-, and Z-axis data over-run has occurred
ZOR Whether a Z-axis data over-run has occurred
YOR Whether a Y-axis data over-run has occurred
XOR Whether a X-axis data over-run has occurred
ZYXDA Whether there is new X-, Y-, and Z-axis data available
ZDA Whether there is new Z-axis data available
YDA Whether there is new Y-axis data available
XDA Whether there is new X-axis data available

 
Example

magnetometer.setLowPower(true);
magnetometer.setConversionMode(LIS3MDL.CONTINUOUS_MODE);

function statusLoop() {
    local status = magnetometer.readStatus();
    if (status.ZYXOR) {
        server.log("Over-run Occurred.");
        server.log("X over-run: " + status.XOR);
        server.log("Y over-run: " + status.YOR);
        server.log("Z over-run: " + status.ZOR);
    }

    if (status.ZYXDA) {
        server.log("New Data.");
        server.log("X data available: " + status.XDA);
        server.log("Y data available: " + status.YDA);
        server.log("Z data available: " + status.ZDA);
        local reading = magnetometer.readAxes();
        server.log("x: "+reading.x+" y: "+reading.y+" z: "+reading.z);
    }

    imp.wakeup(1, statusLoop);
}

statusLoop();

configureInterrupt(isEnabled[, threshold][, options])

This method sets up the interrupt system on the LIS3MDL. The device starts with interrupts disabled by default.

Parameters

Parameter Type Default Value Description
isEnabled Boolean N/A Whether the LIS3MDL should generate interrupts
threshold Integer 4 The threshold magnitude needed to trigger an interrupt. Threshold is in gauss. This value will be interpreted as a 16-bit unsigned integer and represents an absolute value (ie. a measured value of -20 will trigger an interrupt with a threshold of 10).
options Byte 0x00 Configuration options combined with the bitwise OR operator. See the ‘Options’ table below for available values.

Options

Option Interrupt Default Description
LIS3MDL.AXIS_X Disabled When this option is passed in the LIS3MDL will listen for interrupts on the x-axis
LIS3MDL.AXIS_Y Disabled When this option is passed in the LIS3MDL will listen for interrupts on the y-axis
LIS3MDL.AXIS_Z Disabled When this option is passed in the LIS3MDL will listen for interrupts on the z-axis
LIS3MDL.INTERRUPT_ACTIVEHIGH Device is ACTIVE LOW by default When this option is passed in the interrupt pin is configured in active-high mode
LIS3MDL.INTERRUPT_LATCH Disabled When this option is passed in latching will be enabled. If latching is disabled, the interrupt pin may change state even if readInterruptStatus() is not called

 
Example

// Enable interrupt monitoring on the X- and Y-axes with a threshold of 3 gauss
magnetometer.configureInterrupt(true, 3, LIS3MDL.AXIS_X | LIS3MDL.AXIS_Y);
// Disable interrupt monitoring
magnetometer.configureInterrupt(false);

readInterruptStatus()

This method returns the interrupt source register on the LIS3MDL. The return value is a table with following keys and booleans as values:

Key Type Description
x_positive Boolean If true the X-axis value exceeded the threshold on the positive side
x_negative Boolean If true the X-axis value exceeded the threshold on the negative side
y_positive Boolean If true the Y-axis value exceeded the threshold on the positive side
y_negative Boolean If true the Y-axis value exceeded the threshold on the negative side
z_positive Boolean If true the Z-axis value exceeded the threshold on the positive side
z_negative Boolean If true the Z-axis value exceeded the threshold on the negative side
overflow Boolean If true a value overflowed the internal measurement range
interrupt Integer The state of the interrupt pin at the time of the event

reset()

This method performs a software reset of the LIS3MDL’s registers. After calling reset you will need to reconfigure the magnetometer’s settings.

// Something bad just happened
magnetometer.reset();

// Start over
magnetometer.setDataRate(80);
magnetometer.setConversionMode(LIS3MDL.ONE_SHOT_MODE);
local reading = magnetometer.readAxes();
server.log("x: "+reading.x+" y: "+reading.y+" z: "+reading.z);

init()

Synchronizes the object’s data-reading scale with that stored on the device. This method is automatically called by the constructor and reset() functions.

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.0 GitHub Initial release
1.0.1 GitHub Bug fixes
2.0.0 GitHub Major update — check your code
setConversionType() replaced by setConversionMode(); enable() removed; bug fixes

License

The LIS3MDL class is licensed under the MIT License.