QMC5883L 3-Axis Digital Magnetic Sensor

Driver for QST QMC5883L digital magnetic sensor. More...

Detailed Description

Driver for QST QMC5883L digital magnetic sensor.

About

This module provides a device driver for the QML5883L magnetic sensor (digital compass) by QST. This device is a successor and similar to the Honeywell HMC5883L, it does use a different register map and uses a different style of configuration.

Usage

Use the qmc5883l_init() function to initialize your sensor. On exit of the initialization function, the sensor is put into continuous sampling mode (power on) mode.

For reading the sampled data, you have two options: use polling or use interrupt based notifications.

Polling

You call periodically call qmc5883l_read[_raw]() directly and simply check the return value to be QMC5883L_OK or QMC5883L_OVERFLOW for valid data. Alternatively call qmc5883l_data_ready() to explicitly ask the sensor if new data is available.

Interrupt based

For the interrupt mode to be available, you have to build the driver with the associated functions using USEMODULE += qmc5883l_int.

To configure and enable interrupt notifications for data ready events use the qmc5883l_init_int() function. This will setup the configured interrupt pin (params->pin_drdy) and enable the DRDY pin output for the QMC5883L sensor.

Warning
The DRDY interrupt callback is executed in interrupt context, so do not call any driver API function directly inside the callback! Instead use some IPC to notify a thread.

Files

file  qmc5883l.h
 API definition for the QMC5883L device driver.
 
file  qmc5883l_params.h
 Default configuration for QMC5883L devices.
 
file  qmc5883l_internal.h
 Register definitions for the QMC5883L device driver.
 

Data Structures

struct  qmc5883l_params_t
 QMC5883L initialization parameters. More...
 
struct  qmc5883l_t
 QMC5883L device descriptor. More...
 

Macros

#define QMC5883L_ADDR   (0x0d)
 Static QMC5883L I2C address (can not be changed)
 

Enumerations

enum  {
  QMC5883L_OK, QMC5883L_NODATA, QMC5883L_OVERFLOW, QMC5883L_BUSERR,
  QMC5883L_NOCFG
}
 Error codes used by the QMC5883L driver. More...
 
enum  qmc5883l_odr_t { QMC5883L_ODR_10HZ = (0u << 2), QMC5883L_ODR_50HZ = (1u << 2), QMC5883L_ODR_100HZ = (2u << 2), QMC5883L_ODR_200HZ = (3u << 2) }
 Output data rate. More...
 
enum  qmc5883l_rng_t { QMC5883L_RNG_2G = (0u << 4), QMC5883L_RNG_8G = (1u << 4) }
 Output value range. More...
 
enum  qmc5883l_osr_t { QMC5883L_OSR_512 = (0u << 6), QMC5883L_OSR_256 = (1u << 6), QMC5883L_OSR_128 = (2u << 6), QMC5883L_OSR_64 = (3u << 6) }
 Over sample rate (bandwidth of internal digital filter) More...
 

Functions

int qmc5883l_init (qmc5883l_t *dev, const qmc5883l_params_t *params)
 Initialize the given QMC5883L magnetic sensor. More...
 
int qmc5883l_data_ready (const qmc5883l_t *dev)
 Check if new data is available. More...
 
int qmc5883l_read (const qmc5883l_t *dev, int16_t *data_out)
 Read sampled data from the device [converted to milli-Gauss]. More...
 
int qmc5883l_read_raw (const qmc5883l_t *dev, int16_t *data_out)
 Read RAW data from the device. More...
 
int qmc5883l_poweron (const qmc5883l_t *dev)
 Power on the sensor (put it into continuous sampling mode) More...
 
int qmc5883l_poweroff (const qmc5883l_t *dev)
 Power off the sensor (put it into standby mode) More...
 
int qmc5883l_init_int (const qmc5883l_t *dev, gpio_cb_t cb, void *arg)
 Initialize data ready (DRDY) interrupt notifications. More...
 
int qmc5883l_irq_enable (const qmc5883l_t *dev)
 Enable the data ready (DRDY) interrupt. More...
 
int qmc5883l_irq_disable (const qmc5883l_t *dev)
 Disable the data ready (DRDY) interrupt. More...
 

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Error codes used by the QMC5883L driver.

Enumerator
QMC5883L_OK 

success

QMC5883L_NODATA 

no data are available

QMC5883L_OVERFLOW 

at least one axis overflowed its range

QMC5883L_BUSERR 

i2c bus error

QMC5883L_NOCFG 

configuration error

Definition at line 76 of file qmc5883l.h.

◆ qmc5883l_odr_t

Output data rate.

"Output data rate is controlled by ODR registers. Four data update frequencies can be selected: 10Hz, 50Hz, 100Hz and 200Hz. For most of compassing applications, we recommend 10 Hz for low power consumption. For gaming, the high update rate such as 100Hz or 200Hz can be used." (datasheet V1.0, p.17)

Enumerator
QMC5883L_ODR_10HZ 

10Hz data output rate

QMC5883L_ODR_50HZ 

50Hz data output rate

QMC5883L_ODR_100HZ 

100Hz data output rate

QMC5883L_ODR_200HZ 

200Hz data output rate

Definition at line 93 of file qmc5883l.h.

◆ qmc5883l_osr_t

