Honeywell HMC5883L 3-axis magnetometer.

This file contains functions for initializing and reading data from a Honeywell HMC5883L 3-axis magnetometer.

#include <string.h>
#include <math.h>
#include "hmc5883l.h"

Data Structures
struct	angle_t

struct	cal_data_t
	Sensor calibration data. More...

struct	hmc588l_axis_t
	HMC 5883l axis data format. More...

Macros
#define	CAL_OFFSETS_ADDR (0)

#define	CAL_SENSITIVITY_ADDR (0 + sizeof(vector3_t))

#define	DATA_OUTPUT_OVERFLOW ((int16_t)0xf000)

#define	READ_DELAY_MSEC (100) /* delay in msec between consecutive */

#define	SELF_TEST_DELAY_MSEC (250) /* delay in msec during self test */

Enumerations
enum	{ index_90uT, index_130uT, index_190uT, index_250uT, index_400uT, index_470uT, index_560uT, index_810uT }

enum	{ index_1hz, index_2hz, index_3hz, index_8hz, index_15hz, index_30hz, index_75hz }

Functions
static void	hmc5883l_apply_offset (vector3_t *input)
	Apply stored offset values to sensor reading. More...

static void	hmc5883l_apply_sensitivity (vector3_t *input)
	Apply stored sensitivity scaling factors to sensor reading. More...

static bool	hmc5883l_calibrate (sensor_t sensor, sensor_calibration_t calib_type, int step, void info)
	Calibrate magnetometer. More...

static bool	hmc5883l_device_id (sensor_hal_t hal, sensor_data_t data)
	Read magnetometer device ID. More...

static bool	hmc5883l_get_data (sensor_hal_t hal, vector3_t data)
	Read magnetometer vector data. More...

static bool	hmc5883l_get_field (sensor_hal_t hal, sensor_data_t data)
	Read magnetometer vector (3-axis) data. More...

static bool	hmc5883l_get_heading (sensor_hal_t hal, sensor_data_t data)
	Read magnetometer heading/direction data. More...

bool	hmc5883l_init (sensor_t *sensor, int resvd)
	Honeywell HMC5883L magnetometer driver initialization. More...

static bool	hmc5883l_ioctl (sensor_t sensor, sensor_command_t cmd, void arg)
	HMC5883L ioctl control entry point. More...

static bool	hmc5883l_read (sensor_t sensor, sensor_read_t type, sensor_data_t data)
	Read sensor data. More...

static bool	hmc5883l_selftest (sensor_t sensor, int test_code, void *arg)
	Perform self-test function. More...

static bool	hmc5883l_set_bandwidth (sensor_hal_t *hal, int16_t bw)
	Set the sample bandwidth for the magnetometer. More...

static bool	hmc5883l_set_range (sensor_hal_t *hal, int16_t range)
	Set the range for the magnetometer. More...

Variables
static const sensor_map_t	band_table []
	Honeywell HMC5883L Bandwidth Table (hertz, register value) More...

static cal_data_t	cal_data

static int	dev_range
	Current range index for device. More...

static const sensor_map_t	range_table []
	Honeywell HMC5883L Range Table (microtesla, register value) More...

static const int	scale_table []
	Honeywell HMC5883L Data Scaling Table (counts per milligauss) More...

#define CAL_OFFSETS_ADDR (0)

Todo:: Flash memory addresses should be configurable.

Referenced by hmc5883l_calibrate().

#define CAL_SENSITIVITY_ADDR (0 + sizeof(vector3_t))

Referenced by hmc5883l_calibrate().

#define DATA_OUTPUT_OVERFLOW ((int16_t)0xf000)

Referenced by hmc5883l_get_data().

#define READ_DELAY_MSEC (100) /* delay in msec between consecutive */

Referenced by hmc5883l_calibrate().

#define SELF_TEST_DELAY_MSEC (250) /* delay in msec during self test */

Referenced by hmc5883l_selftest().

anonymous enum

Enumerator
index_90uT
index_130uT
index_190uT
index_250uT
index_400uT
index_470uT
index_560uT
index_810uT

anonymous enum

Enumerator
index_1hz
index_2hz
index_3hz
index_8hz
index_15hz
index_30hz
index_75hz

static void hmc5883l_apply_offset ( vector3_t * input )

static

Apply stored offset values to sensor reading.

This function applies stored calibration offsets to the "input" vector of magnetometer values (the magnetic field vector) and returns the modified values. The offsets are calculated based on sensitivity-adjusted readings, so this function should be used after the values that have been adjusted using hmc5883l_apply_sensitivity().

Parameters

input Contains the measured magnetic field values, adjusted for sensitivity. The offset-adjusted values will replace the contents.

Return values

true	successfully adjusted sensor readings
false	Failed to adjust sensor readings

References cal_data_t::offsets, vector3_t::x, vector3_t::y, and vector3_t::z.

Referenced by hmc5883l_get_field(), and hmc5883l_get_heading().

static void hmc5883l_apply_sensitivity ( vector3_t * input )

static

Apply stored sensitivity scaling factors to sensor reading.

This function applies stored sensitivity scaling to the "input" vector of magnetometer values (the magnetic field vector) and returns the modified values.

Parameters

input Contains the measured magnetic field values. The sensitivty-adjusted values will replace the contents.

Return values

true	successfully adjusted sensor readings
false	Failed to adjust sensor readings

References cal_data_t::sensitivity, vector3_t::x, vector3_t::y, and vector3_t::z.

Referenced by hmc5883l_calibrate(), hmc5883l_get_field(), and hmc5883l_get_heading().

bool hmc5883l_calibrate	(	sensor_t *	sensor,
		sensor_calibration_t	calib_type,
		int	step,
		void *	info
	)

static

Calibrate magnetometer.

This function measures the magnetometer output if 3 different device orientations, calculates average offset values, and stores these offsets in non-volatile memory. The offsets will later be used during normal measurements, to compensate for fixed magnetic effects.

This routine must be called 3 times total, with the "step" parameter indicating what stage of the calibration is being performed. This multi-step mechanism allows the application to prompt for physical placement of the sensor device before this routine is called.

Parameters

sensor	Address of an initialized sensor descriptor.
data	The address of a vector storing sensor axis data.
step	The calibration stage number (1 to 3).
info	Unimplemented (ignored) parameter.

Returns: bool true if the call succeeds, else false is returned.

References sensor_data_t::axis, CAL_OFFSETS_ADDR, CAL_SENSITIVITY_ADDR, delay_ms, dummy_data, sensor_desc::err, sensor_desc::hal, hmc5883l_apply_sensitivity(), hmc5883l_get_data(), hmc5883l_selftest(), HMC5883L_TEST_X_NORM, HMC5883L_TEST_Y_NORM, HMC5883L_TEST_Z_NORM, MANUAL_CALIBRATE, nvram_read(), nvram_write(), cal_data_t::offsets, READ_DELAY_MSEC, cal_data_t::sensitivity, SENSOR_ERR_IO, SENSOR_TEST_BIAS_POS, SENSOR_TEST_ERR_NONE, vector3_t::x, vector3_t::y, and vector3_t::z.

Referenced by hmc5883l_init().

static bool hmc5883l_device_id	(	sensor_hal_t *	hal,
		sensor_data_t *	data
	)

static

Read magnetometer device ID.

This function reads the magnetometer hardware identification registers and returns these values to the addresses specified in the function parameters.

Parameters

hal	Address of an initialized sensor hardware descriptor.
data	Address of sensor_data_t structure to return values.

Returns: bool true if the call succeeds, else false is returned.

References cpu_to_be32, sensor_data_t::device, HMC5883L_ID_REG_A, and sensor_bus_read.

Referenced by hmc5883l_init(), and hmc5883l_read().

static bool hmc5883l_get_data	(	sensor_hal_t *	hal,
		vector3_t *	data
	)

static

Read magnetometer vector data.

This function obtains magnetometer data for all three axes of the Honeywell device. The data is read from six device registers using a multi-byte bus transfer. The 13-bit raw results are then assembled from the two register values for each axis, including extending the sign bit, to form a signed 16-bit value.

Parameters

hal	Address of an initialized sensor hardware descriptor.
data	The address of a vector storing sensor axis data.

Returns: bool true if the call succeeds, else false is returned.

References sensor_axis_vec_t::axis, DATA_OUTPUT_OVERFLOW, gpio_pin_is_low, HMC5883L_MAG_X_HI, HMC5883L_MODE_REG, hmc588l_axis_t::lsb, sensor_hal::mcu_sigint, MODE_SINGLE, orient, sensor_hal::orientation, sensor_bus_put, sensor_bus_read, sensor_axis_vec_t::sign, vector3_t::x, sensor_orient_t::x, vector3_t::y, sensor_orient_t::y, vector3_t::z, and sensor_orient_t::z.

Referenced by hmc5883l_calibrate(), hmc5883l_get_field(), hmc5883l_get_heading(), and hmc5883l_selftest().

static bool hmc5883l_get_field	(	sensor_hal_t *	hal,
		sensor_data_t *	data
	)

static

Read magnetometer vector (3-axis) data.

This function obtains magnetometer data for all three axes of the Honeywell device. The data is read from six device registers using a multi-byte bus transfer. The 10-bit raw results are then assembled from the two register values for each axis, including extending the sign bit, to form a signed 32-bit value.

Along with the actual sensor data, the LSB byte contains a "new" flag indicating if the data for this axis has been updated since the last time the axis data was read. Reading either LSB or MSB data will clear this flag.

Parameters

hal	Address of an initialized sensor device descriptor.
data	The address of a vector storing sensor axis data.

Returns: bool true if the call succeeds, else false is returned.

References sensor_data_t::axis, dev_range, GAUSS_TO_MICRO_TESLA, hmc5883l_apply_offset(), hmc5883l_apply_sensitivity(), hmc5883l_get_data(), scale_table, sensor_data_t::scaled, vector3_scale(), vector3_t::x, vector3_t::y, and vector3_t::z.

Referenced by hmc5883l_read().

static bool hmc5883l_get_heading	(	sensor_hal_t *	hal,
		sensor_data_t *	data
	)

static

Read magnetometer heading/direction data.

This function obtains magnetometer data for all three axes of the Honeywell device. The data is read from six device registers using a multi-byte bus transfer. The 10-bit raw results are then assembled from the two register values for each axis, including extending the sign bit, to form a signed 32-bit value.

Along with the actual sensor data, the LSB byte contains a "new" flag indicating if the data for this axis has been updated since the last time the axis data was read. Reading either LSB or MSB data will clear this flag.

Parameters

hal	Address of an initialized sensor device descriptor.
data	The address of a vector storing sensor axis data.

Returns: bool true if the call succeeds, else false is returned.

References dev_range, field_direction(), GAUSS_TO_MICRO_TESLA, sensor_data_t::heading, hmc5883l_apply_offset(), hmc5883l_apply_sensitivity(), hmc5883l_get_data(), and scale_table.

Referenced by hmc5883l_read().

bool hmc5883l_init	(	sensor_t *	sensor,
		int	resvd
	)

Honeywell HMC5883L magnetometer driver initialization.

This is the main initialization function for the HMC5883L device.

Parameters

sensor	Address of a sensor device descriptor.
resvd	Reserved value.

Returns: bool true if the call succeeds, else false is returned.

References sensor_hal::bandwidth, sensor_map_t::bandwidth_Hz, sensor_hal::bus, data, DATA_RATE_15HZ, sensor_data_t::device, sensor_desc::drv, sensor_device_t::func, sensor_desc::hal, hmc5883l_calibrate(), HMC5883L_CONFIG_REG_A, HMC5883L_DATA_RESOLUTION, HMC5883L_DEV_ID, hmc5883l_device_id(), hmc5883l_ioctl(), HMC5883L_MODE_REG, hmc5883l_read(), hmc5883l_selftest(), hmc5883l_set_bandwidth(), hmc5883l_set_range(), index_130uT, index_15hz, MEAS_MODE_NORM, MODE_CONTIN, nvram_read(), cal_data_t::offsets, sensor_hal::range, sensor_map_t::range_units, sensor_funcs_t::read, sensor_hal::resolution, sensor_bus_put, SENSOR_CAPS_3_AXIS, SENSOR_CAPS_SELFTEST, SENSOR_SCALE_micro, SENSOR_UNITS_tesla, SENSOR_VENDOR_HONEYWELL, status, bus_desc_t::status, STATUS_OK, vector3_t::x, vector3_t::y, and vector3_t::z.

static bool hmc5883l_ioctl	(	sensor_t *	sensor,
		sensor_command_t	cmd,
		void *	arg
	)

static

HMC5883L ioctl control entry point.

Parameters

sensor	Address of an initialized sensor descriptor.
cmd	Command to execute
arg	Argument for command (varies)

Returns: bool true if the call succeeds, else false is returned.

References sensor_desc::err, sensor_desc::hal, hmc5883l_set_bandwidth(), hmc5883l_set_range(), SENSOR_ERR_UNSUPPORTED, SENSOR_SET_BANDWIDTH, SENSOR_SET_RANGE, and status.

Referenced by hmc5883l_init().

static bool hmc5883l_read	(	sensor_t *	sensor,
		sensor_read_t	type,
		sensor_data_t *	data
	)

static

Read sensor data.

This routine calls the appropriate internal data function to obtain the specified type of data from the sensor device.

Parameters

sensor	Address of an initialized sensor device descriptor.
type	Type of sensor data to read.
data	The address where data values are returned.

Returns: bool true if the call succeeds, else false is returned.

References sensor_desc::err, sensor_desc::hal, hmc5883l_device_id(), hmc5883l_get_field(), hmc5883l_get_heading(), SENSOR_ERR_FUNCTION, SENSOR_READ_FIELD, SENSOR_READ_HEADING, and SENSOR_READ_ID.

Referenced by hmc5883l_init().

bool hmc5883l_selftest	(	sensor_t *	sensor,
		int *	test_code,
		void *	arg
	)

static

Perform self-test function.

This function sets up and executes an built-in self test function within the HMC5883L device.

Parameters

sensor	Address of an initialized sensor descriptor.
test_code	Address of a numeric code of which test to perform This location will contain the specific test result code when the function returns.

Returns: bool true if the call succeeds, else false is returned.

References data, DATA_RATE_15HZ, delay_ms, sensor_desc::hal, HMC5883L_CONFIG_REG_A, HMC5883L_CONFIG_REG_B, hmc5883l_get_data(), HMC5883L_MODE_REG, HMC5883L_TEST_GAIN, HMC5883L_TEST_X_MAX, HMC5883L_TEST_X_MIN, HMC5883L_TEST_Y_MAX, HMC5883L_TEST_Y_MIN, HMC5883L_TEST_Z_MAX, HMC5883L_TEST_Z_MIN, MEAS_AVG_1, MEAS_MODE_NEG, MEAS_MODE_POS, MODE_SINGLE, SELF_TEST_DELAY_MSEC, sensor_bus_put, sensor_bus_read, sensor_bus_write, SENSOR_TEST_BIAS_NEG, SENSOR_TEST_BIAS_POS, SENSOR_TEST_DEFAULT, SENSOR_TEST_ERR_FUNCTION, SENSOR_TEST_ERR_NONE, SENSOR_TEST_ERR_RANGE, SENSOR_TEST_ERR_READ, SENSOR_TEST_ERR_WRITE, status, vector3_t::x, vector3_t::y, and vector3_t::z.

Referenced by hmc5883l_calibrate(), and hmc5883l_init().

static bool hmc5883l_set_bandwidth	(	sensor_hal_t *	hal,
		int16_t	bw
	)

static

Set the sample bandwidth for the magnetometer.

Parameters

hal	Address of an initialized sensor hardware descriptor.
band	The index of a driver-specific bandwidth table entry.

Returns: bool true if the call succeeds, else false is returned.

References DATA_RATE, HMC5883L_CONFIG_REG_A, sensor_bus_get, and sensor_bus_put.

Referenced by hmc5883l_init(), and hmc5883l_ioctl().

static bool hmc5883l_set_range	(	sensor_hal_t *	hal,
		int16_t	range
	)

static

Set the range for the magnetometer.

Parameters

hal	Address of an initialized sensor hardware descriptor.
range	The index of a driver-specific range table entry.

Returns: bool true if the call succeeds, else false is returned.

References dev_range, HMC5883L_CONFIG_REG_B, and sensor_bus_put.

Referenced by hmc5883l_init(), and hmc5883l_ioctl().

const sensor_map_t band_table[]

static

Initial value:

= {
    {{1}, DATA_RATE_0_75HZ},  
    {{2}, DATA_RATE_1_5HZ},   
    {{3}, DATA_RATE_3HZ},
    {{8}, DATA_RATE_7_5HZ},   
    {{15}, DATA_RATE_15HZ},
    {{30}, DATA_RATE_30HZ},
    {{75}, DATA_RATE_75HZ},
}

Honeywell HMC5883L Bandwidth Table (hertz, register value)

cal_data_t cal_data

static

int dev_range

static

Current range index for device.

Referenced by hmc5883l_get_field(), hmc5883l_get_heading(), and hmc5883l_set_range().

const sensor_map_t range_table[]

static

Initial value:

= {
    {{90}, GAIN_0_9GA},  
    {{130}, GAIN_1_3GA}, 
    {{190}, GAIN_1_9GA}, 
    {{250}, GAIN_2_5GA}, 
    {{400}, GAIN_4_0GA}, 
    {{470}, GAIN_4_7GA}, 
    {{560}, GAIN_5_6GA}, 
    {{810}, GAIN_8_1GA}, 
}

Honeywell HMC5883L Range Table (microtesla, register value)

const int scale_table[]

static

Initial value:

= {
    SCALE_0_9GA,        
    SCALE_1_3GA,        
    SCALE_1_9GA,        
    SCALE_2_5GA,        
    SCALE_4_0GA,        
    SCALE_4_7GA,        
    SCALE_5_6GA,        
    SCALE_8_1GA         
}

Honeywell HMC5883L Data Scaling Table (counts per milligauss)

Referenced by hmc5883l_get_field(), and hmc5883l_get_heading().

Microchip® Advanced Software Framework

Data Structures

Macros

Enumerations

Functions

Variables