Public Member Functions
	HMC5883L ()
	HMC5883L 3-axis digital magnetometer class object. More...

uint8_t	initialize (bool noConfig=false)

Vec3< int >	readRawValues (uint8_t *saturated=NULL)

Vec3< float >	readScaledValues (uint8_t *saturated=NULL)

Vec3< float >	readScaledValuesSingle (uint8_t *saturated=NULL, uint32_t max_retries=0, uint32_t delay_time=HMC_SLEEP_DELAY)

Vec3< float >	readCalibratedValues (uint8_t *saturated=NULL)

Vec3< float >	readCalibratedValuesSingle (uint8_t *saturated=NULL, uint32_t max_retries=0, float delay_time=HMC_SLEEP_DELAY)

Vec3< float >	getCalibration (bool update, uint8_t *saturated=NULL, uint32_t max_retries=0, float delay_time=HMC_SLEEP_DELAY)

Vec3< float >	runPosTest (uint8_t *saturated=NULL, uint32_t max_retries=0, float delay_time=HMC_SLEEP_DELAY)

Vec3< float >	runNegTest (uint8_t *saturated=NULL, uint32_t max_retries=0, float delay_time=HMC_SLEEP_DELAY)

uint8_t	getStatus (bool isLocked, bool isReady)

uint8_t	setGain (uint8_t gain_level)

uint8_t	setAveragingRate (uint8_t avg_rate)

uint8_t	setOutputRate (uint8_t out_rate)

uint8_t	setMeasurementMode (uint8_t mode)

uint8_t	setBiasMode (uint8_t mode)

uint8_t	setHighSpeedI2CMode (bool enabled)

uint8_t	getGain (bool updateCache=false)

uint8_t	getAveragingRate (bool updateCache=false)

uint8_t	getOutputRate (bool updateCache=false)

uint8_t	getMeasurementMode (bool updateCache=false)

uint8_t	getBiasMode (bool updateCache=false)

uint8_t	get_error_code (void)

Static Public Attributes
static const float	outputRates [] = {0.75, 1.50, 3.00, 7.50, 15.00, 30.00, 75.00}

static const float	gainRanges [] = {880, 1300, 1900, 2500, 4000, 4700, 5600, 8100}

Constructor & Destructor Documentation

HMC5883L::HMC5883L ( )

HMC5883L 3-axis digital magnetometer class object.

Constructor for HMC5883L compass / magnetometer class.

Member Function Documentation

uint8_t HMC5883L::getAveragingRate ( bool updateCache = false )

Retrieve the averaging rate

Retrieves the averaging rate that was set from setAveragingRate().

Parameters

[in] updateCache Boolean value, default false. If it evaluates as true, the gain level is retrieved from the device and cached in a private variable. Otherwise the value is retrieved from the cache.

Returns: Returns 0 on no error. Returns I2C errors from call to I2CDev.read_data() if updateCache is true. Otherwise no errors are returned.

uint8_t HMC5883L::getBiasMode ( bool updateCache = false )

Retrieve the bias mode setting from the device

Retrieves the bias mode that was set from setBiasMode().

Parameters

[in] updateCache Boolean value, default false. If it evaluates as true, the gain level is retrieved from the device and cached in a private variable. Otherwise the value is retrieved from the cache.

Returns: Returns 0 on no error. Returns I2C errors from call to I2CDev.read_data() if updateCache is true. Otherwise no errors are returned.

Vec3< float > HMC5883L::getCalibration	(	bool	update,
		uint8_t *	saturated = `NULL`,
		uint32_t	max_retries = `0`,
		float	delay_time = `HMC_SLEEP_DELAY`
	)

Runs a positive and negative bias test and sets the calibration from the average

Runs runPosTest(), then runNegTest() and averages the values, and sets the calibration.

Parameters

[in]	update	If evaluates to true, run the calibration and update the cache. Otherwise just returns the cached value.
[out]	*saturated	Warning flags in case any of the channels are saturated. Pass `NULL` if you don't want to read these out. Default value is `NULL`.
[in]	max_retries	The maximum number of times to try to read the measurement. Pass 0 if you don't want to limit the number of retries. Default is 0.
[in]	delay_time	Time to delay before checking whether or not data is ready to be read from the device (also the repetition delay between checks for whether data is ready), in milliseconds. The default is `HMC_SLEEP_DELAY`, which is 7 ms (6.25 ms = 160 Hz, the maximum data output rate of the device, rounded up). Any non-negative value is valid.

