uBit.compass¶

Overview¶

Onboard the micro:bit is an electronic magnetometer. Like the accelerometer, the
magnetometer is linked to the i2c bus, which is used to access data on the magnetometer.

The magnetometer provides information about the magnetic field where a micro:bit is situated, crucially providing an indication of where magnetic North is located.

Raw magnetic field information alone is not enough to provide accurate compass headings. Therefore, the accelerometer is used in conjunction with the magnetometer to reduce the inaccuracy of the magnetometer reading.

The magnetometer is inaccurate because it considers all 3 planes: x, y and z. The heading North only exists in the horizontal planes (x and y), therefore we only need values in these planes. The accelerometer is used to filter out the vertical plane (z) to make our headings far more accurate. You can see this in action when calibrating the compass.

After calibration has been performed, the end product is an e-compass!

There are two variants of the micro:bit , one uses the NXP MAG3110 and the other a uses the ST LSM303 combined accelerometer and magnetometer.

Real time updates¶

When using the standard uBit presentation, the compass is continuously updated in the background using an idle thread (after it is first used), which is executed whenever the micro:bit has no other tasks to perform.

If there is no scheduler running, the values are synchronously read on get[X,Y,Z]() and heading() calls. Additionally, if you would like to drive compass updates manually updateSample() can be used.

Device initialisation¶

When the compass object is created it attempts to detect which magnetometer is on board. If no device is detected a magnetometer object is created that will throw an 051 error if a program attempts to interact with the compass.

The compass relies on the accelerometer to calculate it's orientation and will fail to initialise if no accelerometer is detected.

In order to calibrate the compass a display object is required, plus an optional storage object that will store the calibration in persistent FLASH.

storage(),
i2c(I2C_SDA0, I2C_SCL0),
display(),
accelerometer(MicroBitAccelerometer::autoDetect(i2c)),
compass(MicroBitCompass::autoDetect(i2c)),
compassCalibrator(compass, accelerometer, display, storage), // Storage is optional

Message Bus ID¶

Constant	Value
MICROBIT_ID_COMPASS	5

Message Bus Events¶

Constant	Value
MICROBIT_COMPASS_EVT_CAL_REQUIRED	1 (DEPRECATED)
MICROBIT_COMPASS_EVT_CAL_START	2 (DEPRECATED)
MICROBIT_COMPASS_EVT_CAL_END	3 (DEPRECATED)
MICROBIT_COMPASS_EVT_DATA_UPDATE	4
MICROBIT_COMPASS_EVT_CONFIG_NEEDED	5
MICROBIT_COMPASS_EVT_CALIBRATE	6

API¶

Constructor¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
MicroBitStorage &
_storage)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitAccelerometer &
_accelerometer - an instance of the accelerometer, used for tilt compensation.

MicroBitStorage &
_storage - an instance of MicroBitStorage , used to persist calibration data across resets.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer(i2c); 

 MicroBitStorage storage; 

 MicroBitCompass compass(i2c, accelerometer, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
MicroBitStorage &
_storage,
uint16_t
address)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitAccelerometer &
_accelerometer - an instance of the accelerometer, used for tilt compensation.

MicroBitStorage &
_storage - an instance of MicroBitStorage , used to persist calibration data across resets.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer(i2c); 

 MicroBitStorage storage; 

 MicroBitCompass compass(i2c, accelerometer, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
MicroBitStorage &
_storage,
uint16_t
address,
uint16_t
id)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitAccelerometer &
_accelerometer - an instance of the accelerometer, used for tilt compensation.

MicroBitStorage &
_storage - an instance of MicroBitStorage , used to persist calibration data across resets.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

uint16_t
id - the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer(i2c); 

 MicroBitStorage storage; 

 MicroBitCompass compass(i2c, accelerometer, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitAccelerometer &
_accelerometer - an instance of the accelerometer, used for tilt compensation.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer(i2c); 

 MicroBitCompass compass(i2c, accelerometer, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
uint16_t
address)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitAccelerometer &
_accelerometer - an instance of the accelerometer, used for tilt compensation.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer(i2c); 

 MicroBitCompass compass(i2c, accelerometer, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
uint16_t
address,
uint16_t
id)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitAccelerometer &
_accelerometer - an instance of the accelerometer, used for tilt compensation.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

uint16_t
id - the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer(i2c); 

 MicroBitCompass compass(i2c, accelerometer, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitStorage &
_storage)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitStorage &
_storage - an instance of MicroBitStorage , used to persist calibration data across resets.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitStorage storage; 

 MicroBitCompass compass(i2c, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitStorage &
_storage,
uint16_t
address)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitStorage &
_storage - an instance of MicroBitStorage , used to persist calibration data across resets.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitStorage storage; 

 MicroBitCompass compass(i2c, storage);

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitStorage &
_storage,
uint16_t
address,
uint16_t
id)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

