hmc5883l - Driver for HMC5883L 3-axis digital compass

group hmc5883l

ESP-IDF Driver for 3-axis digital compass HMC5883L.

Ported from esp-open-rtos

Copyright (C) 2016, 2018 Ruslan V. Uss unclerus@gmail.com

BSD Licensed as described in the file LICENSE

Defines

HMC5883L_ADDR

I2C address.

HMC5883L_ID

Chip ID, “H43”.

Enums

enum hmc5883l_opmode_t

Device operating mode.

Values:

enumerator HMC5883L_MODE_CONTINUOUS

Continuous mode.

enumerator HMC5883L_MODE_SINGLE

Single measurement mode, default.

enum hmc5883l_samples_averaged_t

Number of samples averaged per measurement.

Values:

enumerator HMC5883L_SAMPLES_1

1 sample, default

enumerator HMC5883L_SAMPLES_2

2 samples

enumerator HMC5883L_SAMPLES_4

4 samples

enumerator HMC5883L_SAMPLES_8

8 samples

enum hmc5883l_data_rate_t

Data output rate in continuous measurement mode.

Values:

enumerator HMC5883L_DATA_RATE_00_75

0.75 Hz

enumerator HMC5883L_DATA_RATE_01_50

1.5 Hz

enumerator HMC5883L_DATA_RATE_03_00

3 Hz

enumerator HMC5883L_DATA_RATE_07_50

7.5 Hz

enumerator HMC5883L_DATA_RATE_15_00

15 Hz, default

enumerator HMC5883L_DATA_RATE_30_00

30 Hz

enumerator HMC5883L_DATA_RATE_75_00

75 Hz

enum hmc5883l_bias_t

Measurement mode of the device (bias)

Values:

enumerator HMC5883L_BIAS_NORMAL

Default flow, no bias.

enumerator HMC5883L_BIAS_POSITIVE

Positive bias configuration all axes, used for self test (see datasheet)

enumerator HMC5883L_BIAS_NEGATIVE

Negative bias configuration all axes, used for self test (see datasheet)

enum hmc5883l_gain_t

Device gain.

Values:

enumerator HMC5883L_GAIN_1370

0.73 mG/LSb, range -0.88..+0.88 G

enumerator HMC5883L_GAIN_1090

0.92 mG/LSb, range -1.3..+1.3 G, default

enumerator HMC5883L_GAIN_820

1.22 mG/LSb, range -1.9..+1.9 G

enumerator HMC5883L_GAIN_660

1.52 mG/LSb, range -2.5..+2.5 G

enumerator HMC5883L_GAIN_440

2.27 mG/LSb, range -4.0..+4.0 G

enumerator HMC5883L_GAIN_390

2.56 mG/LSb, range -4.7..+4.7 G

enumerator HMC5883L_GAIN_330

3.03 mG/LSb, range -5.6..+5.6 G

enumerator HMC5883L_GAIN_230

4.35 mG/LSb, range -8.1..+8.1 G

Functions

esp_err_t hmc5883l_init_desc(hmc5883l_dev_t *dev, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)

Initialize device descriptor.

Parameters
  • dev – Device descriptor

  • port – I2C port number

  • sda_gpio – GPIO pin number for SDA

  • scl_gpio – GPIO pin number for SCL

Returns

ESP_OK on success

esp_err_t hmc5883l_free_desc(hmc5883l_dev_t *dev)

Free device descriptor.

Parameters

dev – Device descriptor

Returns

ESP_OK on success

esp_err_t hmc5883l_init(hmc5883l_dev_t *dev)

Initialize device.

Parameters

dev – Device descriptor

Returns

ESP_OK on success

esp_err_t hmc5883l_get_opmode(hmc5883l_dev_t *dev, hmc5883l_opmode_t *val)

Get operating mode.

Parameters
  • dev – Device descriptor

  • [out] val – Operating mode

Returns

ESP_OK on success

esp_err_t hmc5883l_set_opmode(hmc5883l_dev_t *dev, hmc5883l_opmode_t mode)

Set operating mode.