Returns: Returns the new calibration value. On error, returns (0, 0, 0) and sets err_code to the error.

uint8_t HMC5883L::getGain ( bool updateCache = false )

Retrieve the gain value

Retrieves the gain value level that was set from setGain().

Parameters

[in] updateCache Boolean value, default false. If it evaluates as true, the gain level is retrieved from the device and cached in a private variable. Otherwise the value is retrieved from the cache.

Returns: Returns 0 on no error. Returns I2C errors from call to I2CDev.read_data() if updateCache is true. Otherwise no errors are returned.

uint8_t HMC5883L::getMeasurementMode ( bool updateCache = false )

Retrieve the device's measurement mode

Retrieves the measurement mode that was set from setMeasurementMode(). If the cached mode is HMC_MeasurementSingle, the cache is always updated, irrespective of the value of updateCache, since the mode is set to HMC_MeasurementIdle when data is ready.

Parameters

[in] updateCache Boolean value, default false. If it evaluates as true, the gain level is retrieved from the device and cached in a private variable. Otherwise the value is retrieved from the cache.

Returns: Returns 0 on no error. Returns I2C errors from call to I2CDev.read_data() if updateCache is true. Otherwise no errors are returned.

uint8_t HMC5883L::getOutputRate ( bool updateCache = false )

Retrieve the data output rate in Continuous mode

Retrieves the data output rate that was set from setOutputRate().

Parameters

[in] updateCache Boolean value, default false. If it evaluates as true, the gain level is retrieved from the device and cached in a private variable. Otherwise the value is retrieved from the cache.

Returns: Returns 0 on no error. Returns I2C errors from call to I2CDev.read_data() if updateCache is true. Otherwise no errors are returned.

uint8_t HMC5883L::getStatus	(	bool *	isLocked,
		bool *	isReady
	)

Read the status register

Parameters

[out]	isLocked	Whether or not the status LOCK bit is set.
[out]	isReady	Whether or not the status RDY bit is set

Returns: Returns the value of the status register, or a value >= 4 on error (no valid status register values are > 3). On error, err_code is also set.

uint8_t HMC5883L::initialize ( bool noConfig = false )

Initialize the magnetometer communications.

Starts I2C communication with the HMC5883L magnetometer. This creates the Wire interface with the device. If the noConfig parameter is set to false (default), the magnetometer is also explicitly initialized with the device default values for the various configuration parameters:

Parameter	Default value
Gain	`[HMC_GAIN130]` 1090 LSb/Gauss (+/- 1.3 G sensor range)
Averaging rate	`[HMC_AVG1]` 1 point per sample
Data output rate	`[HMC_RATE1500]` 15 Hz
Measurement mode	`[HMC_MeasurementIdle]` Idle mode
Bias mode	`[HMC_BIAS_NONE]` No bias

If noConfig is set to true, this will request the values of some of the parameters already set, so as to ensure the accuracy of calls to functions such as getDelay(), which may use cached values for compass parameters.

Parameters

[in] noConfig Optional parameter. If specified true, explicitly initializes the device using default parameters.

Returns: Returns 0 on no error, or an error code. See HMC5883L_Errors.h for details.

Vec3< float > HMC5883L::readCalibratedValues ( uint8_t * saturated = NULL )

Return the field vector, scaled by the calibration, in milliGauss.

Makes a call to readScaledValues(), then scales the results by the calibration. By default, the calibration is (1.0, 1.0, 1.0). Make a call to getCalibration(true) to initialize the calibration.

Parameters

[out] *saturated Warning flags in case any of the channels are saturated. Pass NULL if you don't want to read these out. Default value is NULL.

Returns: Returns the value of readScaledValues(), scaled by the calibration, in mG. On error, returns (0, 0, 0) and sets the error code.

Vec3< float > HMC5883L::readCalibratedValuesSingle	(	uint8_t *	saturated = `NULL`,
		uint32_t	max_retries = `0`,
		float	delay_time = `HMC_SLEEP_DELAY`
	)

Return the field vector, scaled by the calibration, in milliGauss.

Makes a single call to readScaledValuesSingle(), then scales the results by the calibration stored in the HMC5883L object. By default, the calibration is (1.0, 1.0, 1.0). Make a call to getCalibration(true) to initialize the calibration.

Parameters

