MAG3110  v0.1.7
A C++ library for the SparkFun 3-axis magnetometer breakout board
Public Member Functions
MAG3110 Class Reference

A class to drive the MAG3110 3-axis magnetometer. More...

#include <mag3110.hpp>

Public Member Functions

 MAG3110 (void)
 Default constructor. More...
 
 ~MAG3110 (void)
 Default destcructor. More...
 
void getVersion (void) const
 
void setDebug (bool t_debug)
 Control debug output. More...
 
void initialize (const char *t_bus)
 Initialize I2C communication. More...
 
uint8_t readRegister (uint8_t const &t_addr) const
 Read a register. More...
 
void writeRegister (uint8_t const &t_addr, uint8_t const &t_val) const
 Write a register. More...
 
void standby (void)
 Standby. More...
 
void start (void) const
 Start. More...
 
void reset (void)
 Reset. More...
 
bool isActive (void) const
 Test if active. More...
 
bool isRaw (void) const
 Test if raw mode. More...
 
void setRawMode (bool const t_raw) const
 Set raw mode. More...
 
void setFastRead (bool const t_fast) const
 Set fast read. More...
 
void triggerMeasurement (void) const
 Trigger measurement. More...
 
bool isDataReady (void) const
 Test if new data are ready. More...
 
void setDR_OS (uint8_t const t_DROS)
 Set data rate and oversampling ratio. More...
 
uint8_t getDR_OS (void) const
 Get data rate and oversampling ratio. More...
 
void setDelay (uint8_t t_DROS)
 Set delay. More...
 
void setDelay (int t_delay)
 Set delay. More...
 
int getDelay (void) const
 Get delay. More...
 
void setOffset (int const &t_bxoff, int const &t_byoff, int const &t_bzoff) const
 Set magnetic offset. More...
 
void getOffset (int *t_bxoff, int *t_byoff, int *t_bzoff) const
 Get magnetic offset. More...
 
void calibrate (void)
 Calibrate magnetic reading. More...
 
void getMag (int *t_bx, int *t_by, int *t_bz) const
 Get magnetic field strength. More...
 
void getMagDelayed (int *t_bx, int *t_by, int *t_bz) const
 Get magnetic field strength (delayed) More...
 
void getMagPoll (int *t_bx, int *t_by, int *t_bz) const
 Poll magnetic field strength. More...
 
double getMagnitude (int const &t_bx, int const &t_by, int const &t_bz) const
 Calculate magnetic field strength. More...
 
void displayMag (int const &t_bx, int const &t_by, int const &t_bz) const
 Display magnetic field strength. More...
 
void displayMag (int const &t_bx, int const &t_by, int const &t_bz, double const &t_mag) const
 Display magnetic field strength. More...
 
int getTemperature (void) const
 Get temperature. More...
 

Static Public Attributes

General attributes
static uint8_t const MAG3110_I2C_ADDRESS = 0x0E
 I2C address of the chip.
 
static uint8_t const MAG3110_WHO_AM_I_RSP = 0xC4
 Device identifier.
 
static int const MAG3110_DIE_TEMP_OFFSET = 11
 Temperature offset.
 
Register addresses
static uint8_t const MAG3110_DR_STATUS = 0x00
 Data ready status per axis.
 
static uint8_t const MAG3110_OUT_X_MSB = 0x01
 Bits [15:8] of X measurement.
 
static uint8_t const MAG3110_OUT_X_LSB = 0x02
 Bits [7:0] of X measurement.
 
static uint8_t const MAG3110_OUT_Y_MSB = 0x03
 Bits [15:8] of Y measurement.
 
static uint8_t const MAG3110_OUT_Y_LSB = 0x04
 Bits [7:0] of Y measurement.
 
static uint8_t const MAG3110_OUT_Z_MSB = 0x05
 Bits [15:8] of Z measurement.
 
static uint8_t const MAG3110_OUT_Z_LSB = 0x06
 Bits [7:0] of Z measurement.
 
static uint8_t const MAG3110_WHO_AM_I = 0x07
 Device identification.
 
static uint8_t const MAG3110_SYSMOD = 0x08
 Current System Mode.
 
