Description of the pairing and FOTA process added to the documentation

This commit is contained in:
bluetooth-mdw 2015-09-17 16:25:23 +01:00
parent 9b05dc2708
commit 61fd503bba

View file

@ -0,0 +1,116 @@
micro:bit pairing and over the air firmware updates
Version: 1.0
Date : 17th September 2015
Authors: Joe Finney ( and Martin Woolley (
FOTA: Firmware Over The Air (Nordic's name)
DFU: Device Firmware Update (the process of using FOTA to reprogram a nordic chip)
A Tale of Two DFU GATT Services
The micro:bit possesses two BLE GATT services that are concerned with FOTA. Only one, however should be "visible" to a GATT client at any one time.
The first is the standard Nordic DFU service which has not been modified. See for further details.
The Nordic DFU service is *not* visible to clients most of the time and this is by design.
The second service is the MicroBit DFU Service. This service *is* active/visible in general.
Whilst the Nordic DFU service may not be visible to GATT clients most of the time, it is always resident in the top 20K or so of FLASH program memory.
Flashing the micro:bit OTA involves rebooting the micro:bit in a special way which results in the Nordic boot loader being entered and this brings up the Nordic DFU service instead of the MicroBit DFU service.
The MicroBit DFU Service
This service has two characteristics:
ControlPoint (unsigned 32 bits)
FlashCode (unsigned 32 bits)
The FlashCode characteristic is a primitive used for authentication. Every micro:bit has a unique code (derived from its unique serial ID).
Rebooting into the Nordic Bootloader
As described, to flash the device OTA we must first instruct the micro:bit to reboot into the Nordic boot loader to bring up the Nordic DFU service which will then process firmware OTA updates from the client.
To reboot the micro:bit into the Nordic bootloader, two things need to happen:
1) The FlashCode characteristic has to be written with the correct secret key
2) The ControlPoint characteristic has to be written with a value of 0x01
At this point the micro:bit should automatically reboot and bring up the Nordic DFU service.
Note that the user doesn't have to press the reboot button. Reboot takes place automatically.
Obtaining and Using the flash code
To be able to initiate the reboot into the Nordic boot loader therefore, the client must be in possession of the flash code. This gives us two scenarios to consider and essentially gives us a two stage process of which stage 1 is optional.
Either (1) the client does not possess the flash code and therefore must somehow obtain it or (2) it already has it from some previous interaction with the micro:bit and has cached it.
Stage 1 - Client Does Not Possess flash code
MicroBit has a special mode of operation or state known currently as "Blue Zone". The device enters this state when rebooted by pressing the reset button whilst at the same time holding down both buttons A and B. The device indicates itself to be in the Blue Zone mode by scrolling "BLUEZONE" across the display.
Once in the Blue Zone state, the MicroBit DFU Service also enables another command via the ControlPoint characteristic known as 'REQUEST_FLASHCODE' which is represented by a value of 0x02.
To obtain the flash code the client should enable GATT notifications on the FlashCode characteristic and then write 0x02 to the Control characteristic. The micro:bit will respond by displaying "PAIR?" on the LED display.
The user must now press Button A on the micro:bit. This is an "authorization to proceed" step and results in the client receiving the flash code value as a GATT notification which it can then store for use in the second stage and any subsequent execution of stage 2 without the need to execute the stage 1 procedure.
Stage 2 - Client in Possession of flash code
If a device already knows the flashcode, it can connect any time and initiate rebooting into "Nordic DFU mode" by writing the FlashCode characteristic with the previously cached value and then writing the 'ENTER NORDIC BOOTLOADER' command (0x01) to the Control characteristic. The device will reboot into the stock nordic bootloader and then the attached device can interact with that to reflash the device. The device does NOT need to be in Blue Zone mode.
Issues for Client Application Developers
It should be noted that rebooting into "Nordic DFU Mode" will break any existing BLE connection between the client device and micro:bit. The client will therefore need to re-establish its connection to the MicroBit before being able to proceed with FOTA and discover and then make use of the Nordic DFU service.
More About flash code
Each micro:bit has a secret key (flash code) derived from a 128 bit serial number that's etched onto every nordic nrf51822 during manufacture. All chips are different. Half of the serial number is hashed to generate the flash code.
micro:bit human identifiers
In addition to a secret key (flash code) used in the FOTA process as described, micro:bits have a human readable identifier (public name) which is included in BLE advertising packets and can be discovered and used by human users during any process, including FOTA, where there needs to be a confirmation that the device which is to be interacted with is the one the human intends to interact with. In the context of this document, "interact with" means update using the FOTA procedure.
The public name is generated by the run time from the other half of the Nordic serial number. Humans can discover the public name of a device by switching into BLUEZONE mode. The public name is displayed in a coded but simple graphical form on the LED display and can then be entered into (say) a mobile application screen to verify the device to be updated is the one we mean to update.
Summary of the FOTA Process
Case 1 - Client does not know the flash code
a) User switches micro:bit into BLUEZONE mode - must do this first since it involves a reboot and will therefore disconnect the client
b) Client connects to micro:bit
c) Client discovers MicroBit DFU service
d) Client enables notifications on the MicroBit DFU Service::FlashCode characteristic
e) Client writes 0x02 to the MicroBit DFU Service::Control characteristic
f) micro:bit displays "PAIR?" on the LED display
g) User presses Button A
h) Client should receive FlashCode notification containing the flash code value
We then proceed by following the steps for Case 2
Case 2 - Client is in Possession of flash code
i) Client writes the cached flash code value to the MicroBit DFU Service::FlashCode characteristic
Note: this is optional if following directly on from Case 1 as the FlashCode characterisitic would have been written locally by the micro:bit runtime
j) Client writes 0x01 to the MicroBit DFU Service::Control characteristic. This should cause the micro:bit to reboot into the Nordic boot loader. The Nordic DFU GATT service should become active and visible to GATT clients that subsequently connect and the MicroBit DFU Service should disappear.
k) Client reconnects to micro:bit and proceeds with FOTA per the Nordic documentation on using their DFU service.
MicroBit DFU Service : D8AF991C-7144-43D7-954B-99512F95F99C
Control Characteristic : 97109547-E63A-442A-BF89-9D730413DC2F
FlashCode Characteristic: 947B6934-64D1-4FAD-9BD0-CC9D6E9F3EA3
Nordic DFU Service : 00001530-1212-EFDE-1523-785FEABCD123