MicroBitStorage &
_storage - an instance of MicroBitStorage , used to persist calibration data across resets.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

uint16_t
id - the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitStorage storage; 

 MicroBitCompass compass(i2c, storage);

MicroBitCompass(
MicroBitI2C &
_i2c)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitCompass compass(i2c);

MicroBitCompass(
MicroBitI2C &
_i2c,
uint16_t
address)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitCompass compass(i2c);

MicroBitCompass(
MicroBitI2C &
_i2c,
uint16_t
address,
uint16_t
id)¶

Description¶

Constructor. Create a software representation of an e-compass.

Parameters¶

MicroBitI2C &
_i2c - an instance of i2c, which the compass is accessible from.

uint16_t
address - the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.

uint16_t
id - the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.

Example¶

 MicroBitI2C i2c(I2C_SDA0, I2C_SCL0); 

 MicroBitCompass compass(i2c);

configure¶

int

configure
()¶

Description¶

Configures the compass for the sample rate defined in this object. The nearest values are chosen to those defined that are supported by the hardware. The instance variables are then updated to reflect reality.

Returns¶

MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be configured.

setPeriod¶

int

setPeriod
(
int
period)¶

Description¶

Attempts to set the sample rate of the compass to the specified value (in ms).

Parameters¶

int
period - the requested time between samples, in milliseconds.

Returns¶

MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be updated.

Example¶

 // sample rate is now 20 ms. 
 compass.setPeriod(20);

Note

The requested rate may not be possible on the hardware. In this case, the nearest lower rate is chosen.

getPeriod¶

int

getPeriod
()¶

Description¶

Reads the currently configured sample rate of the compass.

Returns¶

The time between samples, in milliseconds.

heading¶

int

heading
()¶

Description¶

Gets the current heading of the device, relative to magnetic north.

If the compass is not calibrated, it will raise the MICROBIT_COMPASS_EVT_CALIBRATE event.

Users wishing to implement their own calibration algorithms should listen for this event, using MESSAGE_BUS_LISTENER_IMMEDIATE model. This ensures that calibration is complete before the user program continues.

Returns¶

the current heading, in degrees. Or MICROBIT_CALIBRATION_IN_PROGRESS if the compass is calibrating.

Example¶

 compass.heading();

whoAmI¶

int

whoAmI
()¶

Description¶

Attempts to read the 8 bit ID from the magnetometer, this can be used for validation purposes.

Returns¶

the 8 bit ID returned by the magnetometer, or MICROBIT_I2C_ERROR if the request fails.

Example¶

 compass.whoAmI();

getX¶

int

getX
()¶

Description¶

Reads the value of the X axis from the latest update retrieved from the magnetometer.

Returns¶

The magnetic force measured in the X axis, in nano teslas.

Example¶

 compass.getX();

int

getX
(
MicroBitCoordinateSystem
system)¶

Description¶

Reads the value of the X axis from the latest update retrieved from the magnetometer.

Parameters¶

MicroBitCoordinateSystem
system - The coordinate system to use. By default, a simple cartesian system is provided.

Returns¶

The magnetic force measured in the X axis, in nano teslas.

Example¶

 compass.getX();

getY¶

int

getY
()¶

Description¶

Reads the value of the Y axis from the latest update retrieved from the magnetometer.

Returns¶

The magnetic force measured in the Y axis, in nano teslas.

Example¶

 compass.getY();

int

getY
(
MicroBitCoordinateSystem
system)¶

Description¶

Reads the value of the Y axis from the latest update retrieved from the magnetometer.

Parameters¶

MicroBitCoordinateSystem
system - The coordinate system to use. By default, a simple cartesian system is provided.

Returns¶

The magnetic force measured in the Y axis, in nano teslas.

Example¶

 compass.getY();

getZ¶

int

getZ
()¶

Description¶

Reads the value of the Z axis from the latest update retrieved from the magnetometer.

Returns¶

The magnetic force measured in the Z axis, in nano teslas.

Example¶

 compass.getZ();

int

getZ
(
MicroBitCoordinateSystem
system)¶

Description¶

Reads the value of the Z axis from the latest update retrieved from the magnetometer.

Parameters¶

MicroBitCoordinateSystem
system - The coordinate system to use. By default, a simple cartesian system is provided.

Returns¶

The magnetic force measured in the Z axis, in nano teslas.

Example¶

 compass.getZ();

getFieldStrength¶

int

getFieldStrength
()¶

Description¶

Determines the overall magnetic field strength based on the latest update from the magnetometer.

Returns¶

The magnetic force measured across all axis, in nano teslas.

Example¶

 compass.getFieldStrength();

readTemperature¶

int

readTemperature
()¶

Description¶

Reads the current die temperature of the compass.

Returns¶

the temperature in degrees celsius, or MICROBIT_I2C_ERROR if the temperature reading could not be retreived from the accelerometer.

