HMC5883L Class Reference

Public Member Functions
	HMC5883L ()
	HMC5883L (uint8_t address)
void	initialize ()
bool	testConnection ()
uint8_t	getSampleAveraging ()
void	setSampleAveraging (uint8_t averaging)
uint8_t	getDataRate ()
void	setDataRate (uint8_t rate)
uint8_t	getMeasurementBias ()
void	setMeasurementBias (uint8_t bias)
uint8_t	getGain ()
void	setGain (uint8_t gain)
uint8_t	getMode ()
void	setMode (uint8_t mode)
void	getHeading (int16_t *x, int16_t *y, int16_t *z)
int16_t	getHeadingX ()
int16_t	getHeadingY ()
int16_t	getHeadingZ ()
bool	getLockStatus ()
bool	getReadyStatus ()
uint8_t	getIDA ()
uint8_t	getIDB ()
uint8_t	getIDC ()

---

Constructor & Destructor Documentation

HMC5883L::HMC5883L

(

)

Default constructor, uses default I2C address.

See also:

HMC5883L_DEFAULT_ADDRESS

HMC5883L::HMC5883L

(

uint8_t

address

)

Specific address constructor.

Parameters:

address

I2C address

See also:

HMC5883L_DEFAULT_ADDRESS

HMC5883L_ADDRESS

---

Member Function Documentation

uint8_t HMC5883L::getDataRate

(

)

Get data output rate value. The Table below shows all selectable output rates in continuous measurement mode. All three channels shall be measured within a given output rate. Other output rates with maximum rate of 160 Hz can be achieved by monitoring DRDY interrupt pin in single measurement mode.

Value | Typical Data Output Rate (Hz) ------+------------------------------ 0 | 0.75 1 | 1.5 2 | 3 3 | 7.5 4 | 15 (Default) 5 | 30 6 | 75 7 | Not used

Returns:

Current rate of data output to registers

See also:

HMC5883L_RATE_15

HMC5883L_RA_CONFIG_A

HMC5883L_CRA_RATE_BIT

HMC5883L_CRA_RATE_LENGTH

uint8_t HMC5883L::getGain

(

)