static uint8_t const MAG3110_OFF_X_MSB = 0x09
 Bits [14:7] of user X offset.
 
static uint8_t const MAG3110_OFF_X_LSB = 0x0A
 Bits [6:0] of user X offset.
 
static uint8_t const MAG3110_OFF_Y_MSB = 0x0B
 Bits [14:7] of user Y offset.
 
static uint8_t const MAG3110_OFF_Y_LSB = 0x0C
 Bits [6:0] of user Y offset.
 
static uint8_t const MAG3110_OFF_Z_MSB = 0x0D
 Bits [14:7] of user Z offset.
 
static uint8_t const MAG3110_OFF_Z_LSB = 0x0E
 Bits [6:0] of user Z offset.
 
static uint8_t const MAG3110_DIE_TEMP = 0x0F
 Temperature, signed 8 bits in °C.
 
static uint8_t const MAG3110_CTRL_REG1 = 0x10
 Operation modes.
 
static uint8_t const MAG3110_CTRL_REG2 = 0x11
 Operation modes.
 
Control register 1: data rate and oversampling settings
static uint8_t const MAG3110_DR_OS_80_16 = 0x00
 Output rate = 80 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_40_32 = 0x08
 Output rate = 40 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_20_64 = 0x10
 Output rate = 20 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_10_128 = 0x18
 Output rate = 10 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_40_16 = 0x20
 Output rate = 40 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_20_32 = 0x28
 Output rate = 20 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_10_64 = 0x30
 Output rate = 10 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_5_128 = 0x38
 Output rate = 5 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_20_16 = 0x40
 Output rate = 20 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_10_32 = 0x48
 Output rate = 10 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_5_64 = 0x50
 Output rate = 5 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_2_5_128 = 0x58
 Output rate = 2.5 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_10_16 = 0x60
 Output rate = 10 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_5_32 = 0x68
 Output rate = 5 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_2_5_64 = 0x70
 Output rate = 2.5 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_1_25_128 = 0x78
 Output rate = 1.25 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_5_16 = 0x80
 Output rate = 5 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_2_5_32 = 0x88
 Output rate = 2.5 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_1_25_64 = 0x90
 Output rate = 1.25 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_0_63_128 = 0x98
 Output rate = 0.63 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_2_5_16 = 0xA0
 Output rate = 2.5 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_1_25_32 = 0xA8
 Output rate = 1.25 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_0_63_64 = 0xB0
 Output rate = 0.63 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_0_31_128 = 0xB8
 Output rate = 0.31 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_1_25_16 = 0xC0
 Output rate = 1.25 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_0_63_32 = 0xC8
 Output rate = 0.63 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_0_31_64 = 0xD0
 Output rate = 0.31 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_0_16_128 = 0xD8
 Output rate = 0.16 Hz, oversampling ratio = 128.
 
static uint8_t const MAG3110_DR_OS_0_63_16 = 0xE0
 Output rate = 0.63 Hz, oversampling ratio = 16.
 
static uint8_t const MAG3110_DR_OS_0_31_32 = 0xE8
 Output rate = 0.31 Hz, oversampling ratio = 32.
 
static uint8_t const MAG3110_DR_OS_0_16_64 = 0xF0
 Output rate = 0.16 Hz, oversampling ratio = 64.
 
static uint8_t const MAG3110_DR_OS_0_08_128 = 0xF8
 Output rate = 0.08 Hz, oversampling ratio = 128.
 
Control register 1: other settings
static uint8_t const MAG3110_FAST_READ = 0x04
 Fast read mode.
 
static uint8_t const MAG3110_TRIGGER_MEASUREMENT = 0x02
 Trigger immediate measurement.
 
static uint8_t const MAG3110_ACTIVE_MODE = 0x01
 Operation mode.
 
Control register 2 settings
static uint8_t const MAG3110_AUTO_MRST_EN = 0x80
 Automatic magnetic sensor reset.
 
static uint8_t const MAG3110_RAW_MODE = 0x20
 Data output correction.
 
static uint8_t const MAG3110_MAG_RST = 0x10
 Magnetic sensor reset (one-shot).
 
