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

enum 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

enum 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

enum 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] dev QMC5883L 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]	dev	QMC5883L device descriptor
[in]	params	configuration 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]	dev	QMC583L device descriptor
[in]	cb	callback function triggered on DRDY events
[in]	arg	optional 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] dev QMC5883L 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] dev QMC5883L 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] dev QMC5883L 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] dev QMC5883L 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]	dev	QMC5883L device descriptor
[out]	data_out	buffer 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]	dev	QMC5883L device descriptor
[out]	data_out	buffer 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

Detailed Description

About

Usage

Polling

Interrupt based

Files

Data Structures

Macros

Enumerations

Functions

Enumeration Type Documentation

◆ anonymous enum

◆ qmc5883l_odr_t

◆ qmc5883l_osr_t

◆ qmc5883l_rng_t

Function Documentation

◆ qmc5883l_data_ready()

◆ qmc5883l_init()

◆ qmc5883l_init_int()

◆ qmc5883l_irq_disable()

◆ qmc5883l_irq_enable()

◆ qmc5883l_poweroff()

◆ qmc5883l_poweron()

◆ qmc5883l_read()

◆ qmc5883l_read_raw()