PROFILE
A custom Bluetooth profile for the BBC micro:bit Martin Woolley Bluetooth SIG Twitter: @bluetooth_mdw
Version 1.11 - 28th July 2017 Added Magnetometer Calibration characteristic to the Magnetometer Service Added support for Write Without Response to the Client Event characteristic Version 1.10 - 1st September 2016 Added PWM support to the IO Pin Service by adding the PWM Control characteristic. Specified that characteristics in the IO Pin Service are all optional (but at least one must be included). Version 1.9 - 27th April 2016 Added Nordic Semiconductor UART service Version 1.8 - 30th March 2016 - Not Released Version 1.7 - 22nd January 2016 Standard Bluetooth pairing and security are now used. Specifically: 1. Pairing with passkey and MITM protection 2. White Listing 3. Encrypted link for most operations All services except Generic Access, Generic Attribute, Device Information and DFU Control Service designated OPTIONAL DFU Control Service has lost the the DFU Flash Code characteristic since we're now using standard Bluetooth pairing. Changed names of button characteristics to use A and B instead of 1 and 2 Revised 5 byte representation of the LED Matrix: Octet 0, LED Row 1: bit4 bit3 bit2 bit1 bit0 Octet 1, LED Row 2: bit4 bit3 bit2 bit1 bit0 Octet 2, LED Row 3: bit4 bit3 bit2 bit1 bit0 Octet 3, LED Row 4: bit4 bit3 bit2 bit1 bit0 Octet 4, LED Row 5: bit4 bit3 bit2 bit1 bit0 Maximum length of LED Text documented. Changed name of "Scrolling Speed" characteristic to "Scrolling Delay". Reinstated Manufacturer Name String characteristic to the Device Information Service. DFU Control characteristic given the READ property Documented supported values the accelerometer and magnetometer period characteristics can take. Documented magic event type/value of zero Documented event type/value are little endian Version 1.6 - 17th October 2015 Removed the Battery Service. No way to establish battery levels on the micro:bit Added a simple Temperature Service to exploit temperature sensors in micro:bit processors with Temperature and Temperature Period characteristics. Accelerometer and Magnetometer period characteristics now have uint16 fields instead of uint8 which required scaling up by multipling by 10. Accelerometer Data and Magnetometer Data characteristics now use signed 16 bit integer fields for each of their X, Y and Z parts. Accelerometer Data and Magnetometer Data characteristics now use signed 16 bit integer fields for each of their X, Y and Z parts. New characteristic Magnetometer Heading added to the Magnetometer Service. Provides current heading in degrees. Removed IO Parallel Port characteristic due to complexity and memory considerations. Added Generic Attribute Service (previously absent in the repository) Changed the LED Matrix State characteristic field so that we now have one octet per row of LEDs for ease of use. Version 1.5 - 10th September 2015 Button State 2 characteristic given new, distinct UUID of E95DDA91-251D-470A-A062-FA1922DFA9A8 Removed the System LED State characteristic from the LED Service since it cannot be controlled from the BLE MCU. Removed the Scrolling State characteristic from the LED Service due to complexity and memory constraints. Changed LED Matrix State use of “Write Without Response” to “Write” so that no further writes can be made until there’s been an ACK back from the previous one. Removed Write property from MicroBit Requirements characteristic.
SERVICES
Generic Access
The generic_access service contains generic information about the device. All available Characteristics are readonly.
Generic Access - CHARACTERISTICS
Device Name
1. Name : utf8s |
Appearance
The external appearance of this device. The values are composed of a category (10-bits) and sub-categories (6-bits).
1. Category : 16bit |
Peripheral Preferred Connection Parameters
1. Minimum Connection Interval : uint16 |
2. Maximum Connection Interval : uint16 |
3. Slave Latency : uint16 |
4. Connection Supervision Timeout Multiplier : uint16 |
Generic Attribute
Generic Attribute - CHARACTERISTICS
Service Changed
1. Start of Affected Attribute Handle Range : uint16 |
2. End of Affected Attribute Handle Range : uint16 |
1. Client Characteristic Configuration : 2902 |
Device Information
The Device Information Service exposes manufacturer and/or vendor information about a device.
This service exposes manufacturer information about a device. The Device Information Service is instantiated as a Primary Service. Only one instance of the Device Information Service is exposed on a device.
Device Information - CHARACTERISTICS
Model Number String
The value of this characteristic is a UTF-8 string representing the model number assigned by the device vendor.
1. Model Number : utf8s |
Serial Number String
The value of this characteristic is a variable-length UTF-8 string representing the serial number for a particular instance of the device.
1. Serial Number : utf8s |
Hardware Revision String
The value of this characteristic is a UTF-8 string representing the hardware revision for the hardware within the device.
1. Hardware Revision : utf8s |
Firmware Revision String
The value of this characteristic is a UTF-8 string representing the firmware revision for the firmware within the device.
1. Firmware Revision : utf8s |
Manufacturer Name String
The value of this characteristic is a UTF-8 string representing the name of the manufacturer of the device.
1. Manufacturer Name : utf8s |
ACCELEROMETER SERVICE
Exposes accelerometer data. An accelerometer is an electromechanical device that will measure acceleration forces. These forces may be static, like the constant force of gravity pulling at your feet, or they could be dynamic - caused by moving or vibrating the accelerometer. Value contains fields which represent 3 separate 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.
ACCELEROMETER SERVICE - CHARACTERISTICS
Accelerometer Data
Contains accelerometer measurements for X, Y and Z axes as 3 signed 16 bit values in that order and in little endian format. X, Y and Z values should be divided by 1000.
1. Accelerometer_X : sint16 |
2. Accelerometer_Y : sint16 |
3. Accelerometer_Z : sint16 |
1. Client Characteristic Configuration : 2902 |
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.
1. Accelerometer_Period : uint16 |
MAGNETOMETER SERVICE
Exposes magnetometer data. A magnetometer measures a magnetic field such as the earth's magnetic field in 3 axes.
MAGNETOMETER SERVICE - CHARACTERISTICS
Magnetometer Data
Contains magnetometer measurements for X, Y and Z axes as 3 signed 16 bit values in that order and in little endian format. Data can be read on demand or notified periodically.
1. Magnetometer_X : sint16 |
2. Magnetometer_Y : sint16 |
3. Magnetometer_Z : sint16 |
1. Client Characteristic Configuration : 2902 |
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.
1. Magnetometer_Period : uint16 |
Magnetometer Bearing
Compass bearing in degrees from North.
1. bearing value : uint16 |
1. Client Characteristic Configuration : 2902 |
Magnetometer Calibration
0 - state unknown 1 - calibration requested 2 - calibration completed OK 3 - calibration completed with error
1. calibration field : uint8 |
1. Client Characteristic Configuration : 2902 |
Button Service
Exposes the two Micro Bit buttons and allows 'commands' associated with button state changes to be associated with button states and notified to a connected client.
Button Service - CHARACTERISTICS
Button A State
State of Button A may be read on demand by a connected client or the client may 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.
1. Button_State_Value : uint8 |
1. Client Characteristic Configuration : 2902 |
Button B State
State of Button B may be read on demand by a connected client or the client may 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.
1. Button_State_Value : uint8 |
1. Client Characteristic Configuration : 2902 |
IO PIN SERVICE
Provides read/write access to I/O pins, individually or collectively. Allows configuration of each pin for input/output and analogue/digital use.
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. OPERATIONS: 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.
1. IO_Pin_Data : uint8[] |
1. Client Characteristic Configuration : 2902 |
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 LESS THAN OR EQUAL TO n LESS THAN 19. A value of 0 means digital and 1 means analogue.
1. Pin_AD_Config_Value : uint24 |
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. Bit n corresponds to pin n where 0 LESS THAN OR EQUAL TO n LESS THAN 19. A value of 0 means configured for output and 1 means configured for input.
1. Pin_IO_Config_Value : uint24 |
PWM Control
A variable length array 1 to 2 instances of : struct PwmControlData { uint8_t pin; uint16_t value; uint32_t period; } Period is in microseconds and is an unsigned int but transmitted. Value is in the range 0 – 1024, per the current DAL API (e.g. setAnalogValue). 0 means OFF. Fields are transmitted over the air in Little Endian format.
1. PWM Control Field : uint8[] |
LED SERVICE
Provides access to and control of LED state. Allows the state (ON or OFF) of all 25 LEDs to be set in a single write operation. Allows short text strings to be sent by a client for display on the LED matrix and scrolled across at a speed controlled by the Scrolling Delay characteristic.
LED SERVICE - 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 an array of 5 x utf8 octets, each representing one row of 5 LEDs. Octet 0 represents the first row of LEDs i.e. the top row when the micro:bit is viewed with the edge connector at the bottom and USB connector at the top. Octet 1 represents the second row and so on. In each octet, bit 4 corresponds to the first LED in the row, bit 3 the second and so on. Bit values represent the state of the related LED: off (0) or on (1). So we have: Octet 0, LED Row 1: bit4 bit3 bit2 bit1 bit0 Octet 1, LED Row 2: bit4 bit3 bit2 bit1 bit0 Octet 2, LED Row 3: bit4 bit3 bit2 bit1 bit0 Octet 3, LED Row 4: bit4 bit3 bit2 bit1 bit0 Octet 4, LED Row 5: bit4 bit3 bit2 bit1 bit0
1. LED_Matrix_State : uint8[] |
LED Text
A short UTF-8 string to be shown on the LED display. Maximum length 20 octets.
1. LED_Text_Value : utf8s |
Scrolling Delay
Specifies a millisecond delay to wait for in between showing each character on the display.
1. Scrolling_Delay_Value : uint16 |
EVENT SERVICE
A generic, bi-directional event communication 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 SERVICE - CHARACTERISTICS
MicroBit Requirements
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. struct event { uint16 event_type; uint16 event_value; }; Note that an event_type of zero means ANY event type and an event_value part set to zero means ANY event value. event_type and event_value are each encoded in little endian format.
1. microbit_reqs_value : uint8[] |
1. Client Characteristic Configuration : 2902 |
MicroBit 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. struct event { uint16 event_type; uint16 event_value; };
1. Event_Type_And_Value : uint8[] |
1. Client Characteristic Configuration : 2902 |
Client Requirements
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. struct event { uint16 event_type; uint16 event_value; }; Note that an event_type of zero means ANY event type and an event_value part set to zero means ANY event value. event_type and event_value are each encoded in little endian format.
1. Client_Requirements_Value : uint8[] |
Client Event
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. struct event { uint16 event_type; uint16 event_value; };
1. Event_Types_And_Values : uint8[] |
DFU CONTROL SERVICE
Allows clients to initiate the micro:bit pairing and over the air firmware update procedures.
DFU CONTROL SERVICE - 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".
1. dfu_control : uint8 |
TEMPERATURE SERVICE
Ambient temperature derived from several internal temperature sensors on the micro:bit
TEMPERATURE SERVICE - CHARACTERISTICS
Temperature
Signed integer 8 bit value in degrees celsius.
1. temperature value : sint8 |
1. Client Characteristic Configuration : 2902 |
Temperature Period
Determines the frequency with which temperature data is updated in milliseconds.
1. temperature period value : uint16 |
UART SERVICE
This is an implementation of Nordic Semicondutor's UART/Serial Port Emulation over Bluetooth low energy. 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.
UART SERVICE - CHARACTERISTICS
TX Characteristic
This characteristic allows the micro:bit to transmit a byte array containing an arbitrary number of arbitrary octet values to a connected device. 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.
1. UART TX Field : uint8[] |
RX Characteristic
This characteristic allows a connected client to send a byte array containing an arbitrary number of arbitrary octet values to a connected micro:bit. 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.
1. UART TX Field : uint8[] |