SYSMOD readings
static uint8_t const MAG3110_SYSMOD_STANDBY = 0x00
 Standby mode.
 
static uint8_t const MAG3110_SYSMOD_ACTIVE_RAW = 0x01
 Active mode, raw data.
 
static uint8_t const MAG3110_SYSMOD_ACTIVE = 0x02
 Active mode, user corrected data.
 
DR_STATUS readings
static uint8_t const MAG3110_DR_STATUS_XDR = 0x01
 X-axis new data available.
 
static uint8_t const MAG3110_DR_STATUS_YDR = 0x02
 Y-axis new data available.
 
static uint8_t const MAG3110_DR_STATUS_ZDR = 0x04
 Z-axis new data available.
 
static uint8_t const MAG3110_DR_STATUS_XYZDR = 0x08
 X-,Y- or Z-axis new data available.
 
static uint8_t const MAG3110_DR_STATUS_XOW = 0x10
 X-axis data overwrite.
 
static uint8_t const MAG3110_DR_STATUS_YOW = 0x20
 Y-axis data overwrite.
 
static uint8_t const MAG3110_DR_STATUS_ZOW = 0x40
 Z-axis data overwrite.
 
static uint8_t const MAG3110_DR_STATUS_XYZOW = 0x80
 X-, Y- or Z-axis data overwrite.
 
Magnetometer base address
static uint8_t const MAG3110_X_AXIS = 0x01
 X-axis base address.
 
static uint8_t const MAG3110_Y_AXIS = 0x03
 Y-axis base address.
 
static uint8_t const MAG3110_Z_AXIS = 0x05
 Z-axis base address.
 

Detailed Description

A class to drive the MAG3110 3-axis magnetometer.

This class is derived from the Sparkfun Arduino library and has been ported to plain C++.

Author
Alexander Pohl alex@.nosp@m.ahpo.nosp@m.hl.co.nosp@m.m
Examples:
mag3110_active.cpp, mag3110_basic.cpp, mag3110_calibrated.cpp, mag3110_dros.cpp, mag3110_fast.cpp, mag3110_interrupt.cpp, mag3110_offset.cpp, mag3110_poll.cpp, mag3110_raw.cpp, mag3110_slow.cpp, and mag3110_triggered.cpp.

Constructor & Destructor Documentation

MAG3110::MAG3110 ( void  )

Default constructor.

The default constructor initializes the private member variables.

MAG3110::~MAG3110 ( void  )

Default destcructor.

The default destructor removes the I2C bus handle

Member Function Documentation

void MAG3110::calibrate ( void  )

Calibrate magnetic reading.

This function calibrates the magnetic readings of the chip. The initial magnetic induction is set to approximately zero along each axis by applying a user magnetic offset.

See also
setOffset()
getOffset()
Examples:
mag3110_calibrated.cpp.
void MAG3110::displayMag ( int const &  t_bx,
int const &  t_by,
int const &  t_bz 
) const

Display magnetic field strength.

This function displays the magnetic field strength along each axis.

Parameters
t_bxX-axis component
t_byY-axis component
t_bzZ-axis component
See also
getMag()
Examples:
mag3110_basic.cpp, mag3110_calibrated.cpp, mag3110_fast.cpp, mag3110_interrupt.cpp, mag3110_offset.cpp, mag3110_poll.cpp, mag3110_slow.cpp, and mag3110_triggered.cpp.
void MAG3110::displayMag ( int const &  t_bx,
int const &  t_by,
int const &  t_bz,
double const &  t_mag 
) const

Display magnetic field strength.

This function displays the magnetic field strength along each axis and the magnitude of the magnetic field.

Parameters
t_bxX-axis component
t_byY-axis component
t_bzZ-axis component
t_magMagnitute of magnetic field
See also
getMag()
int MAG3110::getDelay ( void  ) const

Get delay.

This function gets the delay between measurements.

Returns
Delay in [ms]
See also
setDelay(uint8_t)
setDelay(int)
Examples:
mag3110_poll.cpp.
uint8_t MAG3110::getDR_OS ( void  ) const

Get data rate and oversampling ratio.

This function gets the date rate (DR) and oversampling ratio (OS) setting.

