BBC micro:bit Bluetooth Profile#
Introduction#
The BBC micro:bit ships with a default Bluetooth profile included in the run-time firmware.
The profile consists of various “services” and “characteristics” designed to give easy access to the micro:bit’s hardware so that initial exploration of the device’s capabilities may take place using a corresponding application on another, compatible Bluetooth device such as a smartphone.
Given the nature of micro:bit and the tools which will be available to developers, it will be possible for the profile to be partly or completely changed and replaced with a profile of the developer’s own design. The latter case is out of scope for this document which focuses on the standard, default profile only.
Reference documentation: micro:bit Bluetooth profile specification
Credits#
The Bluetooth profile for micro:bit is the result of a close collaboration between Martin Woolley of Bluetooth SIG (Twitter: @bluetooth_mdw) and Dr Joe Finney of Lancaster University.
Profile Design#
micro:bit acts as a Bluetooth GAP Peripheral and advertises so that GAP Central devices such as a smart phone can discover and connect to it.
Standard Bluetooth SIG “adopted” services have been used where appropriate in conjunction with custom services designed specifically for micro:bit.
The micro:bit default profile is based around the capabilities and features of the micro:bit device itself. It is not tightly coupled to any particular application of the device such as video control or telephony. It is however able to indicate actions it wishes a connected client device to perform or signal events that have occurred and which the client is expected to act upon in some way.
All services are “primary services” and so may be discovered and enumerated by a client wishing to determine the capabilities of the device.
Ease of use has been considered to be more important than having absolute configurability of all aspects of the hardware in the default profile.
The profile was designed using Bluetooth Developer Studio, a free of charge tool available for download from www.bluetooth.com
Bluetooth Security#
micro:bit uses standard Bluetooth security. Bluetooth defines a series of optional security features of which the following are used for micro:bit:
-
Pairing with passkey and MITM protection
-
White Listing
-
Encrypted link for operations involving most characteristics
Pairing equips the micro:bit and a trusted peer device with the potential to perform security operations when interacting such as utilising an AES 128 bit encrypted link. All interactions involving custom services except for the DFU Control Service must be performed over an encrypted link. Note that encryption will be automatically applied whenever required. If a peer device is not paired with the micro:bit and a secure operation is attempted it will be rejected and the usual, expected behaviour of the peer is that it will initiate the pairing process automatically.
White listing allows paired devices only to connect to and interact with the micro:bit. Attempts to connect from devices not in the white list are ignored by the Bluetooth Link Layer.
Advertising#
The micro:bit will advertise if in “pairing mode” or if it has been previously paired/bonded in which case it will advertise but a white list will be active and connections will only be accepted from previously paired devices. See below for more information on pairing.
In pairing mode the micro:bit will advertise with flags set indicating it is discoverable (LE General Discoverable Mode) as showing here:
In “normal mode” (i.e. not pairing mode) advertising packets have neither the LE Limited Discoverable mode or the LE General Discoverable Mode flags set and so in this situation may not be listed in the “available Bluetooth devices” screen of some smartphones which have not paired with the micro:bit. This is by design.
Pairing#
To interact with any service on the micro:bit the peer device must first be paired/bonded with it.
How to pair your BBC micro:bit with an Android phone or tablet from Martin Woolley on Vimeo.
To pair with a micro:bit it must first be placed in “pairing mode”. To do this, hold down both buttons A and B and press and hold the reset button. If powered by USB, let go of the reset button but keep holding both buttons A and B down. This will result in the micro:bit going into pairing mode and the words “PAIRING MODE” should be seen scrolling across the display followed by the graphical representation of the micro:bit 5 character identifier.
Next, initiate pairing on the peer device. On Android for example, go into Settings/Bluetooth and allow the system to scan for and discover the advertising micro:bit. Select it and pairing will commence. The micro:bit will indicate it’s ready to pair by displaying an arrow which points left towards button A. Press button A and a 6 digit number will be displayed on the micro:bit, one digit at a time. The peer device should now allow you to enter the 6 digit pass key. Do so and if the correct number was entered into the peer, micro:bit will display a tick/check to indicate pairing was achieved.
A maximum of 4 devices may be paired with a micro:bit simultaneously (note though that only one paired device may connect to the micro:bit at a time).
Reference Documentation#
Details of the micro:bit’s Bluetooth services, characteristics, the operations they each support and any associated descriptors along with UUID values can be found in the associated micro:bit Bluetooth profile specification
A simplified overview appears below.
GATT Services#
| Service | Type | micro:bit optionality | Description |
|---|---|---|---|
| Generic Access Service | Adopted | mandatory | Provides generic information about the device. Mandatory in GATT profiles. |
| Generic Attribute Service | Adopted | mandatory | Can inform clients of changes in the attribute table such as reassigned handle values.Mandatory in GATT profiles. |
| Device Information Service | Adopted | mandatory | Provides more comprehensive details about the device and its manufacturer |
| Accelerometer Service | Custom | optional | Provides access to the accelerometer sensor state and configuration of the frequency with which readings are reported. |
| Magnetometer Service | Custom | optional | Provides access to the magnetometer sensor state and configuration of the frequency with which readings are reported. Provides access to a “current bearing” value in degrees. |
| Temperature Service | Custom | optional | Provides access to a simplified, integer temperature measurement in celsius, derived from several sensors in the micro:bit. |
| Button Service | Custom | optional | Allow button state changes to be notified to the client |
| LED Service | Custom | optional | Allows access to both the LED “display” grid and the system status LED |
| IO Pin Service | Custom | optional | Allows access to and configuration of IO pins on the edge connector. |
| Event Service | Custom | optional | Allows the micro:bit to inform the connected client of the types of event it wants to be informed about. Allows the client to inform the micro:bit of relevant events. Allows micro:bit to inform the client of events originating on the micro:bit.Event data includes both a type and a reason or origin. |
| DFU Control Service | Custom | mandatory | Used to initiate device firmware update. Defined by Nordic Semiconductor. |
| UART Service | Custom | optional | Provides pseudo serial data communications over Bluetooth low energy, allowing arbitrary byte sequences to be exchanged in either direction with a connected peer. Data from micro:bit to peer is transmitted using Bluetooth Indications. Data from the peer to the micro:bit is transmitted using Write or Write No Response PDUs. This is an implementation of Nordic Semicondutor’s UART/Serial Port Emulation over Bluetooth low energy. |
The maximum number of bytes which may be transmitted in one PDU is limited to the MTU minus three or 20 octets to be precise.
See https://developer.nordicsemi.com/nRF5_SDK/nRF51_SDK_v8.x.x/doc/8.0.0/s110/html/a00072.html for the original Nordic Semiconductor documentation by way of background.
Note: This service was added after micro:bits initially shipped to school and so is not in the default image. |
Known issue: the firmware on micro:bits shipped initially to schools contains the full Bluetooth profile. Once the software has been changed by flashing an application created using any of the on-line code editors however, all services are lost except for Device Information Service, Event Service and DFU Control Service. If you need other services you must restore your micro:bit to its original state by installing the default hex file or better still this hex file which does not use the display so you can use it over Bluetooth instead.
The following sections elaborate on the description of a service and/or its characteristics. For full details see the micro:bit Bluetooth profile specification
About the Device Information Service#
This is an adopted service which defines 9 characteristics, all of which are optional members of of the service. For micro:bit we chose to include 3 of those characteristics only.
About the Accelerometer Service#
Characteristics#
Accelerometer Data : Contains accelerometer measurements for X, Y and Z axes as 3 unsigned 16 bit values in that order and in little endian format. Data can be read on demand or notified periodically. Values are in the range +/-1000 and in milli-newtons.
Accelerometer Period: Determines the frequency with which accelerometer data is reported in milliseconds. Valid values are 1, 2, 5, 10, 20, 80, 160 and 640.
About the Magnetometer Service#
Characteristics#
Magnetometer Data : Contains magnetometer measurements for X, Y and Z axes as 3 unsigned 16 bit values in that order and in little endian format. Data can be read on demand or notified periodically.
Magnetometer Period : Determines the frequency with which magnetometer data is reported in milliseconds. Valid values are 1, 2, 5, 10, 20, 80, 160 and 640.
Magnetometer Bearing : Compass bearing in degrees from North.
Note: to deliver meaningful data the micro:bit magnetometer must first be calibrated. The calibration procedure can be triggered by simply using the compass in your micro:bit program, or adding the MicroBitMagnetometer Bluetooth service to your Bluetooth profile*.
* from v2.0.0 of the runtime onwards.
About the Temperature Service#
Characteristics#
Temperature : Signed integer 8 bit value in celsius.
Temperature Period : Determines the frequency with which temperature data is updated in milliseconds.
About the Button Service#
The Button Service exposes the two buttons on the micro:bit and allows their state to be read on demand by a connected client or the client to subscribe to notifications of state change. 3 button states are defined and represented by a simple numeric enumeration: 0 = not pressed, 1 = pressed, 2 = long press.
About the LED Service#
The service provides the client with direct control of each individual LED in the display grid. The client may also work at a higher level of abstraction and send strings of text to be displayed one character at a time on the LED display, with configurable scrolling transitions from one character to the next.
A single characteristic containing a 32 bit mask (7 bits are unused) represents all 25 LEDs with a 0 bit indicating LED OFF and a 1 indicating LED ON. The characteristic may be written or read in a single GATT operation allowing efficient manipulation of all LEDs in the grid.
Other characteristics allow a text string to be written to it by the client for display and the scrolling delay may be set.
Characteristics#
LED Matrix State : Allows the state of any|all LEDs in the 5x5 grid to be set to on or off with a single GATT operation. Consists of a 32 bit field with bits 0 - 24 representing the off (0) or on (1) state of the corresponding LED.
LED Text : A UTF-8 string to be shown on the LED display. Maximum length 20 octets.
Scrolling Delay : Specifies a millisecond delay to wait for in between showing each character on the display.
About the IO Pin Service#
Characteristics#
Pin Data : Contains data relating to zero or more pins. Structured as a variable length array of up to 19 Pin Number / Value pairs. Pin Number and Value are each uint8 fields. Note however that the micro:bit has a 10 bit ADC and so values are compressed to 8 bits with a loss of resolution.
WRITE: Clients may write values to one or more pins in a single GATT write operation. A pin to which a value is to be written must have been configured for output using the Pin IO Configuration characteristic. Any attempt to write to a pin which is configured for input will be ignored.
NOTIFY: Notifications will deliver Pin Number / Value pairs for those pins defined as input pins by the Pin IO Configuration characteristic and whose value when read differs from the last read of the pin.
READ: A client reading this characteristic will receive Pin Number / Value pairs for all those pins defined as input pins by the Pin IO Configuration characteristic.
The associated Pin AD Configuration characteristic allows the client to indicate how each pin is to be used, as either an analogue or a digital pin.
Pin IO Configuration : A bit mask (32 bit) which defines which inputs will be read. If the Pin AD Configuration bit mask is also set the pin will be read as an analogue input, if not it will be read as a digital input.
Note that in practice, setting a pin’s mask bit means that it will be read by the micro:bit runtime and, if notifications have been enabled on the Pin Data characteristic, data read will be transmitted to the connected Bluetooth peer device in a Pin Data notification. If the pin’s bit is clear, it simply means that it will not be read by the micro:bit runtime. By default, pins are configured for output.
Pin AD Configuration : A bit mask which allows each pin to be configured for analogue or digital use. Bit n corresponds to pin n where 0 <= n < 19. A value of 0 means digital and 1 means analogue.
PWM Control : Allows a client to use up to 2 micro:bit pins at a time for PWM output and to set the period and value of the pin(s). This is useful for applications such as the analogue control of LEDs and simple audio tone generation. Note that not all pins support PWM on micro:bit.
About the Event Service#
The Event Service allows events or commands to be notified to the micro:bit by a connected client and it allows micro:bit to notify the connected client of events or commands originating from with the micro:bit. The micro:bit can inform the client of the types of event it is interested in being informed about (e.g. an incoming call) and the client can inform the micro:bit of types of event it wants to be notified about. The term “event” will be used here for both event and command types of data.
Events may have an associated value.
Note that specific event ID values including any special values such as those which may represent wild cards are not defined here. The micro:bit run time documentation should be consulted for this information.
Multiple events of different types may be notified to the client or micro:bit at the same time.
Event data is encoded as an array of structs each encoding an event of a given type together with an associated value. Event Type and Event Value are both defined as uint16 and therefore the length of this array will always be a multiple of 4.
| struct event { uint16 event_type; uint16 event_value;}; | | — |
event_type and event_value are each encoded in little endian format.
The Event Service has four characteristics in total:
micro:bit Requirements is a variable length list of event data structures which indicates the types of client event, potentially with a specific value which the micro:bit wishes to be informed of when they occur. The client should read this characteristic when it first connects to the micro:bit. It may also subscribe to notifications to that it can be informed if the value of this characteristic is changed by the micro:bit firmware.
Note that an event_type of zero means ANY event type and an event_value part set to zero means ANY event value.
Client Requirements is a variable length list of event data structures which indicates the types of micro:bit event, potentially with a specific value which the client wishes to be informed of when they occur. The client should write to this characteristic when it first connects to the micro:bit.
Note that an event_type of zero means ANY event type and an event_value part set to zero means ANY event value.
micro:bit Event contains one or more event structures which should be notified to the client. It supports notifications and as such the client should subscribe to notifications from this characteristic.
Client Event is a writable characteristic which the client may write one or more event structures to, to inform the micro:bit of events which have occurred on the client. These should be of types indicated in the micro:bit Requirements characteristic bit mask.
About the DFU Control Service#
Allows clients to initiate the micro:bit pairing and over the air firmware update procedures. Firmware updates are actually handled by the Nordic Semiconductor DFU service which is not part of this profile, after the micro:bit enters an alternate bootloader.
Characteristics#
DFU Control : Writing 0x01 initiates rebooting the micro:bit into the Nordic Semiconductor bootloader if the DFU Flash Code characteristic has been written to with the correct secret key. Writing 0x02 to this characteristic means “request flash code”.
About the UART Service#
Provides a pseudo serial interface to the micro:bit for the exchange of arbitrary sequences of bytes. A maximum of 20 octets (MTU of 23 minus 3) can be transmitted in a single operation but a series of operations can be executed to affect something like serial data communications.
This is an implementation of the Nordic Semiconductor UART service:
https://developer.nordicsemi.com/nRF5_SDK/nRF51_SDK_v8.x.x/doc/8.0.0/s110/html/a00072.html
Characteristics#
TX Characteristic: Allows the micro:bit to transmit a byte array containing an arbitrary number of arbitrary octet values to a connected device. Uses Indications for this purpose.
RX Characteristic: Allows a connected client to send a byte array containing an arbitrary number of arbitrary octet values to a connected micro:bit using with Write Requests or Write Commands.
Using the Bluetooth Profile#
Click on the Bluetooth menu and then select one of the Bluetooth services for a page of information dedicated to that service including information for application developers.
Martin Woolley’s personal blog contains a series of micro:bit Bluetooth demonstration videos. See http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html
The Android application featured in the videos was written by Martin and contains a series of demonstrations, each exercising at least one of the micro:bit Bluetooth services. The application available in github. Information regarding the use of each service appears in the individual service pages of this site.