[out]	*saturated	Warning flags in case any of the channels are saturated. Pass `NULL` if you don't want to read these out. Default value is `NULL`.
[in]	max_retries	The maximum number of times to try to read the measurement. Pass 0 if you don't want to limit the number of retries. Default is 0.
[in]	delay_time	Time to delay before checking whether or not data is ready to be read from the device (also the repetition delay between checks for whether data is ready), in milliseconds. The default is `HMC_SLEEP_DELAY`, which is 7 ms (6.25 ms = 160 Hz, the maximum data output rate of the device, rounded up). Any non-negative value is valid.

Returns: Returns the value of readScaledValuesSingle(), scaled by the calibration, in mG. On error, returns (0, 0, 0) and sets the error code.

Vec3< int > HMC5883L::readRawValues ( uint8_t * saturated = NULL )

Read the raw values from the device

Values on the HMC5883L are stored in the 6 data registers, in two's complement form, with each axis stored as two 8-bit integers (big-endian). This reads the raw integer values from the registers. For data under- and overflows, the registers are set to -4096 - this is detected and indicated with the output parameter saturated.

Parameters

[out] saturated A warning code with flags WC_X_SATURATED, WC_Y_SATURATED and WC_Z_SATURATED indicating whether or not any of the channels has data under- or overflow.

Returns: Returns an integer 3-vector (x, y, z), or (0, 0, 0) on

Vec3< float > HMC5883L::readScaledValues ( uint8_t * saturated = NULL )

Read the field vector and return the value in milliGauss.

Scales the integers returned by readRawValues() by the appropriate gain value determined by the value set by setGain().

Parameters

[out] *saturated Warning flags in case any of the channels are saturated. Pass NULL if you don't want to read these out. Default value is NULL.

Returns: Returns a Vec3<float> containing the scaled values for the x, y and z channels or (0, 0, 0) on error.

Vec3< float > HMC5883L::readScaledValuesSingle	(	uint8_t *	saturated = `NULL`,
		uint32_t	max_retries = `0`,
		uint32_t	delay_time = `HMC_SLEEP_DELAY`
	)

Wrapper for readScaledValues() which makes a single measurement

The device is put into single measurement mode, then wait delay_time (in milliseconds), a single readScaledValues() measurement is made, then the measurement mode is restored to the initial mode.

Parameters

[out]	*saturated	Warning flags in case any of the channels are saturated. Pass `NULL` if you don't want to read these out. Default value is `NULL`.
[in]	max_retries	The maximum number of times to try to read the measurement. Pass 0 if you don't want to limit the number of retries. Default is 0.
[in]	delay_time	Time to delay before checking whether or not data is ready to be read from the device (also the repetition delay between checks for whether data is ready), in milliseconds. The default is `HMC_SLEEP_DELAY`, which is 7 ms (6.25 ms = 160 Hz, the maximum data output rate of the device, rounded up). Any non-negative value is valid.

Returns: Returns a Vec3<float> containing the scaled values for the x, y and z channels or (0, 0, 0) on error. In addition to errors returned from I2CDevice calls, this returns EC_INVALID_UFLOAT if a negative delay_time is passed.

Vec3< float > HMC5883L::runNegTest	(	uint8_t *	saturated = `NULL`,
		uint32_t	max_retries = `0`,
		float	delay_time = `HMC_SLEEP_DELAY`
	)

Runs the negative bias self-test

Sets the bias mode to HMC_BIAS_NEGATIVE, makes a measurement, then returns the bias mode to HMC_BIAS_NONE and returns the value of the measurement.

Returns: Returns the value of a negative-biased measurement. On error, returns (0, 0, 0) and sets err_code to the error.

Vec3< float > HMC5883L::runPosTest	(	uint8_t *	saturated = `NULL`,
		uint32_t	max_retries = `0`,
		float	delay_time = `HMC_SLEEP_DELAY`
	)

Runs the positive bias self-test

Sets the bias mode to HMC_BIAS_POSITIVE, makes a measurement, then returns the bias mode to HMC_BIAS_NONE and returns the value of the measurement.

Returns: Returns the value of a positive-biased measurement. On error, returns (0, 0, 0) and sets err_code to the error.

uint8_t HMC5883L::setAveragingRate ( uint8_t avg_rate )

Set the magnetometer averaging rate.

This is the number of averages composing each measurement. It sets bits 5 and 6 on Configuration Register A on the device.

Parameters

[in] avg_rate The averaging rate. The number of averages per measurement is 1<<avg_rate.

`avg_rate`	Value	Rate
`HMC_AVG1`	0	1
`HMC_AVG2`	1	2
`HMC_AVG4`	2	4
`HMC_AVG8`	3	8