Returns
MAG3110_DR_OS_* constant
See also
setDR_OS()
Examples:
mag3110_dros.cpp, mag3110_interrupt.cpp, and mag3110_poll.cpp.
void MAG3110::getMag ( int *  t_bx,
int *  t_by,
int *  t_bz 
) const

Get magnetic field strength.

This function gets the magnetic field strength along each axis.

Parameters
t_bxX-axis component
t_byY-axis component
t_bzZ-axis component
See also
getMagDelayed()
getMagPoll()
Examples:
mag3110_basic.cpp, mag3110_calibrated.cpp, mag3110_interrupt.cpp, mag3110_offset.cpp, and mag3110_triggered.cpp.
void MAG3110::getMagDelayed ( int *  t_bx,
int *  t_by,
int *  t_bz 
) const

Get magnetic field strength (delayed)

This function gets the magnetic field strength along each axis. The output is delayed.

Parameters
t_bxX-axis component
t_byY-axis component
t_bzZ-axis component
See also
getMag()
getMagPoll()
setDelay(int)
Examples:
mag3110_fast.cpp, and mag3110_slow.cpp.
double MAG3110::getMagnitude ( int const &  t_bx,
int const &  t_by,
int const &  t_bz 
) const

Calculate magnetic field strength.

This function calculates the magnitude of the magnetic field.

Parameters
t_bxX-axis component
t_byY-axis component
t_bzZ-axis component
Returns
Magnitude of the magnetic field
See also
getMag()
getMagDelayed()
getMagPoll()
Examples:
mag3110_calibrated.cpp.
void MAG3110::getMagPoll ( int *  t_bx,
int *  t_by,
int *  t_bz 
) const

Poll magnetic field strength.

This function polls the magnetic field strength along each axis. It waits until new data is ready before a new read request is made.

Parameters
t_bxX-axis component
t_byY-axis component
t_bzZ-axis component
See also
getMag()
getMagDelayed()
Examples:
mag3110_poll.cpp.
void MAG3110::getOffset ( int *  t_bxoff,
int *  t_byoff,
int *  t_bzoff 
) const

Get magnetic offset.

This function gets the user magnetic offsets.

Parameters
t_bxoffX-axis magnetic offset
t_byoffY-axis magnetic offset
t_bzoffZ-axis magnetic offset
See also
setOffset()
calibrate()
Examples:
mag3110_calibrated.cpp, and mag3110_offset.cpp.
int MAG3110::getTemperature ( void  ) const

Get temperature.

This function reads the die temperature inside the chip. The output range is limited from -40°C to 125°C

Returns
Temperature in °C
void MAG3110::getVersion ( void  ) const

brief Get library version

This function outputs the library version and build date

void MAG3110::initialize ( const char *  t_bus)

Initialize I2C communication.

This funtion initializes the I2C communication with the chip and identifies the chip as a MAG3110.

Parameters
t_busThe I2C bus device
Examples:
mag3110_active.cpp, mag3110_basic.cpp, mag3110_calibrated.cpp, mag3110_dros.cpp, mag3110_fast.cpp, mag3110_interrupt.cpp, mag3110_offset.cpp, mag3110_poll.cpp, mag3110_raw.cpp, mag3110_slow.cpp, and mag3110_triggered.cpp.
bool MAG3110::isActive ( void  ) const

Test if active.

This function tests whether the chip is in operation mode or in standby mode.

Returns
True: chip is active, false: chip is in standby
Examples:
mag3110_active.cpp, and mag3110_triggered.cpp.
bool MAG3110::isDataReady ( void  ) const

Test if new data are ready.

This function reads the ZYXDR bit of the DR_STATUS register and reports if new magnetic data are available.

Returns
True: new set of data ready, false: no new data ready
bool MAG3110::isRaw ( void  ) const

Test if raw mode.

This function tests whether the chip is in active raw mode.

Returns
True: chip is in active raw mode, false: chip is not in active raw mode
Examples:
mag3110_raw.cpp.
uint8_t MAG3110::readRegister ( uint8_t const &  t_addr) const

Read a register.

This function reads a register at the given address

Parameters
t_addrAddress of the register
void MAG3110::reset ( void  )

Reset.

This function resets the control registers, selects the default data rate and oversampling setting and resets the user provided axes offsets.

Examples:
mag3110_basic.cpp, mag3110_calibrated.cpp, mag3110_dros.cpp, mag3110_fast.cpp, mag3110_interrupt.cpp, mag3110_offset.cpp, mag3110_poll.cpp, mag3110_slow.cpp, and mag3110_triggered.cpp.
void MAG3110::setDebug ( bool  t_debug)

Control debug output.

This function enables or disables debug output of the member functions.

Parameters
t_debugTrue: debug output enabled, false: debug output disabled
Examples:
mag3110_poll.cpp.
void MAG3110::setDelay ( uint8_t  t_DROS)

Set delay.

This function sets a delay between measurements. The length of the delay is pre-determined by the current data rate and oversampling setting and ranges from 13 ms (80 Hz) to 12.8 s (0.08 Hz).

Parameters
t_DROSData rate and oversampling ratio setting
See also
setDelay(int)
getDelay()
void MAG3110::setDelay ( int  t_delay)

Set delay.

This function sets a delay between measurements in milli seconds.

Parameters
t_delayDelay in [ms]
See also
setDelay(uint8_t)
getDelay()
void MAG3110::setDR_OS ( uint8_t const  t_DROS)

Set data rate and oversampling ratio.

This function sets the data rate (DR) and the oversampling ratio (OS) of the chip. The combination of the two settings determines the ADC data rate (80-1280 Hz), the typical current (8.6-900.0 µA) and the average noise level (0.25-0.40 µT rms). For details see the technical reference on page 20.

Parameters
t_DROSdata rate and oversampling ratio setting
See also
getDR_OS()
Examples:
mag3110_dros.cpp, mag3110_interrupt.cpp, mag3110_poll.cpp, and mag3110_slow.cpp.
void MAG3110::setFastRead ( bool const  t_fast) const

Set fast read.

This function selects a fast read mode. In normal read mode, the full 16-bit values are read. With fast read enabled, 8-bit values are read from the MSB registers (auto-increment skips over the LSB register in burst-read mode).

Parameters
t_fastTrue: enable fast read, false: disable fast read
void MAG3110::setOffset ( int const &  t_bxoff,
int const &  t_byoff,
int const &  t_bzoff 
) const

Set magnetic offset.

This function sets a user magnetic offset. The user offsets have a maximum range -10.000 to +10.000 bit counts per x, y, z-axis and are automatically substracted from the magnetic field readings before they are written to the output registers. The user offsets are not substracted when the chip is in raw active mode.

Parameters
t_bxoffX-axis magnetic offset
t_byoffY-axis magnetic offset
t_bzoffZ-axis magnetic offset
See also
getOffset()
calibrate()
Examples:
mag3110_offset.cpp.
void MAG3110::setRawMode ( bool const  t_raw) const

Set raw mode.

This function puts the chip into active raw mode. In raw active mode, the chip does not automatically apply the user offset correction and outputs the raw magnetometer reading. Useful for calibration.

Parameters
t_rawTrue: enable active raw mode, false: disable active raw mode
Examples:
mag3110_raw.cpp.
void MAG3110::standby ( void  )

Standby.

This function puts the chip into standby mode.

Examples:
mag3110_active.cpp.
void MAG3110::start ( void  ) const

Start.

This function puts the chip into operation mode.

Examples:
mag3110_active.cpp, mag3110_basic.cpp, mag3110_calibrated.cpp, mag3110_dros.cpp, mag3110_fast.cpp, mag3110_interrupt.cpp, and mag3110_slow.cpp.
void MAG3110::triggerMeasurement ( void  ) const

Trigger measurement.

This function triggers a measurement. In standby mode, the measurement will occur immediately and the chip returns to standby. In active mode, any measurement in progress will continue with the highest possible data rate for the currently selected oversampling rate.

Examples:
mag3110_offset.cpp, and mag3110_triggered.cpp.
void MAG3110::writeRegister ( uint8_t const &  t_addr,
uint8_t const &  t_val 
) const

Write a register.

This function writes a value to the register at the given address.

Parameters
t_addrAddress of the register
t_valValue to write