Get magnetic field gain value. The table below shows nominal gain settings. Use the "Gain" column to convert counts to Gauss. Choose a lower gain value (higher GN#) when total field strength causes overflow in one of the data output registers (saturation). The data output range for all settings is 0xF800-0x07FF (-2048 - 2047).

Value | Field Range | Gain (LSB/Gauss) ------+-------------+----------------- 0 | +/- 0.88 Ga | 1370 1 | +/- 1.3 Ga | 1090 (Default) 2 | +/- 1.9 Ga | 820 3 | +/- 2.5 Ga | 660 4 | +/- 4.0 Ga | 440 5 | +/- 4.7 Ga | 390 6 | +/- 5.6 Ga | 330 7 | +/- 8.1 Ga | 230

Returns:

Current magnetic field gain value

See also:

HMC5883L_GAIN_1090

HMC5883L_RA_CONFIG_B

HMC5883L_CRB_GAIN_BIT

HMC5883L_CRB_GAIN_LENGTH

void HMC5883L::getHeading	(	int16_t *	x,
		int16_t *	y,
		int16_t *	z
	)

Get 3-axis heading measurements. In the event the ADC reading overflows or underflows for the given channel, or if there is a math overflow during the bias measurement, this data register will contain the value -4096. This register value will clear when after the next valid measurement is made. Note that this method automatically clears the appropriate bit in the MODE register if Single mode is active.

Parameters:

x	16-bit signed integer container for X-axis heading
y	16-bit signed integer container for Y-axis heading
z	16-bit signed integer container for Z-axis heading

See also:

HMC5883L_RA_DATAX_H

int16_t HMC5883L::getHeadingX

(

)

Get X-axis heading measurement.

Returns:

16-bit signed integer with X-axis heading

See also:

HMC5883L_RA_DATAX_H

int16_t HMC5883L::getHeadingY

(

)

Get Y-axis heading measurement.

Returns:

16-bit signed integer with Y-axis heading

See also:

HMC5883L_RA_DATAY_H

int16_t HMC5883L::getHeadingZ

(

)

Get Z-axis heading measurement.

Returns:

16-bit signed integer with Z-axis heading

See also:

HMC5883L_RA_DATAZ_H

uint8_t HMC5883L::getIDA

(

)

Get identification byte A

Returns:

ID_A byte (should be 01001000, ASCII value 'H')

uint8_t HMC5883L::getIDB

(

)

Get identification byte B

Returns:

ID_A byte (should be 00110100, ASCII value '4')

uint8_t HMC5883L::getIDC

(

)

Get identification byte C

Returns:

ID_A byte (should be 00110011, ASCII value '3')

bool HMC5883L::getLockStatus

(

)

Get data output register lock status. This bit is set when this some but not all for of the six data output registers have been read. When this bit is set, the six data output registers are locked and any new data will not be placed in these register until one of three conditions are met: one, all six bytes have been read or the mode changed, two, the mode is changed, or three, the measurement configuration is changed.

Returns:

Data output register lock status

See also:

HMC5883L_RA_STATUS

HMC5883L_STATUS_LOCK_BIT

uint8_t HMC5883L::getMeasurementBias

(

)

Get measurement bias value.

Returns:

Current bias value (0-2 for normal/positive/negative respectively)

See also:

HMC5883L_BIAS_NORMAL

HMC5883L_RA_CONFIG_A

HMC5883L_CRA_BIAS_BIT

HMC5883L_CRA_BIAS_LENGTH

uint8_t HMC5883L::getMode

(

)

Get measurement mode. In continuous-measurement mode, the device continuously performs measurements and places the result in the data register. RDY goes high when new data is placed in all three registers. After a power-on or a write to the mode or configuration register, the first measurement set is available from all three data output registers after a period of 2/fDO and subsequent measurements are available at a frequency of fDO, where fDO is the frequency of data output.

When single-measurement mode (default) is selected, device performs a single measurement, sets RDY high and returned to idle mode. Mode register returns to idle mode bit values. The measurement remains in the data output register and RDY remains high until the data output register is read or another measurement is performed.

Returns:

Current measurement mode

See also:

HMC5883L_MODE_CONTINUOUS

HMC5883L_MODE_SINGLE

HMC5883L_MODE_IDLE

HMC5883L_RA_MODE

HMC5883L_MODEREG_BIT

HMC5883L_MODEREG_LENGTH

bool HMC5883L::getReadyStatus

(

)

Get data ready status. This bit is set when data is written to all six data registers, and cleared when the device initiates a write to the data output registers and after one or more of the data output registers are written to. When RDY bit is clear it shall remain cleared for 250 us. DRDY pin can be used as an alternative to the status register for monitoring the device for measurement data.

Returns:

Data ready status

See also:

HMC5883L_RA_STATUS

HMC5883L_STATUS_READY_BIT

uint8_t HMC5883L::getSampleAveraging

(

)

Get number of samples averaged per measurement.

Returns:

Current samples averaged per measurement (0-3 for 1/2/4/8 respectively)

See also:

HMC5883L_AVERAGING_8

HMC5883L_RA_CONFIG_A

HMC5883L_CRA_AVERAGE_BIT

HMC5883L_CRA_AVERAGE_LENGTH

void HMC5883L::initialize

(

)

Power on and prepare for general usage. This will prepare the magnetometer with default settings, ready for single- use mode (very low power requirements). Default settings include 8-sample averaging, 15 Hz data output rate, normal measurement bias, a,d 1090 gain (in terms of LSB/Gauss). Be sure to adjust any settings you need specifically after initialization, especially the gain settings if you happen to be seeing a lot of -4096 values (see the datasheet for mor information).

void HMC5883L::setDataRate

(

uint8_t

rate

)

Set data output rate value.

Parameters:

rate	Rate of data output to registers

See also:

getDataRate()

HMC5883L_RATE_15

HMC5883L_RA_CONFIG_A

HMC5883L_CRA_RATE_BIT

HMC5883L_CRA_RATE_LENGTH

void HMC5883L::setGain

(

uint8_t

gain

)

Set magnetic field gain value.

Parameters:

gain	New magnetic field gain value

See also:

getGain()

HMC5883L_RA_CONFIG_B

HMC5883L_CRB_GAIN_BIT

HMC5883L_CRB_GAIN_LENGTH

void HMC5883L::setMeasurementBias

(

uint8_t

bias

)

Set measurement bias value.

Parameters:

bias	New bias value (0-2 for normal/positive/negative respectively)

See also:

HMC5883L_BIAS_NORMAL

HMC5883L_RA_CONFIG_A

HMC5883L_CRA_BIAS_BIT

HMC5883L_CRA_BIAS_LENGTH

void HMC5883L::setMode

(

uint8_t

newMode

)

Set measurement mode.

Parameters:

newMode

New measurement mode

See also:

getMode()

HMC5883L_MODE_CONTINUOUS

HMC5883L_MODE_SINGLE

HMC5883L_MODE_IDLE

HMC5883L_RA_MODE

HMC5883L_MODEREG_BIT

HMC5883L_MODEREG_LENGTH

void HMC5883L::setSampleAveraging

(

uint8_t

averaging

)

Set number of samples averaged per measurement.

Parameters:

averaging

New samples averaged per measurement setting(0-3 for 1/2/4/8 respectively)

See also:

HMC5883L_RA_CONFIG_A

HMC5883L_CRA_AVERAGE_BIT

HMC5883L_CRA_AVERAGE_LENGTH

bool HMC5883L::testConnection

(

)

Verify the I2C connection. Make sure the device is connected and responds as expected.

Returns:

True if connection is valid, false otherwise

---

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

• HMC5883L/HMC5883L.h
• HMC5883L/HMC5883L.cpp