Returns

Returns 0 on no error. Otherwise returns error code. Returns I2C errors from calls to read_data() and write_data(), as well as:

EC_INVALID_NAVG Returned if the number of averages is out of range.

uint8_t HMC5883L::setBiasMode ( uint8_t mode )

Sets the measurement bias mode (negative, positive or none).

The HMC5883L has a self-test mode which applies either a negative or positive bias field along all three channels; the mode is set in the bottom two bits of the Configuration Register A. The applied bias fields along all three axes are:

Axis	Bias-on field (mG)
X	±1160
Y	±1160
Z	±1080

In the negative and positive bias modes, each "measurement" consists of two measurements, a measurement with the bias field applied and one without, and the device returns the difference.

Parameters

[in] mode Valid bias modes are HMC_BIAS_NONE [0], HMC_BIAS_POSITIVE [1] and HMC_BIAS_NEGATIVE [2].

Returns: Returns 0 on no error. Returns I2C errors from calls to I2CDev.read_data() and I2CDev.write_data()

uint8_t HMC5883L::setGain ( uint8_t gain_level )

Set the magnetometer gain value.

Sets the magnetometer gain value, which determines the sensor range and the digital resolution. The gain level is bits 5-7 of Configuration Register B. The rest of configuration register B should be 0.

Parameters

[in] gain_level The gain setting, the values for which can be found in the following table:

`gain_level`	Value	Gain (LSB/G)	Range (G)	Resolution (mG / LSB)
`HMC_GAIN088`	0	1370	±0.88	0.73
`HMC_GAIN130`	1	1090	±1.30	0.92
`HMC_GAIN190`	2	820	±1.90	1.22
`HMC_GAIN250`	3	660	±2.50	1.52
`HMC_GAIN400`	4	440	±4.00	2.27
`HMC_GAIN470`	5	390	±4.70	2.56
`HMC_GAIN560`	6	330	±5.60	3.03
`HMC_GAIN810`	7	230	±8.10	4.35

Returns

Returns 0 on no error. Otherwise returns error code. Returns I2C errors from calls to write_data(), as well as:

EC_BAD_GAIN_LEVEL Returned if input gain level is out of range.

uint8_t HMC5883L::setHighSpeedI2CMode ( bool enabled )

Enable or disable High Speed I2C (3400 kHz)

Returns: Returns 0 on no error. returns I2C errors from calls to I2CDev.read_data() and I2CDev.write_data().

uint8_t HMC5883L::setMeasurementMode ( uint8_t mode )

Sets the measurement mode (Continuous, Single or Idle).

Measurement mode is the first two bits of the mode register. In continuous mode, data is output at the rate set by setOutputRate. In single measurement mode, a single measurement is made, the RDY pin is set high and mode is returned to idle. In single measurement mode, the approximate maximum data rate is 160 Hz. Idle is self-explanatory.

Parameters

[in] mode The measurement mode, HMC_MeasurementContinuous [0], HMC_MeasurementSingle [1], HMC_MeasurementIdle [2].

Returns

Returns 0 on no error. Returns I2C errors from calls to I2CDev.read_data() and I2CDev.write_data(), as well as:

EC_INVALID_MEASUREMENT_MODE Returned if the measurement mode is out of range.

uint8_t HMC5883L::setOutputRate ( uint8_t out_rate )

Sets the data output rate in continuous output mode.

Data output rate in continuous mode. Value is set in bits 2-4 of configuration register A.

Parameters

[in] out_rate The data output rate. Valid values are 0-6:

`out_rate`	Value	Rate (Hz)
`HMC_RATE0075`	0	0.75
`HMC_RATE0150`	1	1.50
`HMC_RATE0300`	2	3.00
`HMC_RATE0750`	3	7.50
`HMC_RATE1500`	4	15.00
`HMC_RATE3000`	5	30.00
`HMC_RATE7500`	6	75.00

Returns

Returns 0 on no error. Returns I2C errors from calls to I2CDev.read_data() and I2CDev.write_data(), as well as:

EC_INVALID_OUTRATE Returned if the output rate is out of range.

Member Data Documentation

const float HMC5883L::gainRanges = {880, 1300, 1900, 2500, 4000, 4700, 5600, 8100}

static

Saturation ranges in mG. See Gain settings

const float HMC5883L::outputRates = {0.75, 1.50, 3.00, 7.50, 15.00, 30.00, 75.00}

static

Output rates in Hz (see Output rate settings).

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation