Skip to content

accelerometer

AccelerometerPeriod module-attribute #

AccelerometerPeriod = Union[
    Literal[1],
    Literal[2],
    Literal[5],
    Literal[10],
    Literal[20],
    Literal[80],
    Literal[160],
    Literal[640],
]

The interval at which the Accelerometer is read is an integer and expresses the number of milliseconds. There is a limited number of valid periods: 1, 2, 5, 10, 20, 80, 160, 640

Warning

These are the valid values according to the specification, but it seems that this does not work as I expect TODO to investigate

AccelerometerData dataclass #

The values of the 3 axes of an accelerometer measurement, in milli-g. (with g the gravitational acceleration on Earth)

Attributes:

  • x (int) –

    horizontal (left to right)

  • y (int) –

    horizontal (from back to front)

  • z (int) –

    vertical (from bottom to top)

Source code in src/kaspersmicrobit/services/accelerometer.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
@dataclass
class AccelerometerData:
    """
    The values of the 3 axes of an accelerometer measurement, in milli-g. (with g the gravitational acceleration on Earth)

    Attributes:
        x (int): horizontal (left to right)
        y (int): horizontal (from back to front)
        z (int): vertical (from bottom to top)
    """
    x: int
    y: int
    z: int

    @staticmethod
    def from_bytes(values: ByteData):
        return AccelerometerData(
            int.from_bytes(values[0:2], "little", signed=True),
            int.from_bytes(values[2:4], "little", signed=True),
            int.from_bytes(values[4:6], "little", signed=True)
        )

AccelerometerService #

This class contains the functions that can be used related to the accelerometer of the micro:bit

The accelerometer measures force/acceleration along 3 axes:

  • x: horizontal (from left to right)
  • y: horizontal (from back to front)
  • z: vertical (from bottom to top)

The values of x, y and z are integers and are values in milli-g, where 1 g, so 1000 milli-g, is equal to the gravitational acceleration on earth. In free fall the values along the axes will be approximately 0:

AccelerometerData(x=0, y=0, z=0)

When the micro:bit is directly in front of you with the buttons visible and the pins facing you, then a reading from the accelerometer will give (approximately) the following:

AccelerometerData(x=-50, y=-50, z=-1024)

That z is approximately -1000 (instead of 1000 as you might have expected) can be explained by measuring the force that stops the micro:bit (e.g. when you hold the micro:bit: the force that your arm exerts, and that prevents the micro:bit from falling)

If you tilt the micro:bit towards you from this starting position, then y and z increase in value and x remains approximately the same:

AccelerometerData(x=-28, y=972, z=-56)

If you tilt the micro:bit away from you from the starting position, then y decreases, z increases in value and x remains approximately the same:

AccelerometerData(x=-104, y=-960, z=124)

Tilt the micro:bit from the starting position to the left then x decreases, z increases in value and y remains approximately the same:

AccelerometerData(x=-1108, y=72, z=-160)

Tilt the micro:bit from the starting position to the right then x and z increase in value and y remains approximately the same:

AccelerometerData(x=960, y=60, z=0)

Turn the micro:bit completely upside down then z increases approximately to 1000 and x and y remain approximately the same:

AccelerometerData(x=-56, y=-36, z=1024)

These are all options offered by the accelerometer Bluetooth service

See Also: https://lancaster-university.github.io/microbit-docs/ble/accelerometer-service/

See Also: https://lancaster-university.github.io/microbit-docs/ubit/accelerometer/

Source code in src/kaspersmicrobit/services/accelerometer.py 
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
class AccelerometerService:
    """
    This class contains the functions that can be used related to the accelerometer of the micro:bit

    The accelerometer measures force/acceleration along 3 axes:

    - x: horizontal (from left to right)
    - y: horizontal (from back to front)
    - z: vertical (from bottom to top)

    The values of x, y and z are integers and are values in milli-g, where 1 g, so 1000 milli-g, is equal to the
    gravitational acceleration on earth. In free fall the values along the axes will be approximately 0:

        AccelerometerData(x=0, y=0, z=0)

    When the micro:bit is directly in front of you with the buttons visible and the pins facing you,
    then a reading from the accelerometer will give (approximately) the following:

        AccelerometerData(x=-50, y=-50, z=-1024)

    That z is approximately -1000 (instead of 1000 as you might have expected) can be explained by measuring the force
    that stops the micro:bit (e.g. when you hold the micro:bit: the force that your arm exerts, and that
    prevents the micro:bit from falling)

    If you tilt the micro:bit towards you from this starting position,
    then y and z increase in value and x remains approximately the same:

        AccelerometerData(x=-28, y=972, z=-56)

    If you tilt the micro:bit away from you from the starting position,
    then y decreases, z increases in value and x remains approximately the same:

        AccelerometerData(x=-104, y=-960, z=124)

    Tilt the micro:bit from the starting position to the left
    then x decreases, z increases in value and y remains approximately the same:

        AccelerometerData(x=-1108, y=72, z=-160)

    Tilt the micro:bit from the starting position to the right
    then x and z increase in value and y remains approximately the same:

        AccelerometerData(x=960, y=60, z=0)

    Turn the micro:bit completely upside down
    then z increases approximately to 1000 and x and y remain approximately the same:

        AccelerometerData(x=-56, y=-36, z=1024)

    These are all options offered by the accelerometer Bluetooth service

    See Also: https://lancaster-university.github.io/microbit-docs/ble/accelerometer-service/

    See Also: https://lancaster-university.github.io/microbit-docs/ubit/accelerometer/
    """
    def __init__(self, device: BluetoothDevice):
        self._device = device

    def is_available(self) -> bool:
        """
        Checks whether the accelerometer Bluetooth service is found on the connected micro:bit.

        Returns:
            true if the accelerometer was found, false if not.
        """
        return self._device.is_service_available(Service.ACCELEROMETER)

    def notify(self, callback: Callable[[AccelerometerData], None]):
        """
        You can call this method when you want to be notified of new accelerometer data. How often you
        receive new data depends on the accelerometer period

        Args:
            callback (Callable[[AccelerometerData], None]): a function that is called when there is new data
                from the accelerometer. The new AccelerometerData is passed as an argument to this function

        Raises:
            errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
                activate accelerometer data notifications (normally does not occur)
        """
        self._device.notify(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_DATA,
                            lambda sender, data: callback(AccelerometerData.from_bytes(data)))

    def read(self) -> AccelerometerData:
        """
        Reads the accelerometer data.

        Returns:
            The accelerometer data (x, y and z)

        Raises:
            errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
                read accelerometer data (normally does not occur)
        """
        return AccelerometerData.from_bytes(self._device.read(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_DATA))

    def set_period(self, period: AccelerometerPeriod):
        """
        Sets the interval at which the accelerometer takes measurements (in milliseconds).

        Args:
            period (AccelerometerPeriod): the interval at which the accelerometer takes measurements,
                valid values are: 1, 2, 5, 10, 20, 80, 160, 640

        Raises:
            errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
                change accelerometer period (normally does not occur)

        Warning:
            These are the valid values according to the specification, but it seems that this does not work as I expect
            TODO to investigate
        """
        self._device.write(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_PERIOD, period.to_bytes(2, "little"))

    def read_period(self) -> int:
        """
        Returns the interval at which the accelerometer takes measurements

        Returns:
            The interval in milliseconds

        Raises:
            errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
                accelerometer period to be read (normally does not occur)
        """
        return int.from_bytes(self._device.read(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_PERIOD)[0:2], "little")

is_available #

is_available() -> bool

Checks whether the accelerometer Bluetooth service is found on the connected micro:bit.

Returns:

  • bool –

    true if the accelerometer was found, false if not.

Source code in src/kaspersmicrobit/services/accelerometer.py 
106
107
108
109
110
111
112
113
def is_available(self) -> bool:
    """
    Checks whether the accelerometer Bluetooth service is found on the connected micro:bit.

    Returns:
        true if the accelerometer was found, false if not.
    """
    return self._device.is_service_available(Service.ACCELEROMETER)

notify #

notify(callback: Callable[[AccelerometerData], None])

You can call this method when you want to be notified of new accelerometer data. How often you receive new data depends on the accelerometer period

Parameters:

  • callback (Callable[[AccelerometerData], None]) –

    a function that is called when there is new data from the accelerometer. The new AccelerometerData is passed as an argument to this function

Raises:

Source code in src/kaspersmicrobit/services/accelerometer.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def notify(self, callback: Callable[[AccelerometerData], None]):
    """
    You can call this method when you want to be notified of new accelerometer data. How often you
    receive new data depends on the accelerometer period

    Args:
        callback (Callable[[AccelerometerData], None]): a function that is called when there is new data
            from the accelerometer. The new AccelerometerData is passed as an argument to this function

    Raises:
        errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
            activate accelerometer data notifications (normally does not occur)
    """
    self._device.notify(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_DATA,
                        lambda sender, data: callback(AccelerometerData.from_bytes(data)))

read #

read() -> AccelerometerData

Reads the accelerometer data.

Returns:

Raises:

Source code in src/kaspersmicrobit/services/accelerometer.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
def read(self) -> AccelerometerData:
    """
    Reads the accelerometer data.

    Returns:
        The accelerometer data (x, y and z)

    Raises:
        errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
            read accelerometer data (normally does not occur)
    """
    return AccelerometerData.from_bytes(self._device.read(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_DATA))

set_period #

set_period(period: AccelerometerPeriod)

Sets the interval at which the accelerometer takes measurements (in milliseconds).

Parameters:

  • period (AccelerometerPeriod) –

    the interval at which the accelerometer takes measurements, valid values are: 1, 2, 5, 10, 20, 80, 160, 640

Raises:

Warning

These are the valid values according to the specification, but it seems that this does not work as I expect TODO to investigate

Source code in src/kaspersmicrobit/services/accelerometer.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def set_period(self, period: AccelerometerPeriod):
    """
    Sets the interval at which the accelerometer takes measurements (in milliseconds).

    Args:
        period (AccelerometerPeriod): the interval at which the accelerometer takes measurements,
            valid values are: 1, 2, 5, 10, 20, 80, 160, 640

    Raises:
        errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
            change accelerometer period (normally does not occur)

    Warning:
        These are the valid values according to the specification, but it seems that this does not work as I expect
        TODO to investigate
    """
    self._device.write(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_PERIOD, period.to_bytes(2, "little"))

read_period #

read_period() -> int

Returns the interval at which the accelerometer takes measurements

Returns:

  • int –

    The interval in milliseconds

Raises:

Source code in src/kaspersmicrobit/services/accelerometer.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
def read_period(self) -> int:
    """
    Returns the interval at which the accelerometer takes measurements

    Returns:
        The interval in milliseconds

    Raises:
        errors.BluetoothServiceNotFound: When the accelerometer service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the accelerometer service is running but there was no way to
            accelerometer period to be read (normally does not occur)
    """
    return int.from_bytes(self._device.read(Service.ACCELEROMETER, Characteristic.ACCELEROMETER_PERIOD)[0:2], "little")