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.

Return

ESP_OK on success

Parameters
  • dev: Pointer to device descriptor

  • port: I2C port number

  • sda_gpio: GPIO pin number for SDA

  • scl_gpio: GPIO pin number for SCL

esp_err_t hmc5883l_free_desc(hmc5883l_dev_t *dev)

Free device descriptor.

Return

ESP_OK on success

Parameters
  • dev: Pointer to device descriptor

esp_err_t hmc5883l_init(hmc5883l_dev_t *dev)

Init device.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

esp_err_t hmc5883l_get_opmode(hmc5883l_dev_t *dev, hmc5883l_opmode_t *val)

Get operating mode.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • val: Measurement mode

esp_err_t hmc5883l_set_opmode(hmc5883l_dev_t *dev, hmc5883l_opmode_t mode)

Set operating mode.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • mode: Measurement mode

esp_err_t hmc5883l_get_samples_averaged(hmc5883l_dev_t *dev, hmc5883l_samples_averaged_t *val)

Get number of samples averaged per measurement output.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • val: Number of samples

esp_err_t hmc5883l_set_samples_averaged(hmc5883l_dev_t *dev, hmc5883l_samples_averaged_t samples)

Set number of samples averaged per measurement output.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • samples: Number of samples

esp_err_t hmc5883l_get_data_rate(hmc5883l_dev_t *dev, hmc5883l_data_rate_t *val)

Get data output rate in continuous measurement mode.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • val: Data output rate

esp_err_t hmc5883l_set_data_rate(hmc5883l_dev_t *dev, hmc5883l_data_rate_t rate)

Set data output rate in continuous measurement mode.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • rate: Data output rate

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.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • val: Bias

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.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • bias: Bias

esp_err_t hmc5883l_get_gain(hmc5883l_dev_t *dev, hmc5883l_gain_t *val)

Get device gain.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • val: Current gain

esp_err_t hmc5883l_set_gain(hmc5883l_dev_t *dev, hmc5883l_gain_t gain)

Set device gain.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • gain: Gain

esp_err_t hmc5883l_data_is_ready(hmc5883l_dev_t *dev, bool *val)

Get data state.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

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

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:

  1. data have been read,

  2. operating mode is changed,

  3. the measurement configuration (bias) is changed,

  4. power is reset.

    Return

    ESP_OK on success

    Parameters
    • dev: Device descriptor

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

esp_err_t hmc5883l_get_raw_data(hmc5883l_dev_t *dev, hmc5883l_raw_data_t *data)

Get raw magnetic data.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • data: Pointer to the struct to write raw data

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: Pointer to source raw data struct

  • mg: Pointer to target struct to write converted data

esp_err_t hmc5883l_get_data(hmc5883l_dev_t *dev, hmc5883l_data_t *data)

Get magnetic data in milligausses.

Return

ESP_OK on success

Parameters
  • dev: Device descriptor

  • data: Pointer to the struct to write data

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.