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.
For an example of this hardware integrated in a reference design, see the Nora overview in the Electric Imp Dev Center.
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);
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);
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");
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 |
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);
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);
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);
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.
magnetometer.setConversionMode(LIS3MDL.ONE_SHOT_MODE);
local reading = magnetometer.readAxes();
server.log("x: " + reading.x + " y: " + reading.y + " z: " + reading.z);
magnetometer.setConversionMode(LIS3MDL.ONE_SHOT_MODE);
magnetometer.readAxes(function(reading) {
server.log("x: " + reading.x + " y: " + reading.y + " z: " + reading.z);
});
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();
This method sets up the interrupt system on the LIS3MDL. The device starts with interrupts disabled by default.
| 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. |
| 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);
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 |
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);
Synchronizes the object’s data-reading scale with that stored on the device. This method is automatically called by the constructor and reset() functions.
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 |
The LIS3MDL class is licensed under the MIT License.