Seeed Grove ++  v0.0.1-2386
Linux C++ Library For Seeed Grove Devices
SG::ThreeAxisDigitalCompass Class Reference

3-axis digital compass. More...

#include <sg_101020034_3AxisCompass.hpp>

Inheritance diagram for SG::ThreeAxisDigitalCompass:
Collaboration diagram for SG::ThreeAxisDigitalCompass:

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 ThreeAxisDigitalCompassreset (void)
 Reset the configuration to default values. More...
 
virtual ThreeAxisDigitalCompassset_mode (const EMode mode=EMode::kSingleMeasurement)
 Set the operating mode. More...
 
virtual EMode get_mode (void)
 Get the operating mode. More...
 
virtual ThreeAxisDigitalCompassset_config (const EDataOutputRate output_rate, const EMeasurements measurements)
 Set the output rate and measurement bias. More...
 
virtual ThreeAxisDigitalCompassget_config (EDataOutputRate &output_rate, EMeasurements &measurements)
 Get the output rate and measurement bias. More...
 
virtual ThreeAxisDigitalCompassset_config (const EGain gain)
 Set the device gain. More...
 
virtual ThreeAxisDigitalCompassget_config (EGain &gain)
 Get the device gain. More...
 
virtual ThreeAxisDigitalCompassget_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 ThreeAxisDigitalCompassget_status (bool &regulator_enabled, bool &data_locked, bool &data_ready)
 Get status information. More...
 
virtual ThreeAxisDigitalCompassset_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 GroveI2CDigitalwrite_byte (const uint8_t value)
 Write a single byte to the I2C bus. More...
 
virtual GroveI2CDigitalwrite_block (const I2CRegister reg, const I2CBlock &v)
 Write a consecutive block of bytes, anywhere between 1 and 32 bytes in length. More...
 
virtual GroveI2CDigitalwrite_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 GroveI2CDigitalwrite8 (const I2CRegister reg, const uint8_t value)
 Write the given value to the specified register. More...
 
virtual GroveI2CDigitalwrite16 (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.
sg_101020034_3AxisDigitalCompass_2.jpg
3-axis digital compass connected to BBG.
sg_101020034_3AxisDigitalCompass_1.jpg

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

i2cdetect -y -r 2
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- 1e --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- UU UU UU UU -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --

Example source:

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:

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

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

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

Measurement bias.

See also
get_config()
set_config()
Enumerator
kNormal 

default value

kPositiveBias 
kNegativeBias 

◆ EMode

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

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_detectThe 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_numberIf 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_errorif /dev cannot be opened.
std::runtime_errorif 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]

◆ 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:

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.

Example source:

// 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()

◆ 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:

// ...
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]xMeasurement value from channel X.
[out]yMeasurement value from channel Y.
[out]zMeasurement value from channel Z.
[in]milliseconds_to_waitThe 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:

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_enabledThis is set when the internal voltage regulator is enabled. This is cleared when the internal regulator is disabled.
[out]data_lockedThis 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_readyThis 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_errorif 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_errorif 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_errorif 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:

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]declinationSet 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:

// 3Hz update rate means we'll have a new reading available every 333 milliseconds (1000ms/3=333.3ms)
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]xMeasurement value from channel X.
[in,out]yMeasurement value from channel Y.
[in,out]zMeasurement value from channel Z.
[in]milliseconds_to_waitThe length of time to wait for a signficant change. If set to zero, then wait_for_significant_change() will wait forever.
[in]deltaDetermines 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_errorif 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_errorif 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_errorif the block is too long to write.
std::system_errorif 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_errorif 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_errorif 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

◆ grove_name

std::string SG::GroveBase::grove_name
inherited

User-supplied name.

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

◆ grove_type

◆ 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: