I2C device driver for the HMC5883L compass chip. More...

#include <fastarduino/devices/hmc5883l.h>

Inheritance diagram for devices::magneto::HMC5883L< MANAGER >:

Collaboration diagram for devices::magneto::HMC5883L< MANAGER >:

Classes
class	BeginFuture
	Create a future to be used by asynchronous method begin(BeginFuture&). More...

Public Types
using	EndFuture = TWriteRegisterFuture< MODE_REG, uint8_t, functor::Constant< uint8_t, uint8_t(OperatingMode::IDLE)> >
	Create a future to be used by asynchronous method end(EndFuture&). More...

using	StatusFuture = TReadRegisterFuture< STATUS_REG, Status >
	Create a future to be used by asynchronous method status(StatusFuture&). More...

using	MagneticFieldsFuture = TReadRegisterFuture< OUTPUT_REG_1, Sensor3D, Sensor3DTransformer >
	Create a future to be used by asynchronous method magnetic_fields(MagneticFieldsFuture&). More...

Public Types inherited from i2c::I2CDevice< MANAGER >
using	MANAGER = MANAGER
	the type of I2C Manager that can handle this device. More...

Public Member Functions
	HMC5883L (MANAGER &manager)
	Create a new device driver for a HMC5883L chip. More...

int	begin (BeginFuture &future)
	Start operation of this compass chip. More...

int	end (EndFuture &future) INLINE
	Stop operation of this compass chip. More...

int	status (StatusFuture &future) INLINE
	Get the curent chip status. More...

int	magnetic_fields (MagneticFieldsFuture &future)
	Read the magnetic fields (as raw values) on 3 axes (datasheet p15-16). More...

bool	begin (OperatingMode mode=OperatingMode::SINGLE, Gain gain=Gain::GAIN_1_3GA, DataOutput rate=DataOutput::RATE_15HZ, SamplesAveraged samples=SamplesAveraged::ONE_SAMPLE, MeasurementMode measurement=MeasurementMode::NORMAL)
	Start operation of this compass chip. More...

bool	end () INLINE
	Stop operation of this compass chip. More...

Status	status () INLINE
	Get the curent chip status. More...

bool	magnetic_fields (Sensor3D &fields)
	Read the magnetic fields (as raw values) on 3 axes (datasheet p15-16). More...

void	convert_fields_to_mGA (Sensor3D &fields)
	Convert raw fields measured obtained with `magnetic_fields()` to actual physical values, using the `Gain` configured for the device. More...

Additional Inherited Members
Protected Types inherited from i2c::I2CDevice< MANAGER >
using	ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE
	The abstract base class of all futures to be defined for a device. More...

using	FUTURE = typename MANAGER::template FUTURE< OUT, IN >
	The template base class of all futures to be defined for a device. More...

Protected Member Functions inherited from i2c::I2CDevice< MANAGER >
	I2CDevice (MANAGER &manager, uint8_t device, UNUSED Mode< MODE > mode, bool auto_stop)
	Create a new I2C device. More...

	I2CDevice (const I2CDevice &)=delete

I2CDevice &	operator= (const I2CDevice &)=delete

void	set_device (uint8_t device)
	Change the I2C address of this device. More...

int	launch_commands (ABSTRACT_FUTURE &future, utils::range< I2CLightCommand > commands)
	Launch execution (asynchronously or synchronously, depending on MANAGER) of a chain of I2CLightCommand items (constructed with `read()` and `write()` methods). More...

int	async_read (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading). More...

bool	sync_read (T &result)
	Helper method that launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading); the method blocks until the end of the I2C transaction. More...

int	async_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing only one write (typically for device register writing). More...

int	async_multi_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing several register writes. More...

bool	sync_write (const T &value)
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

bool	sync_write ()
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

Static Protected Member Functions inherited from i2c::I2CDevice< MANAGER >
static constexpr I2CLightCommand	read (uint8_t read_count=0, bool finish_future=false, bool stop=false)
	Build a read I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

static constexpr I2CLightCommand	write (uint8_t write_count=0, bool finish_future=false, bool stop=false)
	Build a write I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

Detailed Description

template<typename MANAGER>
class devices::magneto::HMC5883L< MANAGER >

I2C device driver for the HMC5883L compass chip.

Template Parameters

MANAGER one of FastArduino available I2C Manager

The HMC5883L also has a DRDY pin that you can use to an EXT or PCI pin, in order to be notified when sensor data is ready for reading; this is particularly useful in continuous mode, where you would try to avoid busy waits against HMC5883L status register. The following snippet (excerpt from Magneto2 example) show this:

// This handler gets notified when HMC5883L data is ready to read
class DataReadyHandler
{
public:
    DataReadyHandler() : ready_{false}
    {
        interrupt::register_handler(*this);
    }
    void reset()
    {
        ready_ = false;
    }
    bool ready() const
    {
        return ready_;
    }
private:
    void data_ready()
    {
        ready_ = true;
    }
    volatile bool ready_;
    DECL_INT_ISR_HANDLERS_FRIEND
};
 
// EXT pin connected to HMC5883L DRDY pin
static constexpr const board::ExternalInterruptPin DRDY = board::ExternalInterruptPin::D2_PD2_EXT0;
// Register our handler with DRDY EXT pin interrupts
REGISTER_INT_ISR_METHOD(0, DRDY, DataReadyHandler, &DataReadyHandler::data_ready)
 
int main()
{
    // Perform other necessary initializations here,
    // including I2C Manager and HMC5883L device (named compass in hte following code)
    ...
    // Initialize DRDY notifications handler
    DataReadyHandler handler;
    interrupt::INTSignal<DRDY> signal{interrupt::InterruptTrigger::RISING_EDGE};
    signal.enable();
 
    // Start compass in continuous mode
    compass.begin(OperatingMode::CONTINUOUS,
                  Gain::GAIN_1_9GA,
                  DataOutput::RATE_0_75HZ,
                  SamplesAveraged::EIGHT_SAMPLES);
    while (true)
    {
        // Wait until data is ready (time::yield() will put MCU to sleep)
        while (!handler.ready()) time::yield();
        handler.reset();
        // Read compass fields
        Sensor3D fields;
        compass.magnetic_fields(fields);
        // Use compass fields in your program
        ...
    }
}

Definition at line 216 of file hmc5883l.h.

Member Typedef Documentation

◆ EndFuture

template<typename MANAGER >

using devices::magneto::HMC5883L< MANAGER >::EndFuture = TWriteRegisterFuture<MODE_REG, uint8_t, functor::Constant<uint8_t, uint8_t(OperatingMode::IDLE)> >

Create a future to be used by asynchronous method end(EndFuture&).

This is used by end() to asynchronously launch the I2C transaction, and it shall be used by the caller to determine when the I2C transaction is finished.

See also: end(EndFuture&)

Definition at line 339 of file hmc5883l.h.

◆ StatusFuture

template<typename MANAGER >

using devices::magneto::HMC5883L< MANAGER >::StatusFuture = TReadRegisterFuture<STATUS_REG, Status>

Create a future to be used by asynchronous method status(StatusFuture&).

This is used by status() to asynchronously launch the I2C transaction, and it shall be used by the caller to determine when the I2C transaction is finished.

See also: status(StatusFuture&)

Definition at line 374 of file hmc5883l.h.

◆ MagneticFieldsFuture

template<typename MANAGER >

using devices::magneto::HMC5883L< MANAGER >::MagneticFieldsFuture = TReadRegisterFuture<OUTPUT_REG_1, Sensor3D, Sensor3DTransformer>

Create a future to be used by asynchronous method magnetic_fields(MagneticFieldsFuture&).

This is used by magnetic_fields() to asynchronously launch the I2C transaction, and it shall be used by the caller to determine when the I2C transaction is finished.

See also: magnetic_fields(MagneticFieldsFuture&); convert_fields_to_mGA()

Definition at line 407 of file hmc5883l.h.

Constructor & Destructor Documentation

◆ HMC5883L()

template<typename MANAGER >

devices::magneto::HMC5883L< MANAGER >::HMC5883L ( MANAGER & manager )

inlineexplicit

Create a new device driver for a HMC5883L chip.

Parameters

manager reference to a suitable MANAGER for this device

Definition at line 267 of file hmc5883l.h.

Member Function Documentation

◆ begin() [1/2]

template<typename MANAGER >

int devices::magneto::HMC5883L< MANAGER >::begin ( BeginFuture & future )

inline

Start operation of this compass chip.

Once this method has been called, you may use magnetic_fields() to find out the directions of the device.

Warning: Asynchronous API!

Parameters

future a BeginFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: BeginFuture; end(); begin(OperatingMode, Gain, DataOutput, SamplesAveraged, MeasurementMode); errors

Definition at line 325 of file hmc5883l.h.

◆ end() [1/2]

template<typename MANAGER >

int devices::magneto::HMC5883L< MANAGER >::end ( EndFuture & future )

inline

Stop operation of this compass chip.

You should not call magnetic_fields() after calling this method.

Warning: Asynchronous API!

Parameters

future an EndFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: EndFuture; end(); begin(BeginFuture&); errors

Definition at line 361 of file hmc5883l.h.

◆ status() [1/2]

template<typename MANAGER >

int devices::magneto::HMC5883L< MANAGER >::status ( StatusFuture & future )

inline

Get the curent chip status.

Warning: Asynchronous API!

Parameters

future a StatusFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: StatusFuture; status(); errors

Definition at line 393 of file hmc5883l.h.

◆ magnetic_fields() [1/2]

template<typename MANAGER >

int devices::magneto::HMC5883L< MANAGER >::magnetic_fields ( MagneticFieldsFuture & future )

inline

Read the magnetic fields (as raw values) on 3 axes (datasheet p15-16).

In order to convert raw measurements to physical values, you should call convert_fields_to_mGA().

Warning: Asynchronous API!

Parameters

future a MagneticFieldsFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors is in namespace errors.

See also: MagneticFieldsFuture; convert_fields_to_mGA(); magnetic_fields(Sensor3D&); errors

Definition at line 430 of file hmc5883l.h.

◆ begin() [2/2]

template<typename MANAGER >

bool devices::magneto::HMC5883L< MANAGER >::begin	(	OperatingMode	mode = `OperatingMode::SINGLE`,
		Gain	gain = `Gain::GAIN_1_3GA`,
		DataOutput	rate = `DataOutput::RATE_15HZ`,
		SamplesAveraged	samples = `SamplesAveraged::ONE_SAMPLE`,
		MeasurementMode	measurement = `MeasurementMode::NORMAL`
	)

inline

Start operation of this compass chip.

Once this method has been called, you may use magnetic_fields() to find out the directions of the device.

Warning: Blocking API!

Parameters

mode	the `OperatingMode` to operate this chip
gain	the `Gain` to use to increase measured magnetic fields
rate	the `DataOutput` rate to use in `OperatingMode::CONTINUOUS` mode
samples	the `SamplesAveraged` to use for each measurement
measurement	the `MeasurementMode` to use on the chip sensors

Return values

true	if the operation succeeded
false	if the operation failed

See also: end(); begin(BeginFuture&)

Definition at line 453 of file hmc5883l.h.

◆ end() [2/2]

template<typename MANAGER >

bool devices::magneto::HMC5883L< MANAGER >::end ( )

inline

Stop operation of this compass chip.

You should not call magnetic_fields() after calling this method.

Warning: Blocking API!

Return values

true	if the operation succeeded
false	if the operation failed

See also: begin(); end(EndFuture&)

Definition at line 473 of file hmc5883l.h.

◆ status() [2/2]

template<typename MANAGER >

Status devices::magneto::HMC5883L< MANAGER >::status ( )

inline

Get the curent chip status.

Warning: Blocking API!

See also: Status; status(StatusFuture&)

Definition at line 485 of file hmc5883l.h.

◆ magnetic_fields() [2/2]

template<typename MANAGER >

bool devices::magneto::HMC5883L< MANAGER >::magnetic_fields ( Sensor3D & fields )

inline

Read the magnetic fields (as raw values) on 3 axes (datasheet p15-16).

In order to convert raw measurements to physical values, you should call convert_fields_to_mGA().

Warning: Blocking API!

Parameters

fields a reference to a Sensor3D variable that will be filled with values upon method return

Return values

true	if the operation succeeded
false	if the operation failed

See also: convert_fields_to_mGA(); magnetic_fields(MagneticFieldsFuture&)

Definition at line 508 of file hmc5883l.h.

◆ convert_fields_to_mGA()

template<typename MANAGER >

void devices::magneto::HMC5883L< MANAGER >::convert_fields_to_mGA ( Sensor3D & fields )

inline

Convert raw fields measured obtained with magnetic_fields() to actual physical values, using the Gain configured for the device.

Parameters

fields a reference to a Sensor3D variable that will be converted from raw to physical values

See also: magnetic_fields(); begin()

Definition at line 523 of file hmc5883l.h.

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

fastarduino/devices/hmc5883l.h

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ EndFuture

◆ StatusFuture

◆ MagneticFieldsFuture

Constructor & Destructor Documentation

◆ HMC5883L()

Member Function Documentation

◆ begin() [1/2]

◆ end() [1/2]

◆ status() [1/2]

◆ magnetic_fields() [1/2]

◆ begin() [2/2]

◆ end() [2/2]

◆ status() [2/2]

◆ magnetic_fields() [2/2]

◆ convert_fields_to_mGA()