Device driver for the Honeywell HMC5883L 3-axis digital compass. More...

Detailed Description

Device driver for the Honeywell HMC5883L 3-axis digital compass.

The driver implements basic polling mode. The application can use different approaches to get new data, either

using the hmc5883l_read function at a lower rate than the the DOR, or
using the data-ready interrupt (DRDY), see hmc5883l_init_int.

The data-ready interrupt (DRDY) is only be available when module hmc5883l_int is enabled.

This driver provides [S]ensor [A]ctuator [U]ber [L]ayer capabilities.

Author: Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Files
file	hmc5883l_params.h
	Default configuration for the Honeywell HMC5883L 3-axis digital compass.

file	hmc5883l_regs.h
	Register definitions for the Honeywell HMC5883L 3-axis digital compass.

file	hmc5883l.h

Data Structures
struct	hmc5883l_data_t
	Magnetic field values in milli-Gauss (mGs) More...

struct	hmc5883l_raw_data_t
	Raw data set as two complements. More...

struct	hmc5883l_params_t
	HMC5883L device initialization parameters. More...

struct	hmc5883l_t
	HMC5883L sensor device data structure type. More...

Typedefs
typedef void(*	hmc5883l_drdy_int_cb_t) (void *)
	HMC5883L DRDY interrupt callback function type. More...

Enumerations
enum	hmc5883l_error_codes_t { HMC5883L_OK = 0, HMC5883L_ERROR_I2C = -1, HMC5883L_ERROR_WRONG_ID = -2, HMC5883L_ERROR_NO_DATA = -3, HMC5883L_ERROR_RAW_DATA = -4, HMC5883L_ERROR_COMMON = -5 }
	Definition of error codes. More...

enum	hmc5883l_dor_t { HMC5883L_DOR_0_75 = 0x00, HMC5883L_DOR_1_5 = 0x04, HMC5883L_DOR_3 = 0x08, HMC5883L_DOR_7_5 = 0x0c, HMC5883L_DOR_15 = 0x10, HMC5883L_DOR_30 = 0x14, HMC5883L_DOR_75 = 0x18 }
	Data output rates (DOR) More...

enum	hmc5883l_meas_mode_t { HMC5883L_MEAS_MODE_NORMAL = 0x00, HMC5883L_MEAS_MODE_BIAS_POS = 0x01, HMC5883L_MEAS_MODE_BIAS_NEG = 0x02 }
	Measurement modes. More...

enum	hmc5883l_meas_avg_t { HMC5883L_MEAS_AVG_NONE = 0x00, HMC5883L_MEAS_AVG_2 = 0x20, HMC5883L_MEAS_AVG_4 = 0x40, HMC5883L_MEAS_AVG_8 = 0x60 }
	Measurement avaraging (number of samples are averaged for output) More...

enum	hmc5883l_op_mode_t { HMC5883L_OP_MODE_CONTINUOUS = 0x00, HMC5883L_OP_MODE_SINGLE = 0x01, HMC5883L_OP_MODE_IDLE = 0x02 }
	Operation modes. More...

enum	hmc5883l_gain_t { HMC5883L_GAIN_1370 = 0x00, HMC5883L_GAIN_1090 = 0x20, HMC5883L_GAIN_820 = 0x40, HMC5883L_GAIN_660 = 0x60, HMC5883L_GAIN_440 = 0x80, HMC5883L_GAIN_390 = 0xa0, HMC5883L_GAIN_330 = 0xc0, HMC5883L_GAIN_230 = 0xe0 }
	Gain (determines the sensitivity and the range) More...

Functions
int	hmc5883l_init (hmc5883l_t dev, const hmc5883l_params_t params)
	Initialize the HMC5883L sensor device. More...

int	hmc5883l_init_int (hmc5883l_t dev, hmc5883l_drdy_int_cb_t cb, void arg)
	Initialize and activate the DRDY interrupt of HMC5883L sensor device. More...

int	hmc5883l_data_ready (const hmc5883l_t *dev)
	Data-ready status function. More...

int	hmc5883l_read (const hmc5883l_t dev, hmc5883l_data_t data)
	Read one sample of magnetic field values in milli-Gauss (mGs) More...

int	hmc5883l_read_raw (const hmc5883l_t dev, hmc5883l_raw_data_t raw)
	Read one sample of raw sensor data as 16 bit two's complements. More...

int	hmc5883l_power_down (hmc5883l_t *dev)
	Power down the sensor. More...

