3-axis magnetometer driver interface. More...

Data Structures
struct	MagData
	3-axis magnetometer sample, in milligauss, in the watch frame. More...

Enumerations
enum	MagReadStatus { MagReadSuccess = 0 , MagReadClobbered = -1 , MagReadCommunicationFail = -2 , MagReadMagOff = -3 , MagReadNoMag = -4 }
	Result of mag_read_data(). More...

enum	MagSampleRate { MagSampleRate20Hz , MagSampleRate5Hz }
	Magnetometer sampling rate. More...

Functions
void	mag_init (void)
	Initialize the magnetometer.

void	mag_use (void)
	Take a reference on the magnetometer hardware.

void	mag_start_sampling (void)
	Take a reference on the magnetometer and start sampling at 5 Hz.

void	mag_release (void)
	Drop a reference on the magnetometer hardware.

MagReadStatus	mag_read_data (MagData *data)
	Read the latest sample.

bool	mag_change_sample_rate (MagSampleRate rate)
	Change the sampling rate.

Detailed Description

3-axis magnetometer driver interface.

The hardware is reference counted: it is powered while at least one user holds it through mag_use() or mag_start_sampling(), and turned off when the last user calls mag_release().

MagData data;
 
mag_start_sampling();
if (mag_read_data(&data) == MagReadSuccess) {
  // use data.x, data.y, data.z
}
mag_release();

Data Structure Documentation

◆ MagData

struct MagData

3-axis magnetometer sample, in milligauss, in the watch frame.

Data Fields
int16_t	x	Magnetic field along the X axis.
int16_t	y	Magnetic field along the Y axis.
int16_t	z	Magnetic field along the Z axis.

Enumeration Type Documentation

◆ MagReadStatus

enum MagReadStatus

Result of mag_read_data().

Enumerator
MagReadSuccess	A new sample was read.
MagReadClobbered	The sample was overwritten while being read.
MagReadCommunicationFail	No sample is ready, or the bus transfer failed.
MagReadMagOff	The magnetometer is not sampling.
MagReadNoMag	No magnetometer is present.

◆ MagSampleRate

enum MagSampleRate

Magnetometer sampling rate.

Enumerator
MagSampleRate20Hz	20 Hz.
MagSampleRate5Hz	5 Hz.

Function Documentation

◆ mag_change_sample_rate()

bool mag_change_sample_rate ( MagSampleRate rate )

Change the sampling rate.

Does nothing and succeeds when no reference is held.

Parameters

rate	New sampling rate.

Returns: true on success.

◆ mag_init()

void mag_init ( void )

Initialize the magnetometer.

Called once at startup, before any other function in this API.

◆ mag_read_data()

MagReadStatus mag_read_data ( MagData * data )

Read the latest sample.

The caller must hold a reference and the magnetometer must be sampling.

Parameters

[out] data Sample.

Returns: Read status, MagReadSuccess when data was filled.

◆ mag_release()

void mag_release ( void )

Drop a reference on the magnetometer hardware.

The hardware is turned off when the last reference is dropped.

◆ mag_start_sampling()

void mag_start_sampling ( void )

Take a reference on the magnetometer and start sampling at 5 Hz.

Must be matched with a call to mag_release().

◆ mag_use()

void mag_use ( void )

Take a reference on the magnetometer hardware.