Parameters
  • dev – Device descriptor

  • mode – Operating mode

Returns

ESP_OK on success

esp_err_t hmc5883l_get_samples_averaged(hmc5883l_dev_t *dev, hmc5883l_samples_averaged_t *val)

Get number of samples averaged per measurement output.

Parameters
  • dev – Device descriptor

  • [out] val – Number of samples

Returns

ESP_OK on success

esp_err_t hmc5883l_set_samples_averaged(hmc5883l_dev_t *dev, hmc5883l_samples_averaged_t samples)

Set number of samples averaged per measurement output.

Parameters
  • dev – Device descriptor

  • samples – Number of samples

Returns

ESP_OK on success

esp_err_t hmc5883l_get_data_rate(hmc5883l_dev_t *dev, hmc5883l_data_rate_t *val)

Get data output rate in continuous measurement mode.

Parameters
  • dev – Device descriptor

  • [out] val – Data output rate

Returns

ESP_OK on success

esp_err_t hmc5883l_set_data_rate(hmc5883l_dev_t *dev, hmc5883l_data_rate_t rate)

Set data output rate in continuous measurement mode.

Parameters
  • dev – Device descriptor

  • rate – Data output rate

Returns

ESP_OK on success

esp_err_t hmc5883l_get_bias(hmc5883l_dev_t *dev, hmc5883l_bias_t *val)

Get measurement mode (bias of the axes)

See datasheet for self test description.

Parameters
  • dev – Device descriptor

  • [out] val – Bias

Returns

ESP_OK on success

esp_err_t hmc5883l_set_bias(hmc5883l_dev_t *dev, hmc5883l_bias_t bias)

Set measurement mode (bias of the axes)

See datasheet for self test description.

Parameters
  • dev – Device descriptor

  • bias – Bias

Returns

ESP_OK on success

esp_err_t hmc5883l_get_gain(hmc5883l_dev_t *dev, hmc5883l_gain_t *val)

Get device gain.

Parameters
  • dev – Device descriptor

  • [out] val – Current gain

Returns

ESP_OK on success

esp_err_t hmc5883l_set_gain(hmc5883l_dev_t *dev, hmc5883l_gain_t gain)

Set device gain.

Parameters
  • dev – Device descriptor

  • gain – Gain

Returns

ESP_OK on success

esp_err_t hmc5883l_data_is_ready(hmc5883l_dev_t *dev, bool *val)

Get data state.

Parameters
  • dev – Device descriptor

  • [out] val – true when data is written to all six data registers

Returns

ESP_OK on success

esp_err_t hmc5883l_data_is_locked(hmc5883l_dev_t *dev, bool *val)

Get lock state.

If data is locked, any new data will not be placed in data registers until one of these conditions are met:

  • data have been read,

  • operating mode is changed,

  • the measurement configuration (bias) is changed,

  • power is reset.

Parameters
  • dev – Device descriptor

  • [out] val – true when data registers is locked

Returns

ESP_OK on success

esp_err_t hmc5883l_get_raw_data(hmc5883l_dev_t *dev, hmc5883l_raw_data_t *data)

Get raw magnetic data.

Parameters
  • dev – Device descriptor

  • [out] data – Raw data

Returns

ESP_OK on success

esp_err_t hmc5883l_raw_to_mg(const hmc5883l_dev_t *dev, const hmc5883l_raw_data_t *raw, hmc5883l_data_t *mg)

Convert raw magnetic data to milligausses.

Parameters
  • dev – Device descriptor

  • raw – Source raw data

  • [out] mg – Converted data

esp_err_t hmc5883l_get_data(hmc5883l_dev_t *dev, hmc5883l_data_t *data)

Get magnetic data in milligausses.

Parameters
  • dev – Device descriptor

  • [out] data – Magnetic data

Returns

ESP_OK on success

struct hmc5883l_dev_t
#include <hmc5883l.h>

Device descriptor.

struct hmc5883l_raw_data_t
#include <hmc5883l.h>

Raw measurement result.

struct hmc5883l_data_t
#include <hmc5883l.h>

Measurement result, milligauss.