3-axis digital compass. More...

#include <sg_101020034_3AxisCompass.hpp>

Inheritance diagram for SG::ThreeAxisDigitalCompass:

Collaboration diagram for SG::ThreeAxisDigitalCompass:

[legend]

Public Types
enum	ERegister { ERegister::kConfigRegA = 0, ERegister::kConfigRegB = 1, ERegister::kModeReg = 2, ERegister::kXMSB = 3, ERegister::kXLSB = 4, ERegister::kZMSB = 5, ERegister::kZLSB = 6, ERegister::kYMSB = 7, ERegister::kYLSB = 8, ERegister::kStatusReg = 9, ERegister::kIDRegA = 10, ERegister::kIDRegB = 11, ERegister::kIDRegC = 12 }
	I2C registers. More...

enum	EMode { EMode::kContinuousMeasurement = 0, EMode::kSingleMeasurement = 1, EMode::kIdle = 2, EMode::kSleep = 3 }
	Mode register (0x02). More...

enum	EDataOutputRate { EDataOutputRate::k0_75Hz = 0, EDataOutputRate::k1_5Hz = 1, EDataOutputRate::k3Hz = 2, EDataOutputRate::k7_5Hz = 3, EDataOutputRate::k15Hz = 4, EDataOutputRate::k30Hz = 5, EDataOutputRate::k75Hz = 6 }
	The rate at which new data readings are done when running in continuous measurement mode. More...

enum	EMeasurements { EMeasurements::kNormal = 0, EMeasurements::kPositiveBias = 1, EMeasurements::kNegativeBias = 2 }
	Measurement bias. More...

enum	EGain { EGain::k0_9Ga = 0, EGain::k1_2Ga = 1, EGain::k1_9Ga = 2, EGain::k2_5Ga = 3, EGain::k4_0Ga = 4, EGain::k4_6Ga = 5, EGain::k5_5Ga = 6, EGain::k7_9Ga = 7 }
	Device gain. More...

typedef uint8_t	I2CBus
	I2C bus. More...

typedef uint8_t	I2CAddress
	I2C addresses. More...

typedef uint8_t	I2CRegister
	I2C register. More...

typedef std::vector< uint8_t >	I2CBlock
	Block of sequential bytes to read or write. More...

Public Member Functions
virtual	~ThreeAxisDigitalCompass (void)
	Destructor. More...

	ThreeAxisDigitalCompass (const std::string &name="", const SG::GroveI2CDigital::I2CAddress addr=0)
	Constructor. If not specified, the I2C address will be obtained using get_address_from_type(). More...

virtual ThreeAxisDigitalCompass &	reset (void)
	Reset the configuration to default values. More...

virtual ThreeAxisDigitalCompass &	set_mode (const EMode mode=EMode::kSingleMeasurement)
	Set the operating mode. More...

virtual EMode	get_mode (void)
	Get the operating mode. More...

virtual ThreeAxisDigitalCompass &	set_config (const EDataOutputRate output_rate, const EMeasurements measurements)
	Set the output rate and measurement bias. More...

virtual ThreeAxisDigitalCompass &	get_config (EDataOutputRate &output_rate, EMeasurements &measurements)
	Get the output rate and measurement bias. More...

virtual ThreeAxisDigitalCompass &	set_config (const EGain gain)
	Set the device gain. More...

virtual ThreeAxisDigitalCompass &	get_config (EGain &gain)
	Get the device gain. More...

virtual ThreeAxisDigitalCompass &	get_data (int16_t &x, int16_t &y, int16_t &z)
	Get the measurement data stored in the HMC5883. More...

virtual bool	get_single_measurement (int16_t &x, int16_t &y, int16_t &z, const size_t milliseconds_to_wait=1000)
	This sets the mode to EMode::kSingleMeasurement, waits for a new measurement to have been made, and returns the new data. More...

virtual bool	wait_for_significant_change (int16_t &x, int16_t &y, int16_t &z, const size_t milliseconds_to_wait=0, const int16_t delta=10)
	Repeatedly call get_single_measurement() until the data values are significantly different than the initial values for `x`, `y`, and `z`. More...

virtual ThreeAxisDigitalCompass &	get_status (bool &regulator_enabled, bool &data_locked, bool &data_ready)
	Get status information. More...

virtual ThreeAxisDigitalCompass &	set_declination (const double declination)
	Set the magnetic declination to compensate for differences between magnetic north and geographic north. More...

virtual double	get_direction (void)
	Get the direction in radians. This uses the most recent values read by get_data(). More...

virtual double	get_heading (void)
	Get the compass heading in degrees, where east is `0`, north is `90`, west is `180`, and south is `270`. More...

double	gain_to_digital_resolution (const EGain gain)
	Convert the gain to digital resolution. More...

virtual bool	is_analog (void) const
	This is always `false` for GroveI2CDigital. More...

virtual bool	is_digital (void) const
	This is always `true` for GroveI2CDigital. More...

I2CAddress	get_address_from_type (void) const
	Get the address for this Grove type. More...

virtual uint8_t	read8 (const I2CRegister reg)
	Read a byte (8 bits) from the specificed register. More...

virtual uint16_t	read16 (const I2CRegister reg)
	Read a 16-bit word from the specified register. More...

virtual uint16_t	read12 (const I2CRegister reg)
	Read a 16-bit word from the specified register, but only keep the bottom 12 bits. More...

virtual I2CBlock	read_block (const I2CRegister reg)
	Read a consecutive block of bytes, anywhere between 1 and 32 bytes in length. More...

virtual GroveI2CDigital &	write_byte (const uint8_t value)
	Write a single byte to the I2C bus. More...

virtual GroveI2CDigital &	write_block (const I2CRegister reg, const I2CBlock &v)
	Write a consecutive block of bytes, anywhere between 1 and 32 bytes in length. More...

