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

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

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

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

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

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

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

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]devdevice descriptor of HMC5883L sensor
Return values
HMC5883L_OKnew data available
HMC5883L_ERROR_NO_DATAno 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]devdevice descriptor of HMC5883L sensor to be initialized
[in]paramsHMC5883L initialization parameters
Return values
HMC5883L_OKon 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]devdevice descriptor of HMC5883L sensor
[in]cbfunction called when DRDY interrupt is triggered
[in]argargument for the callback function
Return values
HMC5883L_OKon 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]devDevice descriptor of HMC5883L device to read from
Return values
HMC5883L_OKon 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]devDevice descriptor of HMC5883L device to read from
Return values
HMC5883L_OKon 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]devdevice descriptor of HMC5883L sensor
[out]dataresult vector in milli-Gauss (mGs) per axis
Return values
HMC5883L_OKon 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]devdevice descriptor of HMC5883L sensor
rawraw data vector
Return values
HMC5883L_OKon success
HMC5883L_ERROR_*a negative error code on error, see hmc5883l_error_codes_t