int	hmc5883l_power_up (hmc5883l_t *dev)
	Power up the sensor. More...

Typedef Documentation

◆ hmc5883l_drdy_int_cb_t

typedef void(* hmc5883l_drdy_int_cb_t) (void *)

HMC5883L DRDY interrupt callback function type.

Function prototype for the function which is called on DRDY interrupt if the interrupt is activated by hmc5883l_init_int and the interrupt pin is defined in device initialization parameters.

Note: The cb function is called in interrupt context. The application should do nothing time consuming and not directly access sensor data.

Definition at line 151 of file hmc5883l.h.

Enumeration Type Documentation

◆ hmc5883l_dor_t

enum hmc5883l_dor_t

Data output rates (DOR)

The values correspond to bits <4:2> of the HMC5883L_REG_CFG_A register.

Enumerator
HMC5883L_DOR_0_75	0.75 Hz
HMC5883L_DOR_1_5	1.5 Hz
HMC5883L_DOR_3	3 Hz
HMC5883L_DOR_7_5	7.5 Hz
HMC5883L_DOR_15	15 Hz (default)
HMC5883L_DOR_30	30 Hz
HMC5883L_DOR_75	75 Hz

Definition at line 61 of file hmc5883l.h.

◆ hmc5883l_error_codes_t

enum hmc5883l_error_codes_t

Definition of error codes.

Enumerator
HMC5883L_OK	success
HMC5883L_ERROR_I2C	any I2C communication error
HMC5883L_ERROR_WRONG_ID	wrong id read
HMC5883L_ERROR_NO_DATA	no data are available
HMC5883L_ERROR_RAW_DATA	reading raw data failed
HMC5883L_ERROR_COMMON	common error

Definition at line 47 of file hmc5883l.h.

◆ hmc5883l_gain_t

enum hmc5883l_gain_t

Gain (determines the sensitivity and the range)

The values correspond to bits <7:5> of the HMC5883L_REG_CFG_B_GN register.

Enumerator
HMC5883L_GAIN_1370	Range +-0.88 Gs, Resolution 0.73 mGs/LSB.
HMC5883L_GAIN_1090	Range +-1.3 Gs, Resolution 0.92 mGs/LSB.
HMC5883L_GAIN_820	Range +-1.9 Gs, Resolution 1.22 mGs/LSB.
HMC5883L_GAIN_660	Range +-2.5 Gs, Resolution 1.52 mGs/LSB.
HMC5883L_GAIN_440	Range +-4.0 Gs, Resolution 2.27 mGs/LSB.
HMC5883L_GAIN_390	Range +-4.7 Gs, Resolution 2.56 mGs/LSB.
HMC5883L_GAIN_330	Range +-5.6 Gs, Resolution 3.03 mGs/LSB.
HMC5883L_GAIN_230	Range +-8.1 Gs, Resolution 4.35 mGs/LSB.

Definition at line 110 of file hmc5883l.h.

◆ hmc5883l_meas_avg_t

enum hmc5883l_meas_avg_t

Measurement avaraging (number of samples are averaged for output)

The values correspond to bits <6:5> of the HMC5883L_REG_CFG_A register.

Enumerator
HMC5883L_MEAS_AVG_NONE	No averaging.
HMC5883L_MEAS_AVG_2	2 samples are averaged
HMC5883L_MEAS_AVG_4	4 samples are averaged
HMC5883L_MEAS_AVG_8	8 samples are averaged

Definition at line 87 of file hmc5883l.h.

◆ hmc5883l_meas_mode_t

enum hmc5883l_meas_mode_t

Measurement modes.

The values correspond to bits <1:0> of the HMC5883L_REG_CFG_A register.

Enumerator
HMC5883L_MEAS_MODE_NORMAL	Normal measurement config.
HMC5883L_MEAS_MODE_BIAS_POS	Positive bias config for all axes.
HMC5883L_MEAS_MODE_BIAS_NEG	Negative bias config for all axes.

Definition at line 76 of file hmc5883l.h.

◆ hmc5883l_op_mode_t

enum hmc5883l_op_mode_t

Operation modes.

Values correspond to bits <1:0> of HMC5883L_REG_MODE register

Enumerator
HMC5883L_OP_MODE_CONTINUOUS	Continuous measurement.
HMC5883L_OP_MODE_SINGLE	Single measurement.
HMC5883L_OP_MODE_IDLE	Idle mode.

Definition at line 99 of file hmc5883l.h.

Function Documentation

◆ hmc5883l_data_ready()

