uBit.accelerometer

Overview

Onboard the micro:bit is an accelerometer, and it is linked to the i2c bus which is used to read data from the accelerometer.

The accelerometer on the micro:bit detects the acceleration (in milli-g) in 3 planes: x and y (the horizontal planes), and z (the vertical plane).

As well as detecting acceleration, accelerometers can also detect orientation, which is used in smart phones and tablets to rotate content as you tilt the device. This means that the micro:bit can infer its own orientation as well!

As well as being used to detect acceleration, accelerometers are also used to detect the rate of deceleration. A great example of an application of accelerometers are airbags in modern vehicles, where an accelerometer is used to detect the rapid deceleration of a vehicle. If rapid deceleration were to occur, the airbags are deployed.

Accelerometers can also be used to detect when an object is in free fall, which is when only the force gravity is acting upon an object. If you were to throw a ball directly into the air, free fall would begin as soon as the ball begins its decent after the acceleration from your throw has subsided.

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

Real time updates

When using the standard uBit presentation, the accelerometer 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]() calls. Additionally, if you would like to drive accelerometer updates manually updateSample() can be used.

Device initialisation

When the accelerometer object is created it attempts to detect which accelerometer is on board and creates an instance of the corresponding class. If no device is detected a MicroBitAccelerometer object is created that will throw an 050 error if the program attempts to interact with the accelerometer.

This is done by creating an i2c object and passing it to the MicroBitAccelerometer::autoDetect() function. This then scans the given I2C bus for supported accelerometer devices and returns the appropriate driver.

i2c(I2C_SDA0, I2C_SCL0),
accelerometer(MicroBitAccelerometer::autoDetect(i2c)),

Message Bus ID

Constant Value
MICROBIT_ID_ACCELEROMETER 4
MICROBIT_ID_GESTURE 27

Message Bus Events:

MICROBIT_ID_ACCELEROMETER

Constant Value
MICROBIT_ACCELEROMETER_EVT_DATA_UPDATE 1

MICROBIT_ID_GESTURE

Constant Value
MICROBIT_ACCELEROMETER_EVT_TILT_UP 1
MICROBIT_ACCELEROMETER_EVT_TILT_DOWN 2
MICROBIT_ACCELEROMETER_EVT_TILT_LEFT 3
MICROBIT_ACCELEROMETER_EVT_TILT_RIGHT 4
MICROBIT_ACCELEROMETER_EVT_FACE_UP 5
MICROBIT_ACCELEROMETER_EVT_FACE_DOWN 6
MICROBIT_ACCELEROMETER_EVT_FREEFALL 7
MICROBIT_ACCELEROMETER_EVT_3G 8
MICROBIT_ACCELEROMETER_EVT_6G 9
MICROBIT_ACCELEROMETER_EVT_8G 10
MICROBIT_ACCELEROMETER_EVT_SHAKE 11

API

Constructor


MicroBitAccelerometer(
MicroBitI2C &
_i2c)

Description

Constructor. Create a software abstraction of an accelerometer.

Parameters

MicroBitI2C &
_i2c - an instance of MicroBitI2C used to communicate with the onboard accelerometer.