virtual GroveI2CDigital &	write_block (const I2CBlock &v)
	Write a consecutive block of bytes directly to the I2C file handle. More...

virtual bool	is_grove_uart (void) const
	This is always `false` for GroveI2C. More...

virtual bool	is_grove_i2c (void) const
	This is always `true` for GroveI2C. More...

virtual bool	is_grove_gpio (void) const
	This is always `false` for GroveI2C. More...

virtual uint32_t	get_sku (void) const
	Return a guess as to the Seeed SKU number based on the grove type. More...

virtual std::string	get_type_name (void) const
	Return a short text string representing the grove type. More...

virtual EGroveType	get_type (void) const
	Return the grove type. More...

virtual std::string	get_name (void) const
	Return the user-supplied name. More...

virtual std::string	get_description (void) const
	Return a multi-word 1-line description of this object. More...


virtual bool	is_regulator_enabled (void)
	Alias for the given field from get_status(). More...

virtual bool	is_data_locked (void)
	Alias for the given field from get_status(). More...

virtual bool	is_data_ready (void)
	Alias for the given field from get_status(). More...


virtual double	get_direction (const int16_t x, const int16_t y)
	Get the direction in radians. More...

virtual double	get_direction (const int16_t x, const int16_t y, const EGain gain)


virtual double	get_heading (const int16_t x, const int16_t y)
	Get the compass heading in degrees, where east is `0`, north is `90`, west is `180`, and south is `270`. More...

virtual double	get_heading (const int16_t x, const int16_t y, const EGain gain)


virtual GroveI2CDigital &	write8 (const I2CRegister reg, const uint8_t value)
	Write the given value to the specified register. More...

virtual GroveI2CDigital &	write16 (const I2CRegister reg, const uint16_t value)


bool	operator== (const GroveBase &rhs) const
	Test object equality. More...

bool	operator!= (const GroveBase &rhs) const
	Test object equality. More...

Static Public Member Functions
static I2CBus	detect_i2c_bus_number (const bool force_detect=false, const int force_bus_number=-1)
	Detect the I2C bus to use to talk to Grove I2C devices. More...

static I2CAddress	get_address_from_type (const EGroveType &type)
	Get the default I2C address for a given type. More...


static std::string	to_string (const EMode mode)
	Convert the enum to a string. More...

static std::string	to_string (const EDataOutputRate output_rate)
	Convert the enum to a string. More...

static std::string	to_string (const EMeasurements measurements)
	Convert the enum to a string. More...

static std::string	to_string (const EGain gain)
	Convert the enum to a string. More...

Public Attributes
I2CBus	i2c_bus_number
	The bus number to use for I2C Grove twigs. More...

I2CAddress	i2c_address
	The I2C address used to communicate with the Grove device. More...

int	i2c_file_handle
	The file handle to /dev/i2c-* used to communicate with the Grove device. More...

EGroveType	grove_type
	Grove type. More...

std::string	grove_name
	User-supplied name. More...

Protected Attributes
EGain	most_recent_gain
	Most recent gain. More...


double	declination_degrees
	Magnetic declination. More...

double	declination_radians
	Magnetic declination. More...


int16_t	most_recent_x
	Most recent value read by get_data(). More...

int16_t	most_recent_y
	Most recent value read by get_data(). More...

int16_t	most_recent_z
	Most recent value read by get_data(). More...

Detailed Description

3-axis digital compass.

Description	Image
Relative size of 3-axis digital compass.
3-axis digital compass connected to BBG.

Connect the digital compass to the left-hand-side digital I2C interface. The I2C address for this device is 0x1e.

i2cdetect -y -r 2
1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
         -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- 1e --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- UU UU UU UU -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --

Example source:

SG::ThreeAxisDigitalCompass compass;
compass.reset(); // use default settings
while (! done)
{
    int16_t x = 0;
    int16_t y = 0;
    int16_t z = 0;
    compass.wait_for_significant_change( x, y, z );
    std::cout << "x=" << x << ", y=" << y << ", z=" << z << std::endl;
}

Example source:

SG::ThreeAxisDigitalCompass compass;
int16_t x = 0;
int16_t y = 0;
int16_t z = 0;
compass.get_data( x, y, z );
compass.set_declination( -3.5 ); // -3 degrees 30 minutes
double heading = compass.get_heading( x, y );

See also: http://www.seeedstudio.com/wiki/Grove_-_3-Axis_Digital_Compass; http://www.seeedstudio.com/depot/grove-3axis-compass-p-759.html; http://www.seeedstudio.com/wiki/images/4/42/HMC5883.pdf; https://aerospace.honeywell.com/~/media/aerospace/files/datasheet/3-axisdigitalcompassichmc5883l_ds.pdf

Member Typedef Documentation

◆ I2CAddress

typedef uint8_t SG::GroveI2CDigital::I2CAddress

inherited

I2C addresses.

See also: get_address_from_type()

◆ I2CBlock

typedef std::vector<uint8_t> SG::GroveI2CDigital::I2CBlock

inherited

Block of sequential bytes to read or write.

◆ I2CBus

typedef uint8_t SG::GroveI2CDigital::I2CBus

inherited

I2C bus.

See also: detect_i2c_bus_number()

◆ I2CRegister

typedef uint8_t SG::GroveI2CDigital::I2CRegister

inherited

I2C register.

Member Enumeration Documentation

◆ EDataOutputRate

enum SG::ThreeAxisDigitalCompass::EDataOutputRate

strong

The rate at which new data readings are done when running in continuous measurement mode.

See also: EMode::kContinuousMeasurement; set_mode(); set_config()

Enumerator
k0_75Hz	1333 milliseconds between data updates
k1_5Hz	667 milliseconds between data updates
k3Hz	333 milliseconds between data updates
k7_5Hz	133 milliseconds between data updates
k15Hz	67 milliseconds between data updates (default value)
k30Hz	33 milliseconds between data updates
k75Hz	13 milliseconds between data updates

◆ EGain

enum SG::ThreeAxisDigitalCompass::EGain

strong

Device gain.

These are specific to the HMC5883. The newer HMC5883L has different gain values which are slightly different, and which will also impact gain_to_digital_resolution(). Unfortunately, both the HMC5883 and HMC5883L identify themselves identically.

See also: get_config(); set_config()

Enumerator
k0_9Ga	gain (counts/Gauss) = 1280, digital resolution = 1/1280*1000 = 0.78 mG
k1_2Ga	gain (counts/Gauss) = 1024, digital resolution = 1/1024*1000 = 0.98 mG (default value)
k1_9Ga	gain (counts/Gauss) = 768, digital resolution = 1/768*1000 = 1.30 mG
k2_5Ga	gain (counts/Gauss) = 614, digital resolution = 1/614*1000 = 1.63 mG
k4_0Ga	gain (counts/Gauss) = 415, digital resolution = 1/415*1000 = 2.41 mG
k4_6Ga	gain (counts/Gauss) = 361, digital resolution = 1/361*1000 = 2.77 mG
k5_5Ga	gain (counts/Gauss) = 307, digital resolution = 1/307*1000 = 3.26 mG
k7_9Ga	gain (counts/Gauss) = 219, digital resolution = 1/219*1000 = 4.57 mG

◆ EMeasurements

enum SG::ThreeAxisDigitalCompass::EMeasurements

strong

Measurement bias.

See also: get_config(); set_config()

Enumerator
kNormal	default value
kPositiveBias
kNegativeBias

◆ EMode

enum SG::ThreeAxisDigitalCompass::EMode

strong

Mode register (0x02).

See also: ERegister::kModeReg; set_mode(); HMC5883 datasheet page 10, and table 16 on page 14

Enumerator
kContinuousMeasurement	The device continuously makes measurements and places measured data in data output registers.
kSingleMeasurement	The device makes a single measurement, places the measured data in data output registers, then puts itself in idle mode. This is the default when first powered on.
kIdle	The device is accessible through the I2C bus, but major sources of power consumption are disabled, such as, but not limited to, the ADC, the amplifier, the SVDD pin, and the sensor bias current.
kSleep	The device functionality is limited to listening to the I2C bus.

◆ ERegister

enum SG::ThreeAxisDigitalCompass::ERegister

strong

I2C registers.

See also: HMC5883 datasheet page 11

Enumerator
kConfigRegA	0
kConfigRegB	1
kModeReg	2
kXMSB	3 (this register is read-only)
kXLSB	4 (this register is read-only)
kZMSB	5 (this register is read-only)
kZLSB	6 (this register is read-only)
kYMSB	7 (this register is read-only)
kYLSB	8 (this register is read-only)
kStatusReg	9 (this register is read-only)
kIDRegA	10 (this register is read-only)
kIDRegB	11 (this register is read-only)
kIDRegC	12 (this register is read-only)

Constructor & Destructor Documentation

◆ ~ThreeAxisDigitalCompass()

SG::ThreeAxisDigitalCompass::~ThreeAxisDigitalCompass ( void )

virtual

Destructor.

◆ ThreeAxisDigitalCompass()

SG::ThreeAxisDigitalCompass::ThreeAxisDigitalCompass	(	const std::string &	name = `""`,
		const SG::GroveI2CDigital::I2CAddress	addr = `0`
	)

Constructor. If not specified, the I2C address will be obtained using get_address_from_type().

Member Function Documentation

◆ detect_i2c_bus_number()

SG::GroveI2CDigital::I2CBus SG::GroveI2CDigital::detect_i2c_bus_number	(	const bool	force_detect = `false`,
		const int	force_bus_number = `-1`
	)

staticinherited

Detect the I2C bus to use to talk to Grove I2C devices.

This is normally 1 or 2. The detection consists of looking at /dev/i2c* devices.

Parameters

[in]	force_detect	The detected bus number is usually remembered to prevent having to re-detect it every time a new GroveI2C object is instantiated. If `force_detect` is set to `true`, then this will force GroveI2C to ignore the previously cached bus number and re-detect the I2C bus.
[in]	force_bus_number	If an explicit bus number should be used, then `force_bus_number` can be set to the correct bus value. This will prevent calls to `detect_i2c_bus_number()` from attempting to auto-detect the I2C bus. Setting the I2C bus number this way wont change existing GroveI2C objects that have already been instantiated. Only new objects will use the new bus number. The actual bus number used by specific objects is i2c_bus_number.

Exceptions

std::system_error	if /dev cannot be opened.
std::runtime_error	if the I2C bus cannot be found in /dev.

Referenced by SG::GroveI2CDigital::is_digital().

Here is the caller graph for this function:

◆ gain_to_digital_resolution()

double SG::ThreeAxisDigitalCompass::gain_to_digital_resolution ( const EGain gain )

Convert the gain to digital resolution.

See also: EGain; The datasheet for the newer model HMC5883L has a better explanation of the gain and the digital resolution.

References k0_9Ga, k1_2Ga, k1_9Ga, k2_5Ga, k4_0Ga, k4_6Ga, k5_5Ga, and k7_9Ga.

Referenced by get_direction().

Here is the caller graph for this function:

◆ get_address_from_type() [1/2]

SG::GroveI2CDigital::I2CAddress SG::GroveI2CDigital::get_address_from_type ( const EGroveType & type )

staticinherited

Get the default I2C address for a given type.

Note that several Grove types have multiple addresses. This only returns the first address.

See also: http://www.seeedstudio.com/wiki/I2C_And_I2C_Address_of_Seeed_Product

References SG::k3AxisDigitalAccelerometer16g, SG::k3AxisDigitalAccelerometer1_5g, SG::k3AxisDigitalAccelerometer400g, SG::k3AxisDigitalCompass, SG::k3AxisDigitalGyro, SG::k6AxisAccelerometerAndCompassV1, SG::k6AxisAccelerometerAndCompassV2, SG::kBarometerHighAccuracy, SG::kBarometerSensor, SG::kBarometerSensorBMP180, SG::kDigitalInfraredTemperatureSensor, SG::kDigitalLightSensor, SG::kGestureV1, SG::kI2CADC, SG::kI2CColorSensor, SG::kI2CFMReceiver, SG::kI2CMotorDriverV10, SG::kI2CMotorDriverV12, SG::kIMU10DOF, SG::kIMU9DOFV1, SG::kIMU9DOFV2, SG::kLCDRGBBacklight, SG::kMultichannelGasSensor, SG::kNFCTag, SG::kOLEDDisplay0_96, SG::kOLEDDisplay1_12, SG::kQTouchSensor, SG::kRTC, SG::kTemperatureAndHumiditySensor, and SG::kTouchSensor.

◆ get_address_from_type() [2/2]

I2CAddress SG::GroveI2CDigital::get_address_from_type ( void ) const

inlineinherited

Get the address for this Grove type.

References SG::GroveI2CDigital::get_address_from_type(), SG::GroveBase::get_type(), SG::GroveI2CDigital::read16(), and SG::GroveI2CDigital::read8().

Referenced by SG::GroveI2CDigital::get_address_from_type(), SG::GroveI2CDigital::GroveI2CDigital(), and SG::GroveI2CDigital::is_digital().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_config() [1/2]

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::get_config	(	EDataOutputRate &	output_rate,
		EMeasurements &	measurements
	)

virtual

Get the output rate and measurement bias.

Example source:

SG::ThreeAxisDigitalCompass compass;
SG::ThreeAxisDigitalCompass::EDataOutputRate rate;
SG::ThreeAxisDigitalCompass::EMeasurements measurements;
compass.get_config( rate, measurements );
std::cout << "rate="         << SG::ThreeAxisDigitalCompass::to_string(rate)         << ", "
          << "measurements=" << SG::ThreeAxisDigitalCompass::to_string(measurements) << std::endl;

See also: set_config(); EDataOutputRate; EMeasurements

References k15Hz, kConfigRegA, kNormal, and SG::GroveI2CDigital::read8().

Referenced by compass().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_config() [2/2]

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::get_config ( EGain & gain )

virtual

Get the device gain.

See also: set_config(); EGain

References k1_2Ga, kConfigRegB, and SG::GroveI2CDigital::read8().

Here is the call graph for this function:

◆ get_data()

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::get_data	(	int16_t &	x,
		int16_t &	y,
		int16_t &	z
	)

virtual

Get the measurement data stored in the HMC5883.

If the mode has been set to EMode::kContinuousMeasurement, then this call may obtain a new measurement (but also see EDataOutputRate).

Note: Calling get_data() does not cause the device to obtain a new reading. It only returns what was previously read and stored.

If using continuous mode, consider calling is_data_ready() prior to get_data().
If using single measurement mode, then get_data() is likely the wrong call to make. Instead, the device can be told to make a new reading and return it by calling either get_single_measurement() or wait_for_significant_change().

Example source:

SG::ThreeAxisDigitalCompass compass;
compass.set_mode( SG::ThreeAxisDigitalCompass::EMode::kContinuousMeasurement );
compass.set_config( SG::ThreeAxisDigitalCompass::EDataOutputRate::k15Hz, SG::ThreeAxisDigitalCompass::EMeasurements::kNormal );
// output rate of 15Hz means a new reading should be available every 66.7 milliseconds (1000ms/15=66.7ms)
while ( ! done )
{
    bool ready = false;
    while (! done && ! ready)
    {
        std::this_thread::sleep_for( std::chrono::milliseconds( 25 ) );
        ready = compass.is_data_ready();
    }
    if (ready)
    {
        int16_t xyz[3];
        compass.get_data( xyz[0], xyz[1], xyz[2] );
        do_something_with_readings( xyz );
    }
}

See also: get_single_measurement(); wait_for_significant_change()

References kXMSB, most_recent_x, most_recent_y, most_recent_z, and SG::GroveI2CDigital::read8().

Referenced by get_single_measurement().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_description()

std::string SG::GroveBase::get_description ( void ) const

virtualinherited

Return a multi-word 1-line description of this object.

References SG::demangle(), SG::GroveBase::get_name(), SG::GroveBase::get_sku(), SG::GroveBase::get_type_name(), SG::GroveBase::is_grove_gpio(), SG::GroveBase::is_grove_i2c(), SG::GroveBase::is_grove_uart(), and SG::BeagleBone::Detect::to_string().

Referenced by buzzer(), chainable_rgb_led(), common_oled(), SG::GroveBase::get_name(), SG::GroveI2CDigital::GroveI2CDigital(), SG::CommonOLED::set_display_bitmap(), SG::CommonOLED::set_orientation(), temperature(), variable_led(), and SG::GroveI2CDigital::write_block().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_direction() [1/3]

double SG::ThreeAxisDigitalCompass::get_direction ( void )

virtual

Get the direction in radians. This uses the most recent values read by get_data().

Todo:: I don't know how to test if this code is working correctly. Inspiration came from the method Hmc5883l::direction() in https://github.com/intel-iot-devkit/upm/blob/master/src/hmc5883l/hmc5883l.cxx

References most_recent_gain, most_recent_x, and most_recent_y.

Referenced by compass(), get_direction(), and get_heading().

Here is the caller graph for this function:

◆ get_direction() [2/3]

double SG::ThreeAxisDigitalCompass::get_direction	(	const int16_t	x,
		const int16_t	y
	)

virtual

Get the direction in radians.

Todo:: I don't know how to test if this code is working correctly. Inspiration came from the method Hmc5883l::direction() in https://github.com/intel-iot-devkit/upm/blob/master/src/hmc5883l/hmc5883l.cxx

References get_direction(), and most_recent_gain.

Here is the call graph for this function:

◆ get_direction() [3/3]

double SG::ThreeAxisDigitalCompass::get_direction	(	const int16_t	x,
		const int16_t	y,
		const EGain	gain
	)

virtual

Todo:: I don't know how to test if this code is working correctly. Inspiration came from the method Hmc5883l::direction() in https://github.com/intel-iot-devkit/upm/blob/master/src/hmc5883l/hmc5883l.cxx

References declination_radians, and gain_to_digital_resolution().

Here is the call graph for this function:

◆ get_heading() [1/3]

double SG::ThreeAxisDigitalCompass::get_heading ( void )

virtual

Get the compass heading in degrees, where east is 0, north is 90, west is 180, and south is 270.

This uses the most recent values read by get_data().

Todo:: I don't know how to test if this code is working correctly. Inspiration came from the method Hmc5883l::heading() in https://github.com/intel-iot-devkit/upm/blob/master/src/hmc5883l/hmc5883l.cxx

References most_recent_gain, most_recent_x, and most_recent_y.

Referenced by compass(), and get_heading().

Here is the caller graph for this function:

◆ get_heading() [2/3]

double SG::ThreeAxisDigitalCompass::get_heading	(	const int16_t	x,
		const int16_t	y
	)

virtual

Get the compass heading in degrees, where east is 0, north is 90, west is 180, and south is 270.

Todo:: I don't know how to test if this code is working correctly. Inspiration came from the method Hmc5883l::heading() in https://github.com/intel-iot-devkit/upm/blob/master/src/hmc5883l/hmc5883l.cxx

References get_heading(), and most_recent_gain.

Here is the call graph for this function:

◆ get_heading() [3/3]

double SG::ThreeAxisDigitalCompass::get_heading	(	const int16_t	x,
		const int16_t	y,
		const EGain	gain
	)

virtual

Todo:: I don't know how to test if this code is working correctly. Inspiration came from the method Hmc5883l::heading() in https://github.com/intel-iot-devkit/upm/blob/master/src/hmc5883l/hmc5883l.cxx

References get_direction().

Here is the call graph for this function:

◆ get_mode()

SG::ThreeAxisDigitalCompass::EMode SG::ThreeAxisDigitalCompass::get_mode ( void )

virtual

Get the operating mode.

See also: set_mode(); to_string(); EMode

Example source:

SG::ThreeAxisDigitalCompass compass;
// ...
const SG::ThreeAxisDigitalCompass::EMode mode = compass.get_mode();
std::cout << "digital compass mode: " << SG::ThreeAxisDigitalCompass::to_string(mode) << std::endl;

References kModeReg, and SG::GroveI2CDigital::read8().

Referenced by compass().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_name()

virtual std::string SG::GroveBase::get_name ( void ) const

inlinevirtualinherited

Return the user-supplied name.

References SG::GroveBase::get_description(), SG::GroveBase::grove_name, SG::GroveBase::is_grove_gpio(), SG::GroveBase::is_grove_i2c(), and SG::GroveBase::is_grove_uart().

Referenced by SG::GroveBase::get_description(), SG::GroveBase::operator=(), and SG::GroveBase::operator==().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_single_measurement()

bool SG::ThreeAxisDigitalCompass::get_single_measurement	(	int16_t &	x,
		int16_t &	y,
		int16_t &	z,
		const size_t	milliseconds_to_wait = `1000`
	)

virtual

This sets the mode to EMode::kSingleMeasurement, waits for a new measurement to have been made, and returns the new data.

Note: After making a measurement in single measurement mode, the device automatically puts itself into EMode::kIdle.

This method may be called multiple times, where each time it is called a new measurement will be made.

Parameters

[out]	x	Measurement value from channel `X`.
[out]	y	Measurement value from channel `Y`.
[out]	z	Measurement value from channel `Z`.
[in]	milliseconds_to_wait	The length of time to wait for data to be available. If set to zero, then `get_single_measurement()` will wait as long as necessary. It normally takes less than 10 milliseconds for data to be available.

Returns: TRUE if a reading was obtained.; FALSE if a timeout occurred. This can only happen when milliseconds_to_wait is non-zero.

Source example:

SG::ThreeAxisDigitalCompass compass;
while ( ! done )
{
    int16_t x, y, z;
    bool valid = compass.get_single_measurement( x, y, z );
    if ( ! valid )
    {
        break;
    }
    std::cout << "x=" << x << ", y=" << y << ", z=" << z << std::endl;
}

References get_data(), is_data_ready(), kSingleMeasurement, and set_mode().

Referenced by wait_for_significant_change().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_sku()

virtual uint32_t SG::GroveBase::get_sku ( void ) const

inlinevirtualinherited

Return a guess as to the Seeed SKU number based on the grove type.

References SG::get_sku_from_grove_type(), and SG::GroveBase::grove_type.

Referenced by SG::GroveBase::get_description().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_status()

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::get_status	(	bool &	regulator_enabled,
		bool &	data_locked,
		bool &	data_ready
	)

virtual

Get status information.

Parameters

[out]	regulator_enabled	This is set when the internal voltage regulator is enabled. This is cleared when the internal regulator is disabled.
[out]	data_locked	This is set when some but not all of the data output registers have been read. When this is set, the data output is locked and new data will not be stored.
[out]	data_ready	This is set once data has been stored in the data registers, and cleared when the device initiates a write to the data output registers.

See also: is_regulator_enabled(); is_data_locked(); is_data_ready()

References kStatusReg, and SG::GroveI2CDigital::read8().

Referenced by compass(), is_data_locked(), is_data_ready(), and is_regulator_enabled().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_type()

virtual EGroveType SG::GroveBase::get_type ( void ) const

inlinevirtualinherited

Return the grove type.

References SG::GroveBase::grove_type.

Referenced by SG::GroveI2CDigital::get_address_from_type(), SG::GroveBase::operator=(), and SG::GroveBase::operator==().

Here is the caller graph for this function:

◆ get_type_name()

virtual std::string SG::GroveBase::get_type_name ( void ) const

inlinevirtualinherited

Return a short text string representing the grove type.

References SG::GroveBase::grove_type, and SG::to_string().

Referenced by SG::GroveBase::get_description().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_analog()

virtual bool SG::GroveI2CDigital::is_analog ( void ) const

inlinevirtualinherited

This is always false for GroveI2CDigital.

Implements SG::GroveI2C.

◆ is_data_locked()

bool SG::ThreeAxisDigitalCompass::is_data_locked ( void )

virtual

Alias for the given field from get_status().

References get_status().

Here is the call graph for this function:

◆ is_data_ready()

bool SG::ThreeAxisDigitalCompass::is_data_ready ( void )

virtual

Alias for the given field from get_status().

References get_status().

Referenced by get_single_measurement().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_digital()

virtual bool SG::GroveI2CDigital::is_digital ( void ) const

inlinevirtualinherited

This is always true for GroveI2CDigital.

Implements SG::GroveI2C.

References SG::GroveI2CDigital::detect_i2c_bus_number(), and SG::GroveI2CDigital::get_address_from_type().

Here is the call graph for this function:

◆ is_grove_gpio()

virtual bool SG::GroveI2C::is_grove_gpio ( void ) const

inlinevirtualinherited

This is always false for GroveI2C.

Implements SG::GroveBase.

References SG::GroveI2C::is_analog(), and SG::GroveI2C::is_digital().

Here is the call graph for this function:

◆ is_grove_i2c()

virtual bool SG::GroveI2C::is_grove_i2c ( void ) const

inlinevirtualinherited

This is always true for GroveI2C.

Implements SG::GroveBase.

◆ is_grove_uart()

virtual bool SG::GroveI2C::is_grove_uart ( void ) const

inlinevirtualinherited

This is always false for GroveI2C.

Implements SG::GroveBase.

◆ is_regulator_enabled()

bool SG::ThreeAxisDigitalCompass::is_regulator_enabled ( void )

virtual

Alias for the given field from get_status().

References get_status().

Here is the call graph for this function:

◆ operator!=()

bool SG::GroveBase::operator!= ( const GroveBase & rhs ) const

inlineinherited

Test object equality.

References SG::GroveBase::operator==().

Here is the call graph for this function:

◆ operator==()

bool SG::GroveBase::operator== ( const GroveBase & rhs ) const

inherited

Test object equality.

References SG::GroveBase::get_name(), and SG::GroveBase::get_type().

Referenced by SG::GroveBase::operator!=(), SG::Buzzer::operator==(), SG::TemperatureAndHumiditySensor::operator==(), SG::TemperatureSensor::operator==(), and SG::I2CADC::operator==().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ read12()

virtual uint16_t SG::GroveI2CDigital::read12 ( const I2CRegister reg )

inlinevirtualinherited

Read a 16-bit word from the specified register, but only keep the bottom 12 bits.

Some devices such as the I2CADC return 12-bit values.

References SG::GroveI2CDigital::read16(), SG::GroveI2CDigital::read_block(), SG::GroveI2CDigital::write16(), SG::GroveI2CDigital::write8(), SG::GroveI2CDigital::write_block(), and SG::GroveI2CDigital::write_byte().

Referenced by SG::I2CADC::read12().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ read16()

uint16_t SG::GroveI2CDigital::read16 ( const I2CRegister reg )

virtualinherited

Read a 16-bit word from the specified register.

Exceptions

std::system_error if the register cannot be read.

Note: The high/low bytes in the 16-bit word are swapped after reading.

Referenced by SG::GroveI2CDigital::get_address_from_type(), and SG::GroveI2CDigital::read12().

Here is the caller graph for this function:

◆ read8()

uint8_t SG::GroveI2CDigital::read8 ( const I2CRegister reg )

virtualinherited

Read a byte (8 bits) from the specificed register.

Exceptions

std::system_error if the register cannot be read.

Referenced by SG::GroveI2CDigital::get_address_from_type(), get_config(), get_data(), get_mode(), get_status(), and SG::I2CADC::read8().

Here is the caller graph for this function:

◆ read_block()

SG::GroveI2CDigital::I2CBlock SG::GroveI2CDigital::read_block ( const I2CRegister reg )

virtualinherited

Read a consecutive block of bytes, anywhere between 1 and 32 bytes in length.

See also: write_block()

Exceptions

std::system_error if the register cannot be read.

Referenced by SG::GroveI2CDigital::read12().

Here is the caller graph for this function:

◆ reset()

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::reset ( void )

virtual

Reset the configuration to default values.

The default configuration is:

15 Hz data output rate
normal bias
single measurement mode

References k15Hz, k1_2Ga, kNormal, kSingleMeasurement, set_config(), and set_mode().

Referenced by compass().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_config() [1/2]

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::set_config	(	const EDataOutputRate	output_rate,
		const EMeasurements	measurements
	)

virtual

Set the output rate and measurement bias.

Example source:

SG::ThreeAxisDigitalCompass compass;
compass.set_mode( SG::ThreeAxisDigitalCompass::EMode::kContinuousMeasurement );
// 7.5Hz update rate means we'll have a new reading available every 133 milliseconds (1000ms/7.5=133.3ms)
compass.set_config( SG::ThreeAxisDigitalCompass::EDataOutputRate::k7_5Hz, SG::ThreeAxisDigitalCompass::EMeasurements::kNormal );

See also: get_config(); EDataOutputRate; EMeasurements

References kConfigRegA, and SG::GroveI2CDigital::write8().

Referenced by compass(), and reset().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_config() [2/2]

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::set_config ( const EGain gain )

virtual

Set the device gain.