int hmc5883l_data_ready ( const hmc5883l_t * dev )

Data-ready status function.

The function checks the status register and returns

Parameters

[in] dev device descriptor of HMC5883L sensor

Return values

HMC5883L_OK	new data available
HMC5883L_ERROR_NO_DATA	no new data available
HMC5883L_ERROR_*	negative error code, see hmc5883l_error_codes_t

◆ hmc5883l_init()

int hmc5883l_init	(	hmc5883l_t *	dev,
		const hmc5883l_params_t *	params
	)

Initialize the HMC5883L sensor device.

This function resets the sensor and initializes the sensor according to given initialization parameters. All registers are reset to default values.

Parameters

[in]	dev	device descriptor of HMC5883L sensor to be initialized
[in]	params	HMC5883L initialization parameters

Return values

HMC5883L_OK	on success
HMC5883L_ERROR_*	a negative error code on error, see hmc5883l_error_codes_t

◆ hmc5883l_init_int()

int hmc5883l_init_int	(	hmc5883l_t *	dev,
		hmc5883l_drdy_int_cb_t	cb,
		void *	arg
	)

Initialize and activate the DRDY interrupt of HMC5883L sensor device.

This function activates the DRDY interrupt and initializes the pin defined as the interrupt pin in the initialization parameters of the device. The cb parameter specifies the function, along with an optional argument arg, which is called when a DRDY interrupt is triggered.

Warning: The given callback function cb is executed in interrupt context. Make sure not to call any driver API function in that context.

Note: This function is only available when module hmc5883l_int is enabled.

Parameters

[in]	dev	device descriptor of HMC5883L sensor
[in]	cb	function called when DRDY interrupt is triggered
[in]	arg	argument for the callback function

Return values

HMC5883L_OK	on success
HMC5883L_ERROR_*	a negative error code on error, see hmc5883l_error_codes_t

◆ hmc5883l_power_down()

int hmc5883l_power_down ( hmc5883l_t * dev )

Power down the sensor.

Changes the sensor operation mode to HMC5883L_OP_MODE_IDLE in which almost all internal blocks are switched off. I2C interface is still active. The content of the configuration registers is preserved.

Parameters

[in] dev Device descriptor of HMC5883L device to read from

Return values

HMC5883L_OK	on success
HMC5883L_ERROR_*	negative error code, see hmc5883l_error_codes_t

◆ hmc5883l_power_up()

int hmc5883l_power_up ( hmc5883l_t * dev )

Power up the sensor.

Swichtes the sensor back into the last active operation mode.

Parameters

[in] dev Device descriptor of HMC5883L device to read from

Return values

HMC5883L_OK	on success
HMC5883L_ERROR_*	negative error code, see hmc5883l_error_codes_t

◆ hmc5883l_read()

int hmc5883l_read	(	const hmc5883l_t *	dev,
		hmc5883l_data_t *	data
	)

Read one sample of magnetic field values in milli-Gauss (mGs)

Raw magnetometer data are read from the sensor and normalized them with respect to configured gain. Magnetic field values are given in milli-Gauss (mGs) to preserve full resolution:

Parameters

[in]	dev	device descriptor of HMC5883L sensor
[out]	data	result vector in milli-Gauss (mGs) per axis

Return values

HMC5883L_OK	on success
HMC5883L_ERROR_*	a negative error code on error, see hmc5883l_error_codes_t

◆ hmc5883l_read_raw()

int hmc5883l_read_raw	(	const hmc5883l_t *	dev,
		hmc5883l_raw_data_t *	raw
	)

Read one sample of raw sensor data as 16 bit two's complements.

Parameters

[in]	dev	device descriptor of HMC5883L sensor
	raw	raw data vector

Return values

HMC5883L_OK	on success
HMC5883L_ERROR_*	a negative error code on error, see hmc5883l_error_codes_t

Detailed Description

Files

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ hmc5883l_drdy_int_cb_t

Enumeration Type Documentation

◆ hmc5883l_dor_t

◆ hmc5883l_error_codes_t

◆ hmc5883l_gain_t

◆ hmc5883l_meas_avg_t

◆ hmc5883l_meas_mode_t

◆ hmc5883l_op_mode_t

Function Documentation

◆ hmc5883l_data_ready()

◆ hmc5883l_init()

◆ hmc5883l_init_int()

◆ hmc5883l_power_down()

◆ hmc5883l_power_up()

◆ hmc5883l_read()

◆ hmc5883l_read_raw()