calibrate¶

int

calibrate
()¶

Description¶

Perform a calibration of the compass.

This method will be called automatically if a user attempts to read a compass value when the compass is uncalibrated. It can also be called at any time by the user.

The method will only return once the compass has been calibrated.

Returns¶

MICROBIT_OK, MICROBIT_I2C_ERROR if the magnetometer could not be accessed, or MICROBIT_CALIBRATION_REQUIRED if the calibration algorithm failed to complete successfully.

Note

THIS MUST BE CALLED TO GAIN RELIABLE VALUES FROM THE COMPASS

setCalibration¶

void

setCalibration
(
CompassSample
calibration)¶

Description¶

Configure the compass to use the calibration data that is supplied to this call.

Calibration data is comprised of the perceived zero offset of each axis of the compass.

After calibration this should now take into account trimming errors in the magnetometer, and any "hard iron" offsets on the device.

calibration

A CompassSample containing the offsets for the x, y and z axis.

Parameters¶

CompassSample
calibration - A CompassSample containing the offsets for the x, y and z axis.

getCalibration¶

CompassSample

getCalibration
()¶

Description¶

Provides the calibration data currently in use by the compass.

More specifically, the x, y and z zero offsets of the compass.

Returns¶

calibration A CompassSample containing the offsets for the x, y and z axis.

updateSample¶

int

updateSample
()¶

Description¶

Updates the local sample, only if the compass indicates that data is stale.

Note

Can be used to trigger manual updates, if the device is running without a scheduler. Also called internally by all getX,Y,Z member functions.

isCalibrated¶

int

isCalibrated
()¶

Description¶

Returns 0 or 1. 1 indicates that the compass is calibrated, zero means the compass requires calibration.

isCalibrating¶

int

isCalibrating
()¶

Description¶

Returns 0 or 1. 1 indicates that the compass is calibrating, zero means the compass is not currently calibrating.

clearCalibration¶

void

clearCalibration
()¶

Description¶

Clears the calibration held in persistent storage, and sets the calibrated flag to zero.

uBit.compass¶

Overview¶

Real time updates¶

Device initialisation¶

Message Bus ID¶

Message Bus Events¶

API¶

Constructor¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitAccelerometer & _accelerometer, MicroBitStorage & _storage)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitAccelerometer & _accelerometer, MicroBitStorage & _storage, uint16_t address)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitAccelerometer & _accelerometer, MicroBitStorage & _storage, uint16_t address, uint16_t id)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitAccelerometer & _accelerometer)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitAccelerometer & _accelerometer, uint16_t address)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitAccelerometer & _accelerometer, uint16_t address, uint16_t id)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitStorage & _storage)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitStorage & _storage, uint16_t address)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, MicroBitStorage & _storage, uint16_t address, uint16_t id)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, uint16_t address)¶

Description¶

Parameters¶

Example¶

MicroBitCompass( MicroBitI2C & _i2c, uint16_t address, uint16_t id)¶

Description¶

Parameters¶

Example¶

configure¶

int configure()¶

Description¶

Returns¶

setPeriod¶

int setPeriod( int period)¶

Description¶

Parameters¶

Returns¶

Example¶

getPeriod¶

int getPeriod()¶

Description¶

Returns¶

heading¶

int heading()¶

Description¶

Returns¶

Example¶

whoAmI¶

int whoAmI()¶

Description¶

Returns¶

Example¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
MicroBitStorage &
_storage)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
MicroBitStorage &
_storage,
uint16_t
address)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
MicroBitStorage &
_storage,
uint16_t
address,
uint16_t
id)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
uint16_t
address)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitAccelerometer &
_accelerometer,
uint16_t
address,
uint16_t
id)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitStorage &
_storage)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitStorage &
_storage,
uint16_t
address)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
MicroBitStorage &
_storage,
uint16_t
address,
uint16_t
id)¶

MicroBitCompass(
MicroBitI2C &
_i2c)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
uint16_t
address)¶

MicroBitCompass(
MicroBitI2C &
_i2c,
uint16_t
address,
uint16_t
id)¶

int

configure
()¶

int

setPeriod
(
int
period)¶

int

getPeriod
()¶

int

heading
()¶

int

whoAmI
()¶

int

getX
()¶

int

getX
(
MicroBitCoordinateSystem
system)¶

int

getY
()¶

int

getY
(
MicroBitCoordinateSystem
system)¶

int

getZ
()¶

int

getZ
(
MicroBitCoordinateSystem
system)¶

int

getFieldStrength
()¶

int

readTemperature
()¶

int

calibrate
()¶

void

setCalibration
(
CompassSample
calibration)¶

CompassSample

getCalibration
()¶

int

updateSample
()¶

int

isCalibrated
()¶

int

isCalibrating
()¶

void

clearCalibration
()¶