Warning: The documentation for the more recent HMC5883L states the following: Note that the very first measurement after a gain change maintains the same gain as the previous setting. The new gain setting is effective from the second measurement and on.

See also: get_config(); EGain

References kConfigRegB, most_recent_gain, and SG::GroveI2CDigital::write8().

Here is the call graph for this function:

◆ set_declination()

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::set_declination ( const double declination )

virtual

Set the magnetic declination to compensate for differences between magnetic north and geographic north.

This is specific to the geographic location where the device runs, and can be obtained from places such as http://www.magnetic-declination.com/ .

Parameters

[in] declination Set the declination in decimal degrees format. For example, 15 degrees 54 minutes of declination would be specified as 15.9 (15 + 54/60).

See also: http://www.magnetic-declination.com/

References declination_degrees, and declination_radians.

◆ set_mode()

SG::ThreeAxisDigitalCompass & SG::ThreeAxisDigitalCompass::set_mode ( const EMode mode = EMode::kSingleMeasurement )

virtual

Set the operating mode.

The default when first powered on is EMode::kSingleMeasurement which leads to EMode::kIdle after having stored the data. To get compass data to continuously update, set the mode to EMode::kContinuousMeasurement, or call get_single_measurement().

Example source:

SG::ThreeAxisDigitalCompass compass;
compass.set_mode( SG::ThreeAxisDigitalCompass::EMode::kContinuousMeasurement );
// 3Hz update rate means we'll have a new reading available every 333 milliseconds (1000ms/3=333.3ms)
compass.set_config( SG::ThreeAxisDigitalCompass::EDataOutputRate::k3Hz, SG::ThreeAxisDigitalCompass::EMeasurements::kNormal );
while ( ! done )
{
    std::this_thread::sleep_for( std::chrono::milliseconds( 350 ) );
    int16_t xyz[3];
    compass.get_data( xyz[0], xyz[1], xyz[2] );
    do_something_with_readings( xyz );
}

See also: get_mode()

References kContinuousMeasurement, kIdle, kModeReg, kSingleMeasurement, kSleep, SG::BeagleBone::Detect::to_string(), and SG::GroveI2CDigital::write8().

Referenced by compass(), get_single_measurement(), and reset().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ to_string() [1/4]

std::string SG::ThreeAxisDigitalCompass::to_string ( const EMode mode )

static

Convert the enum to a string.

References kContinuousMeasurement, kIdle, kSingleMeasurement, and kSleep.

Referenced by compass().

Here is the caller graph for this function:

◆ to_string() [2/4]

std::string SG::ThreeAxisDigitalCompass::to_string ( const EDataOutputRate output_rate )

static

Convert the enum to a string.

References k0_75Hz, k15Hz, k1_5Hz, k30Hz, k3Hz, k75Hz, and k7_5Hz.

◆ to_string() [3/4]

std::string SG::ThreeAxisDigitalCompass::to_string ( const EMeasurements measurements )

static

Convert the enum to a string.

References kNegativeBias, kNormal, and kPositiveBias.

◆ to_string() [4/4]

std::string SG::ThreeAxisDigitalCompass::to_string ( const EGain gain )

static

Convert the enum to a string.

References k0_9Ga, k1_2Ga, k1_9Ga, k2_5Ga, k4_0Ga, k4_6Ga, k5_5Ga, and k7_9Ga.

◆ wait_for_significant_change()

bool SG::ThreeAxisDigitalCompass::wait_for_significant_change	(	int16_t &	x,
		int16_t &	y,
		int16_t &	z,
		const size_t	milliseconds_to_wait = `0`,
		const int16_t	delta = `10`
	)

virtual

Repeatedly call get_single_measurement() until the data values are significantly different than the initial values for x, y, and z.

Parameters

[in,out]	x	Measurement value from channel `X`.
[in,out]	y	Measurement value from channel `Y`.
[in,out]	z	Measurement value from channel `Z`.
[in]	milliseconds_to_wait	The length of time to wait for a signficant change. If set to zero, then `wait_for_significant_change()` will wait forever.
[in]	delta	Determines how different `X`, `Y`, or `Z` must be from their original values for the difference to be considered "significant".

Returns: TRUE if a significantly different reading was obtained.; FALSE if a timeout occurred. This can only happen when milliseconds_to_wait is non-zero.

References get_single_measurement().

Referenced by compass().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write16()

SG::GroveI2CDigital & SG::GroveI2CDigital::write16	(	const I2CRegister	reg,
		const uint16_t	value
	)

virtualinherited

Note: The high/low bytes in the 16-bit word are swapped prior to writting.

Exceptions

std::system_error if the value cannot be written.

Referenced by SG::GroveI2CDigital::read12(), and SG::I2CADC::write16().

Here is the caller graph for this function:

◆ write8()

SG::GroveI2CDigital & SG::GroveI2CDigital::write8	(	const I2CRegister	reg,
		const uint8_t	value
	)

virtualinherited

Write the given value to the specified register.

Exceptions

std::system_error if the value cannot be written.

Referenced by SG::GroveI2CDigital::read12(), set_config(), set_mode(), and SG::I2CADC::write8().

Here is the caller graph for this function:

◆ write_block() [1/2]

SG::GroveI2CDigital & SG::GroveI2CDigital::write_block	(	const I2CRegister	reg,
		const I2CBlock &	v
	)

virtualinherited

Write a consecutive block of bytes, anywhere between 1 and 32 bytes in length.

See also: read_block()

Exceptions

std::length_error	if the block is too long to write.
std::system_error	if the block failed to write.

References SG::GroveBase::get_description(), SG::GroveI2CDigital::i2c_address, and SG::BeagleBone::Detect::to_string().

Referenced by SG::CommonOLED::flood(), SG::GroveI2CDigital::read12(), SG::OLED096::reset(), SG::CommonOLED::send_command(), SG::CommonOLED::set_display_bitmap(), SG::CommonOLED::set_orientation(), and SG::CommonOLED::show().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write_block() [2/2]