Over sample rate (bandwidth of internal digital filter)

"Over sample Rate (OSR) registers are used to control bandwidth of an internal digital filter. Larger OSR value leads to smaller filter bandwidth, less in-band noise and higher power consumption. It could be used to reach a good balance between noise and power. Four over sample ratio can be selected, 64, 128, 256 or 512." (datasheet V1.0, p.17)

Enumerator
QMC5883L_OSR_512 

512 samples per reading

QMC5883L_OSR_256 

256 samples per reading

QMC5883L_OSR_128 

128 samples per reading

QMC5883L_OSR_64 

64 samples per reading

Definition at line 124 of file qmc5883l.h.

◆ qmc5883l_rng_t

Output value range.

"Field ranges of the magnetic sensor can be selected through the register RNG. The full scale field range is determined by the application environments. For magnetic clear environment, low field range such as +/- 2gauss can be used. The field range goes hand in hand with the sensitivity of the magnetic sensor. The lowest field range has the highest sensitivity, therefore, higher resolution." (datasheet V1.0, p.17)

Enumerator
QMC5883L_RNG_2G 

2 Gauss data output range

QMC5883L_RNG_8G 

8 Gauss data output range

Definition at line 110 of file qmc5883l.h.

Function Documentation

◆ qmc5883l_data_ready()

int qmc5883l_data_ready ( const qmc5883l_t dev)

Check if new data is available.

Precondition
dev != NULL
Parameters
[in]devQMC5883L device descriptor
Returns
QMC5883L_OK if new data is available
QMC5883L_NODATA if no new data is available
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_init()

int qmc5883l_init ( qmc5883l_t dev,
const qmc5883l_params_t params 
)

Initialize the given QMC5883L magnetic sensor.

Precondition
dev != NULL
params != NULL
Parameters
[out]devQMC5883L device descriptor
[in]paramsconfiguration parameters
Returns
QMC5883L_OK on success
QMC5883L_NOCFG on configuration error
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_init_int()

int qmc5883l_init_int ( const qmc5883l_t dev,
gpio_cb_t  cb,
void *  arg 
)

Initialize data ready (DRDY) interrupt notifications.

After this function is called the DRDY interrupt is enabled, so there is no need to call qmc5883l_irq_enable() afterwards.

Configure and enable the data ready (DRDY) interrupt

This function sets up the configured GPIO pin to trigger the given callback for rising edges and it enables the interrupt signal generation for the given QMC5883L sensor.

Warning
The given callback function is executed in interrupt context. Make sure not to call any driver API function in that context!
Precondition
dev != NULL
cb != NULL
Parameters
[in]devQMC583L device descriptor
[in]cbcallback function triggered on DRDY events
[in]argoptional user argument passed to cb
Returns
QMC5883L_OK on success
QMC5883L_NOCFG on GPIO configuration errors
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_irq_disable()

int qmc5883l_irq_disable ( const qmc5883l_t dev)

Disable the data ready (DRDY) interrupt.

Precondition
dev != NULL
Parameters
[in]devQMC5883L device descriptor
Returns
QMC5883L_OK on success
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_irq_enable()

int qmc5883l_irq_enable ( const qmc5883l_t dev)

Enable the data ready (DRDY) interrupt.

Note
Call this function only after you have configured the DRDY interrupt
Precondition
dev != NULL
Parameters
[in]devQMC5883L device descriptor
Returns
QMC5883L_OK on success
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_poweroff()

int qmc5883l_poweroff ( const qmc5883l_t dev)

Power off the sensor (put it into standby mode)

Precondition
dev != NULL
Parameters
[in]devQMC5883L device descriptor
Returns
QMC5883L_OK on success
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_poweron()

int qmc5883l_poweron ( const qmc5883l_t dev)

Power on the sensor (put it into continuous sampling mode)

Precondition
dev != NULL
Parameters
[in]devQMC5883L device descriptor
Returns
QMC5883L_OK on success
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_read()

int qmc5883l_read ( const qmc5883l_t dev,
int16_t *  data_out 
)

Read sampled data from the device [converted to milli-Gauss].

Precondition
dev != NULL
data_out != NULL
Parameters
[in]devQMC5883L device descriptor
[out]data_outbuffer for holding the resulting vector, must be able to hold 3 data items (x, y, z)
Returns
QMC5883L_OK on data being written to data_out
QMC5883L_OVERFLOW on data successfully read, but at least one data item overflowed its data range
QMC5883L_NODATA if no new data is available, nothing is written to data_out
QMC5883L_BUSERR on any I2C bus error

◆ qmc5883l_read_raw()

int qmc5883l_read_raw ( const qmc5883l_t dev,
int16_t *  data_out 
)

Read RAW data from the device.

This function returns the configured data range of 2 or 8 Gauss mapped to 16-bit signed integers [–32768:32767].

Precondition
dev != NULL
data_out != NULL
Parameters
[in]devQMC5883L device descriptor
[out]data_outbuffer for holding the resulting vector, must be able to hold 3 data items (x, y, z)
Returns
QMC5883L_OK on data being written to data_out
QMC5883L_OVERFLOW on data successfully read, but at least one data item overflowed its data range
QMC5883L_NODATA if no new data is available, nothing is written to data_out
QMC5883L_BUSERR on any I2C bus error