Ctrl+K

EVNCompassSensor

EVNCompassSensor#

This class provides the following features and functionalities for our Compass Sensor Standard Peripheral (HMC5883L / QMC5883L IC):

  • Drift-free Yaw Measurements

    • Since this measures heading using the earth’s geomagnetic field, magnets (like those in motors) can result in poor readings when placed too close to the sensor

    • Compasses are also susceptible to local hard-iron and soft-iron interference. We will be adding functions and a tutorial on calibrating to local environments soon!

  • Non-Blocking & Blocking Read Functions

  • Configurable Timing Budget for Readings

  • Built-in I2C Port Selection and De-selection

Note

This class does I2C port selection automatically, so users do not need to call setPort() using their EVNAlpha objects.

Wiring (I2C)#

Host

Peripheral

Description

3V3

VCC

3.3V Power

GND

GND

Ground (0V)

SCL

SCL

I2C Serial Clock

SDA

SDA

I2C Serial Data

–

DRDY

Not Connected

Constructor#

class EVNCompassSensor(uint8_t port, float hard_x = 0, float hard_y = 0, float hard_z = 0, float soft_x_0 = 1, float soft_x_1 = 0, float soft_x_2 = 0, float soft_y_0 = 0, float soft_y_1 = 1, float soft_y_2 = 0, float soft_z_0 = 0, float soft_z_1 = 0, float soft_z_2 = 1)#
Parameters

  • port – I2C port the sensor is connected to (1-16)

  • hard_x – X-axis hard iron calibration value. Defaults to 0

  • hard_y – Y-axis hard iron calibration value. Defaults to 0

  • hard_z – Z-axis hard iron calibration value. Defaults to 0

  • soft_x_0 – X-axis soft iron calibration value 0. Defaults to 1

  • soft_x_1 – X-axis soft iron calibration value 1. Defaults to 0

  • soft_x_2 – X-axis soft iron calibration value 2. Defaults to 0

  • soft_y_0 – Y-axis soft iron calibration value 0. Defaults to 0

  • soft_y_1 – Y-axis soft iron calibration value 1. Defaults to 1

  • soft_y_2 – Y-axis soft iron calibration value 2. Defaults to 0

  • soft_z_0 – Z-axis soft iron calibration value 0. Defaults to 0

  • soft_z_1 – Z-axis soft iron calibration value 1. Defaults to 0

  • soft_z_2 – Z-axis soft iron calibration value 2. Defaults to 1

Since advanced sensor settings are different depending on which sensor model you have, sensor settings can only be changed using the functions below.

These are the defaults:
  • QMC Model:

    • Data Rate: COMPASS_QMC_HZ_200

    • Range: COMPASS_QMC_GA_2

    • Samples per Reading: COMPASS_QMC_X512

  • HMC Model:

    • Data Rate: COMPASS_HMC_HZ_75

    • Range: COMPASS_HMC_GA_4

    • Samples per Reading: COMPASS_HMC_X1

Functions#

bool begin()

Initializes compass sensor. Call this function before using the other functions.

Returns

Boolean indicating whether the sensor was successfully initialized. If false is returned, all other functions will return 0.

bool isQMC()
Returns

true if the sensor has a QMC chip, false otherwise

bool isHMC()
Returns

true if the sensor has a HMC chip, false otherwise

bool isCalibrated()
Returns

true if the sensor has been supplied with calibration values, false otherwise

void setCalibration(float hard_x = 0, float hard_y = 0, float hard_z = 0, float soft_x_0 = 1, float soft_x_1 = 0, float soft_x_2 = 0, float soft_y_0 = 0, float soft_y_1 = 1, float soft_y_2 = 0, float soft_z_0 = 0, float soft_z_1 = 0, float soft_z_2 = 1)
Parameters

  • hard_x – X-axis hard iron calibration value. Defaults to 0

  • hard_y – Y-axis hard iron calibration value. Defaults to 0

  • hard_z – Z-axis hard iron calibration value. Defaults to 0

  • soft_x_0 – X-axis soft iron calibration value 0. Defaults to 1

  • soft_x_1 – X-axis soft iron calibration value 1. Defaults to 0

  • soft_x_2 – X-axis soft iron calibration value 2. Defaults to 0

  • soft_y_0 – Y-axis soft iron calibration value 0. Defaults to 0

  • soft_y_1 – Y-axis soft iron calibration value 1. Defaults to 1

  • soft_y_2 – Y-axis soft iron calibration value 2. Defaults to 0

  • soft_z_0 – Z-axis soft iron calibration value 0. Defaults to 0

  • soft_z_1 – Z-axis soft iron calibration value 1. Defaults to 0

  • soft_z_2 – Z-axis soft iron calibration value 2. Defaults to 1

Reading Yaw / Heading#

float read(bool blocking = true)

Get yaw measurement (i.e. heading) from sensor

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

Yaw measurement (from 0-360deg)

..function:: void setNorth(void)

Set current yaw as North (heading = 0).

Reading Magnetometer Values#

float readRawX()
Returns

raw X-axis magnetometer measurement (in uT)

float readRawY()
Returns

raw Y-axis magnetometer measurement (in uT)

float readRawZ()
Returns

raw Z-axis magnetometer measurement (in uT)

float readCalX()

Ensure that the sensor has received calibration values for this function to work properly.

Returns

calibrated X-axis magnetometer measurement (in uT)

float readCalY()

Ensure that the sensor has received calibration values for this function to work properly.

Returns

calibrated Y-axis magnetometer measurement (in uT)

float readCalZ()

Ensure that the sensor has received calibration values for this function to work properly.

Returns

calibrated Z-axis magnetometer measurement (in uT)

Sensor Settings#

void setMode(bool enable)

Sets mode to run sensor in

Parameters

enable – Whether measurement is enabled

The compass measures along 3 different axes (X, Y and Z). This image depicts the 3 axes of the sensor. As a quick reference, the sensor PCB has markings for the X and Y axis. By default, the X axis is set as the axis passing through the front of the robot, and the Z axis as the axis passing through the top of the robot.

However, the Compass Sensor Standard Peripheral can be mounted in many orientations, hence the functions below can be used to set the correct axes.

void setTopAxis(uint8_t axis)
Parameters

axis – Sensor axis that passes through the top of the robot (options shown below)

  • AXIS_X

  • AXIS_Y

  • AXIS_Z

void setFrontAxis(uint8_t axis)
Parameters

axis – Sensor axis that passes through the front of the robot (options shown below)

  • AXIS_X

  • AXIS_Y

  • AXIS_Z

Advanced Sensor Settings (HMC)#

void setDataRateHMC(hmc_data_rate data_rate)
Parameters

data_rate – Rate at which the sensor takes measurements

  • COMPASS_HMC_HZ_0_75 (0.75Hz)

  • COMPASS_HMC_HZ_1_5 (1.5Hz)

  • COMPASS_HMC_HZ_3 (3Hz)

  • COMPASS_HMC_HZ_7_5 (7.5Hz)

  • COMPASS_HMC_HZ_15 (15Hz)

  • COMPASS_HMC_HZ_30 (30Hz)

  • COMPASS_HMC_HZ_75 (75Hz)

void setRangeHMC(hmc_range range)
Parameters

range – Measurable magnetic range of readings (in Gauss)

  • COMPASS_HMC_GA_0_88 (+-0.88Ga)

  • COMPASS_HMC_GA_1_3 (+-1.3Ga)

  • COMPASS_HMC_GA_1_9 (+-1.9Ga)

  • COMPASS_HMC_GA_2_5 (+-2.5Ga)

  • COMPASS_HMC_GA_4 (+-4Ga)

  • COMPASS_HMC_GA_4_7 (+-4.7Ga)

  • COMPASS_HMC_GA_5_6 (+-5.6Ga)

  • COMPASS_HMC_GA_8_1 (+-8.1Ga)

void setSamplingRateHMC(hmc_sampling samples)
Parameters

samples – Number of samples taken per reading

  • COMPASS_HMC_SAMPLING_X1 (1)

  • COMPASS_HMC_SAMPLING_X2 (2)

  • COMPASS_HMC_SAMPLING_X4 (4)

  • COMPASS_HMC_SAMPLING_X8 (8)

Advanced Sensor Settings (QMC)#

void setDataRateQMC(qmc_data_rate data_rate)
Parameters

data_rate – Rate at which the sensor takes measurements

  • COMPASS_QMC_HZ_10 (10Hz)

  • COMPASS_QMC_HZ_50 (50Hz)

  • COMPASS_QMC_HZ_100 (100Hz)

  • COMPASS_QMC_HZ_200 (200Hz)

void setRangeQMC(qmc_range range)
Parameters

range – Measurable magnetic range of readings (in Gauss)

  • COMPASS_QMC_GA_2 (+-2Ga)

  • COMPASS_QMC_GA_8 (+-8Ga)

void setSamplingRateQMC(qmc_sampling samples)
Parameters

samples – Number of samples taken per reading

  • COMPASS_QMC_SAMPLING_X64 (64)

  • COMPASS_QMC_SAMPLING_X128 (128)

  • COMPASS_QMC_SAMPLING_X256 (256)

  • COMPASS_QMC_SAMPLING_X512 (512)

Contents