Setup & Testing

0%

Requirements

The hardware requirements for running the BLE Secure DFU Bootloader example are:

  • A development PC (Windows, Linux, or macOS) – for building the bootloader and application, and generating cryptographic keys.
  • One nRF52832 or nRF840 development kit – used as the DFU target (Note: In all the steps below, we’ll be using an nRF52840 DK).
  • A mobile phone (iOS or Android) – used as the DFU controller (alternatively, you could use a second nRF52 DK along with your development PC and use nRF Connect for Desktop)
  • [Optional] A Bluetooth sniffer to monitor and analyze the DFU process BLE packets. (I’ll be using the Ellisys Bluetooth Tracker).

The software requirements are:

  • nRF5 SDK version 15.3.0 – simply download and unzip to a folder of choice.
  • Segger Embedded Studio (SES) – download and install.
  • Python (and pip) – check out the following articles for installation instructions:
  • GNU ARM Embedded Toolchain
    • Download from the official website here – (version 4.9-2015-q3-update or newer).
    • Set your system’s path to include the <GNU ARM Tolchain>/bin folder – mostly needed for Linux and macOS. Windows will do this automatically during the installation of the toolchain.
    • Edit nRF5 SDK’s Makefile.posix file to point to the correct location of the GNU ARM Toolchain and indicate the correct version (you can find out the version by running arm-none-eabi-gcc –version). The Makefile.posix file is located at <nRF5 SDK Folder>/components/toolchain/gcc/Makefile.posix.
  • nRF Connect for Mobile (iOS, or Android) or nRF Connect for Desktop if you’re using a PC as the DFU controller.
  • nRF Command Line Tools – download the appropriate version for your operating system and install the two packages included (JLink installer & nRF Command Line Tools installer).
  • Git – follow this guide for instructions on how to install it for your specific operating system.
  • Set up the micro-ecc library:
    • Clone the GitHub repo. You can simply run the following command in your terminal or command prompt:
      git clone https://github.com/kmackay/micro-ecc.git
    • Make sure to clone it in the folder: <nRF5 SDK Folder>/external/micro-ecc/micro-ecc
    • Navigate to the folder <nRF5 SDK Folder>/external/micro-ecc/nrf52hf_armgcc/armgcc/
    • Note: the *hf* in the folder name above is used for chipsets that have an FPU (floating-point unit). If your target chipset does not include an FPU, then use the folder with *nf* in the name.
    • Build the library by running make
    • The output file will be linked when building the Secure Bootloader

Once you’ve got all the hardware and software installed, you’re ready to move on to the next step.

Adding OTA DFU Support to nRF52

Here are the general steps needed to add and perform Secure OTA DFU over BLE for your nRF52 project:

1 – Generate Private-Public Key Pair

  • Navigate to a folder of your choice for storing the private-public key pair files
  • Run the commands:
    nrfutil keys generate private.key
    nrfutil keys display --key pk --format code private.key --out_file public_key.c
  • These commands will create private-public key pair files.
  • For example,
    private.key:

    public_key.c:
  • The private key file must be secured and protected.
  • The public key file will be added to the BLE Secure DFU Bootloader project.

2 – Replace the Placeholder Public Key File

  • Open the example located at <nRF5 SDK Folder>/examples/dfu/secure_bootloader/pca10056_ble/ses/secure_bootloader_ble_s140_pca10056.emProject
  • Replace the file dfu_public_key.c with the one generated in step #1, or simply copy/paste the contents of public_key.c into dfu_public_key.c

3 – Build the BLE Secure DFU Bootloader

Build the BLE Secure DFU Bootloader example project (using Segger Embedded Studio).

4 – Flash the Bootloader and the SoftDevice to the nRF52 DK

  • Load both the Bootloader and the SoftDevice using SES
  • Choose the top menu “Target” ==> “Connect J-Link”.
  • Once connected, choose the top menu “Target” again ==> “Erase All”.
  • When that’s finished, we can now load the Bootloader and SoftDevice. Choose “Target” ==> “Download secure_bootloader_ble_s140_pca10056”.

 

5 – Verify BLE Secure Bootloader is running

  • After loading the images in the previous step, verify that both LED 1 and LED 2 are on.
  • Next, open up nRF Connect on Mobile (or Desktop ==> Bluetooth app) and verify that the device is advertising with the name “DfuTarg”:
  • This indicates that the BLE Secure DFU Bootloader is running correctly and ready to accept a new DFU package.

6 – Building the nRF52 Application

  • Next, we’ll build our nRF52 application in SES.
  • This is the application that we want to include in the DFU package.
  • Once you build it, locate the output .hex file.

7 – Generating the DFU Package

  • To generate the DFU package .zip file, we need to use the nrfutil command-line tool.
  • The command takes in the private key generated from step #1 and the .hex file from step #6.
  • In this example, we’ll be including the application only (no Bootloader or SoftDevice).
  • Copy the .hex file from step #6 (.hex file of the application) to the same location as the private key from step #1.
  • Now, run the following command:
  • Let’s look at each of the arguments passed into the command:
    • pkg: Display or generate a DFU package (zip file).
    • generate: Generate a zip file for performing DFU.
    • --hw-version 52: The hardware version.
    • --application-version 1: The assigned application version.
    • --application ble_app_blinky_pca10056_s140.hex: The application hex file to be included in the DFU package.
    • --sd-req 0xB6: The SoftDevice firmware ID(s) required for the update to be processed, of which one must be present on the target device. Below is the list of SoftDevice firmware IDs supported by version 5.2.0 of the nrfutil command-line tool. We are using SoftDevice s140 version 6.1.1 which matches ID value: 0xB6.
    • --sd-id 0xB6: The new SoftDevice ID to be used as –sd-req for the Application update in case the ZIP contains a SoftDevice and an Application.
    • --key-file private.key: The private (signing) key in PEM format.
    • app_dfu_package.zip: Name of the output ZIP file (the DFU package).

8 – Discover and Connect to the DFU Target

  • Use nRF Connect for Mobile (or nRF Connect for Desktop Bluetooth App with a second nRF52 DK connected to the PC) and look for the “DfuTarg” advertisement.
  • You’ll need to make sure the package you created in step #7 is accessible on the mobile phone you’re using (if you’re using nRF Connect for Mobile).
  • Now, connect to the DFU target:

9 – Start the DFU Process

  • After you’ve connected to the DFU target in nRF Connect on Mobile, swipe to the left twice to navigate to the DFU screen. Then click “Open Document Picker”:
  • Choose the .zip file (from step #7) and start the DFU process.
  • Click the “Start” button:

10 – New Firmware Application

  • Once the DFU process is complete, you should see that your new application (that was part of the DFU package) is now running on the DFU Target development kit.
    In this example, I used the ble_app_blinky peripheral application:

DFU Package Contents

In the example above we included only the application in the DFU package. However, in many other cases, you would want to include a combination of Bootloader + SoftDevice + Application. Below is a table (taken from Nordic’s nrfutil documentation on the combinations supported in a DFU package along with the guidelines and restrictions on some of the combinations:


BL: Bootloader
SD: SoftDevice
APP: Application

Note 1: SD must be of the same Major Version as the old BL may not be compatible with the new SD.
Note 2: When updating SD (+ BL) + APP the update is done in 2 following connections, unless a custom bootloader is used. First the SD (+ BL) is updated, then the bootloader will disconnect and the (new) BL will start advertising. Second connection to the bootloader will update the APP. However, the two SDs may have different IDs. The first update requires --sd-req to be set to the ID of the old SD. Update of the APP requires the ID of the new SD. In that case the new ID must be set using --sd-id parameter. This parameter was added in nrfutil 3.1.0 and is required since 3.2.0 in case the package should contain SD (+ BL) + APP. Also, since version 3.2.0 the new ID is copied to --sd-req list so that in case of a link loss during APP update the DFU process can be restarted. In that case the new SD would overwrite itself, so --sd-req must contain also the ID of the new SD.
Note 3: When creating update packages of bootloaders compiled from nRF5 SDK 15.3.0 and higher, nrfutil version 5.0.0 must be used. This is because of changes to the bootloader projects in the nRF5 SDK, and if an old nrfutil version is used the size of the generated packages will be too large.


To expand on these guidelines:

  • Note 1: if the SoftDevice only or the SoftDevice + Application are included in the DFU package (meaning that the Bootloader is not included), then the new SoftDevice must be of the same Major version of the existing SoftDevice (e.g. you cannot update from 15.3.0 to 16.0.0 without including the Bootloader in the DFU package).
  • Note 2: if the update needs to update at least the SoftDevice and the Application (with the Bootloader being optional), then the update will happen in two updates (two separate .ZIP files and two BLE connections to the DFU target device). The first one will update the SoftDevice and the second will update the Application. The --sd-id argument list relates to the SoftDevice update (1st .ZIP file) and needs to contain the ID of the existing SoftDevice on the target device. The  --sd-req relates to the Application update (2nd .ZIP file) and needs to contain the ID of the new SoftDevice.

BL + SD + APP Hex Package

In practice, you may want to include the Bootloader, SoftDevice, and Application all in one DFU package. For example, this would be useful if you want to create a DFU package to program many devices via UART or USB which can save a lot of time versus having to do it via the OTA DFU process. A device that contains all three (BL + SD + APP) will be able to boot into DFU mode on demand while being able to run the Application in normal operation.

In this case, we need to include the Bootloader settings in the package so the BL recognizes the APP included and launches it. A couple of tools are utilized to achieve this:

  • The nrfutil command-line tool: used to generate the BL settings page.
  • The mergehex command-line tool: used to merge the BL with the BL settings.

To generate the BL settings, we run the following command:

Output:

Make sure you assign the version numbers to the appropriate values, incrementing with each new version for the application and bootloader versions. The bootloader settings version number is defined as follows:

  • Version value = 1 for SDK 12.0.0 – SDK 15.2.0
  • Version value = 2 for SDK15.3.0 and later

Next, we merge the two hex files (the BL hex file + BL settings hex file) by running the following command:

The output will contain both the Bootloader and the Bootloader settings as part of a single hex file.

We can then take this resulting hex file and merge it with the Application hex and the SoftDevice hex. This can be done with the mergehex tool once again:

Now we can take this resulting hex file and flash it directly to the target(s).

Note: This output is not valid as a DFU package, but rather a hex file that can be programmed to many devices in production.

Development Mode

When you’re working in development mode and do not want to worry about version numbers, you can include the --debug-mode flag when invoking the nrfutil pkg generate command. This will allow the bootloader to skip/ignore the version numbers, so you can flash a DFU package again and again without having to increment the version number.

Note: It is extremely important to make sure this flag is NOT included in any DFU package used in production.