Example
 MicroBitI2C i2c = MicroBitI2C(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer = MicroBitAccelerometer(i2c);


MicroBitAccelerometer(
MicroBitI2C &
_i2c,
uint16_t
address)

Description

Constructor. Create a software abstraction of an accelerometer.

Parameters

MicroBitI2C &
_i2c - an instance of MicroBitI2C used to communicate with the onboard accelerometer.

uint16_t
address - the default I2C address of the accelerometer. Defaults to: MMA8653_DEFAULT_ADDR.

Example
 MicroBitI2C i2c = MicroBitI2C(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer = MicroBitAccelerometer(i2c);


MicroBitAccelerometer(
MicroBitI2C &
_i2c,
uint16_t
address,
uint16_t
id)

Description

Constructor. Create a software abstraction of an accelerometer.

Parameters

MicroBitI2C &
_i2c - an instance of MicroBitI2C used to communicate with the onboard accelerometer.

uint16_t
address - the default I2C address of the accelerometer. Defaults to: MMA8653_DEFAULT_ADDR.

uint16_t
id - the unique EventModel id of this component. Defaults to: MICROBIT_ID_ACCELEROMETER

Example
 MicroBitI2C i2c = MicroBitI2C(I2C_SDA0, I2C_SCL0); 

 MicroBitAccelerometer accelerometer = MicroBitAccelerometer(i2c);

configure


int
configure
()

Description

Configures the accelerometer for G range and 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 on success, MICROBIT_I2C_ERROR if the accelerometer could not be configured.

updateSample


int
updateSample
()

Description

Reads the acceleration data from the accelerometer, and stores it in our buffer. This only happens if the accelerometer indicates that it has new data via int1.

On first use, this member function will attempt to add this component to the list of fiber components in order to constantly update the values stored by this object.

This technique is called lazy instantiation, and it means that we do not obtain the overhead from non-chalantly adding this component to fiber components.

Returns

MICROBIT_OK on success, MICROBIT_I2C_ERROR if the read request fails.

setPeriod


int
setPeriod
(
int
period)

Description

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

Parameters

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

Returns

MICROBIT_OK on success, MICROBIT_I2C_ERROR is the request fails.

Example
 // sample rate is now 20 ms. 
 accelerometer.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 accelerometer.

Returns

The time between samples, in milliseconds.

setRange


int
setRange
(
int
range)

Description

Attempts to set the sample range of the accelerometer to the specified value (in g).

Parameters

int
range - The requested sample range of samples, in g.

Returns

MICROBIT_OK on success, MICROBIT_I2C_ERROR is the request fails.

Example
 // the sample range of the accelerometer is now 8G. 
 accelerometer.setRange(8);

Note

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

getRange


int
getRange
()

Description

Reads the currently configured sample range of the accelerometer.

Returns

The sample range, in g.

whoAmI


int
whoAmI
()

Description

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

Returns

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

Example
 accelerometer.whoAmI();

getX


int
getX
()

Description

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

Returns

The force measured in the X axis, in milli-g.

Example
 accelerometer.getX();


int
getX
(
MicroBitCoordinateSystem
system)

Description

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

Parameters

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

Returns

The force measured in the X axis, in milli-g.

Example
 accelerometer.getX();

getY


int
getY
()

Description

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

Returns

The force measured in the Y axis, in milli-g.

Example
 accelerometer.getY();


int
getY
(
MicroBitCoordinateSystem
system)

Description

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

Parameters

MicroBitCoordinateSystem
system

Returns

The force measured in the Y axis, in milli-g.

Example
 accelerometer.getY();

getZ


int
getZ
()

Description

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

Returns

The force measured in the Z axis, in milli-g.

Example
 accelerometer.getZ();


int
getZ
(
MicroBitCoordinateSystem
system)

Description

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

Parameters

MicroBitCoordinateSystem
system

Returns

The force measured in the Z axis, in milli-g.

Example
 accelerometer.getZ();

getPitch


int
getPitch
()

Description

Provides a rotation compensated pitch of the device, based on the latest update retrieved from the accelerometer.

Returns

The pitch of the device, in degrees.

Example
 accelerometer.getPitch();

getPitchRadians


float
getPitchRadians
()

Description

Provides a rotation compensated pitch of the device, based on the latest update retrieved from the accelerometer.

Returns

The pitch of the device, in radians.

Example
 accelerometer.getPitchRadians();

getRoll


int
getRoll
()

Description

Provides a rotation compensated roll of the device, based on the latest update retrieved from the accelerometer.

Returns

The roll of the device, in degrees.

Example
 accelerometer.getRoll();

getRollRadians


float
getRollRadians
()

Description

Provides a rotation compensated roll of the device, based on the latest update retrieved from the accelerometer.

Returns

The roll of the device, in radians.

Example
 accelerometer.getRollRadians();

getGesture


uint16_t
getGesture
()

Description

Retrieves the last recorded gesture.

Returns

The last gesture that was detected.

Example
 MicroBitDisplay display; 

 if (accelerometer.getGesture() == SHAKE) 
 display.scroll("SHAKE!");