SG::GroveI2CDigital & SG::GroveI2CDigital::write_block ( const I2CBlock & v )

virtualinherited

Write a consecutive block of bytes directly to the I2C file handle.

Exceptions

std::system_error if the block failed to write.

References SG::GroveBase::get_description(), SG::GroveI2CDigital::i2c_address, SG::GroveI2CDigital::i2c_file_handle, and SG::BeagleBone::Detect::to_string().

Here is the call graph for this function:

◆ write_byte()

SG::GroveI2CDigital & SG::GroveI2CDigital::write_byte ( const uint8_t value )

virtualinherited

Write a single byte to the I2C bus.

Exceptions

std::system_error if the value cannot be writen.

Referenced by SG::OLED096::all_off_display(), SG::OLED096::all_on_display(), SG::OLED096::invert_display(), SG::OLED096::normal_display(), SG::GroveI2CDigital::read12(), and SG::CommonOLED::set_display_bitmap().

Here is the caller graph for this function:

Member Data Documentation

◆ declination_degrees

double SG::ThreeAxisDigitalCompass::declination_degrees

protected

Magnetic declination.

See also: set_declination(); http://www.magnetic-declination.com/

Referenced by set_declination().

◆ declination_radians

double SG::ThreeAxisDigitalCompass::declination_radians

protected

Magnetic declination.

See also: set_declination(); http://www.magnetic-declination.com/

Referenced by get_direction(), and set_declination().

◆ grove_name

std::string SG::GroveBase::grove_name

inherited

User-supplied name.

Referenced by SG::GroveBase::get_name(), and SG::GroveBase::operator=().

◆ grove_type

EGroveType SG::GroveBase::grove_type

inherited

Grove type.

Referenced by SG::GroveBase::get_sku(), SG::GroveBase::get_type(), SG::GroveBase::get_type_name(), and SG::GroveBase::operator=().

◆ i2c_address

I2CAddress SG::GroveI2CDigital::i2c_address

inherited

The I2C address used to communicate with the Grove device.

Referenced by SG::GroveI2CDigital::GroveI2CDigital(), SG::I2CADC::operator==(), and SG::GroveI2CDigital::write_block().

◆ i2c_bus_number

I2CBus SG::GroveI2CDigital::i2c_bus_number

inherited

The bus number to use for I2C Grove twigs.

The exposed I2C bus is usually 1 or 2. This is normally auto-detected by detect_i2c_bus_number() called by the constructor, and doesn't need to be manually set.

Referenced by SG::GroveI2CDigital::GroveI2CDigital().

◆ i2c_file_handle

int SG::GroveI2CDigital::i2c_file_handle

inherited

The file handle to /dev/i2c-* used to communicate with the Grove device.

Referenced by SG::GroveI2CDigital::GroveI2CDigital(), SG::GroveI2CDigital::write_block(), and SG::GroveI2CDigital::~GroveI2CDigital().

◆ most_recent_gain

EGain SG::ThreeAxisDigitalCompass::most_recent_gain

protected

Most recent gain.

Referenced by get_direction(), get_heading(), and set_config().

◆ most_recent_x

int16_t SG::ThreeAxisDigitalCompass::most_recent_x

protected

Most recent value read by get_data().

Referenced by get_data(), get_direction(), and get_heading().

◆ most_recent_y

int16_t SG::ThreeAxisDigitalCompass::most_recent_y

protected

Most recent value read by get_data().

Referenced by get_data(), get_direction(), and get_heading().

◆ most_recent_z

int16_t SG::ThreeAxisDigitalCompass::most_recent_z

protected

Most recent value read by get_data().

Referenced by get_data().

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

src-groves/sg_101020034_3AxisCompass.hpp
src-groves/sg_101020034_3AxisCompass.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ I2CAddress

◆ I2CBlock

◆ I2CBus

◆ I2CRegister

Member Enumeration Documentation

◆ EDataOutputRate

◆ EGain

◆ EMeasurements

◆ EMode

◆ ERegister

Constructor & Destructor Documentation

◆ ~ThreeAxisDigitalCompass()

◆ ThreeAxisDigitalCompass()

Member Function Documentation

◆ detect_i2c_bus_number()

◆ gain_to_digital_resolution()

◆ get_address_from_type() [1/2]

◆ get_address_from_type() [2/2]

◆ get_config() [1/2]

◆ get_config() [2/2]

◆ get_data()

◆ get_description()

◆ get_direction() [1/3]

◆ get_direction() [2/3]

◆ get_direction() [3/3]

◆ get_heading() [1/3]

◆ get_heading() [2/3]

◆ get_heading() [3/3]

◆ get_mode()

◆ get_name()

◆ get_single_measurement()

◆ get_sku()

◆ get_status()

◆ get_type()

◆ get_type_name()

◆ is_analog()

◆ is_data_locked()

◆ is_data_ready()

◆ is_digital()

◆ is_grove_gpio()

◆ is_grove_i2c()

◆ is_grove_uart()

◆ is_regulator_enabled()

◆ operator!=()

◆ operator==()

◆ read12()

◆ read16()

◆ read8()

◆ read_block()

◆ reset()

◆ set_config() [1/2]

◆ set_config() [2/2]

◆ set_declination()

◆ set_mode()

◆ to_string() [1/4]

◆ to_string() [2/4]

◆ to_string() [3/4]

◆ to_string() [4/4]

◆ wait_for_significant_change()

◆ write16()

◆ write8()

◆ write_block() [1/2]

◆ write_block() [2/2]

◆ write_byte()

Member Data Documentation

◆ declination_degrees

◆ declination_radians

◆ grove_name

◆ grove_type

◆ i2c_address

◆ i2c_bus_number

◆ i2c_file_handle

◆ most_recent_gain