micro:bit pairing and over the air firmware updates
---------------------------------------------------

Version: 1.0
Date   : 17th September 2015
Authors: Joe Finney (j.finney@lancaster.ac.uk) and Martin Woolley (mwoolley@bluetooth.com)

Terminology
-----------
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 https://devzone.nordicsemi.com/documentation/nrf51/4.4.1/html/group__dfu__ble__service__spec.html 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 Control 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 "Pairing
Mode". 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 pairing mode by scrolling "PAIRING MODE!" across the display.

Once in the pairin mode 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 pairing 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 pairing mode 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 pairing 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.


UUIDs
-----
MicroBit DFU Service      : E95D93B0-251D-470A-A062-FA1922DFA9A8
  Control Characteristic  : E95D93B1-251D-470A-A062-FA1922DFA9A8
  FlashCode Characteristic: E95D93B2-251D-470A-A062-FA1922DFA9A8
  
Nordic DFU Service        : 00001530-1212-EFDE-1523-785FEABCD123

