nRF5 SDK for Mesh v5.0.0
Proprietary mesh DFU protocol

A Device Firmware Update (DFU) is the process of updating the firmware on a Bluetooth mesh device.

Nordic Semiconductor's mesh DFU protocol is adopted from the proprietary nRF OpenMesh project, and operates on the proprietary OpenMesh protocol. The OpenMesh protocol is an advertising based protocol like the Bluetooth mesh, but it does not support addressing, acknowledged message passing or encryption.

This page and its subpages describe the proprietary mesh DFU protocol, including DFU Utilities and Tools and nRF5 SDK for Mesh bootloader. In this section, you can also learn more about Setting up DFU using the DFU example included in the nRF5 SDK for Mesh.

Table of contents


Characteristics

The proprietary mesh DFU protocol is optimized for updating all devices in a network as efficiently as possible. Although it shares some tooling and code modules with nRF5 SDK Bootloader and DFU modules, there are several differences both in protocol and operation to make updating of large amounts of devices as painless as possible.

Category nRF5 SDK DFU nRF5 SDK for Mesh DFU
Transfer modes Background and bootloader DFUs. Background and bootloader DFUs.
Transfer types SoftDevice, bootloader, application, SoftDevice and bootloader.
SoftDevice and bootloader can be updated independently.
SoftDevice, bootloader, application.
SoftDevice and bootloader can be updated independently.
Roles DFU target and DFU controller. DFU source, DFU target, and DFU relay.
Concurrent transfers Not possible: each device updated individually. Implemented: entire network updated simultaneously.
Device network Devices with single role or firmware. Network of devices of different role and firmware.
Transfer rate Fast transfer rate. Very slow transfer rate.
Background operation Background mode transfer in the application not available. Background mode transfer in the application implemented and active by default.
Transfer banking Banking in an unused area of flash. Banking in an unused area of flash.
Memory map Flash memory map with the MBR parameter storage between the bootloader and the bootloader settings. The same flash memory map as for the nRF5 SDK, but with the MBR parameter storage between the bootloader and the application area.
Security No encryption on the DFU level. Optional security key signing. No encryption on the DFU level. Optional security key signing.

Transfer modes and types

The proprietary mesh DFU supports two modes:

As part of each transfer mode, the proprietary mesh DFU protocol is using three different transfer types (packages):

Each of these three firmware pieces must be transferred separately, and each has its own identifier. Each has also its own area in the memory map.

The nRF5 SDK for Mesh SoftDevice and bootloader can be updated independently. This saves time and memory if you want to make small changes in the bootloader.

Roles

The following roles are supported by the proprietary mesh DFU:

See Integrating DFU process into the application for more information about when the DFU module switches to the target and relay roles.

Concurrent transfers

Contrary to the nRF5 SDK DFU, the entire Bluetooth mesh network can be updated simultaneously with concurrent transfers.

A Bluetooth mesh network can contain hundreds of devices, and updating all of them one by one can take a lot of time. To get around this, the proprietary mesh DFU protocol lets mesh network devices relay the data they are receiving to their neighbors. Both the passive mesh devices and the devices receiving a transfer will relay all data packets, thus ensuring that the DFU transfer reaches all devices in the network. This method is much faster than passing the entire DFU transfer to each device individually.

A device that receives a DFU transfer will perform the following steps for each data message it receives:

  1. Verification that the data packet has not already been received.
  2. Storing of the payload of the data packet in the flash at the appropriate offset in the transfer data.
  3. Marking of the data packet as received.
  4. Retransmission of the data packet a predefined amount of times at an exponential interval.

Devices that are not directly interested in the contents of the transfer, will only perform steps 1, 3, and 4 to ensure that the target devices further out in the network still receive the packets.

To learn more about proprietary mesh DFU packets, see DFU protocol packet formats.

Mixed-device networks

Typically, a Bluetooth mesh network contains devices with several different roles and firmware. When performing a DFU transfer, it is important to be able to distinguish between these devices. If an update for light switch devices is flashed to a light bulb, it is likely that the light bulb stops working. This is different for one-to-one DFU transfers, like the ones performed by the nRF5 SDK DFU protocol, where the sender is able to identify the target device and send it the correct firmware.

The proprietary mesh DFU protocol deals with mixed-device networks by allowing each device type to have its own application ID in addition to an application version number. When a device is notified of an upcoming DFU transfer, it can compare the application ID of the transfer with the application ID of its own firmware. If the application IDs match, and the incoming transfer has a higher version, the device generally accepts the transfer. If a device is notified of an upcoming DFU transfer with a different application ID, it can choose to either act as a relay device for this transfer, or to ignore it.

Transfer rate

Compared to the nRF5 SDK DFU protocol, the proprietary mesh DFU transfer is quite slow. For example, a 100 kB firmware image will take about an hour to transfer.

The proprietary mesh DFU protocol depends on redundancy to ensure reliable communication, and therefore takes a lot longer to propagate the same amount of data than the nRF5 SDK DFU. The DFU data is sent in 16-byte chunks at regular intervals, with a few redundant transmissions for every packet to ensure that all devices receive it.

The packet interval is controlled by the transfer source device. By default, the Bluetooth mesh DFU tools emit a new packet every 500 ms (making the transfer rate 16 B/500 ms = 32 B/s), but this number should be tuned according to the Bluetooth mesh network properties.

Some network characteristics to consider are:

Because these characteristics are different for all deployments, it is not possible to make a general rule that will work for all networks. To maximize the DFU performance:

Background operation

Due to the relatively slow transfer rate of the proprietary mesh DFU protocol, transfers could end up taking over an hour, which is an unacceptable downtime for a lot of applications. To deal with this, the proprietary mesh DFU implements a background mode.

The background mode allows the application to continue the normal operation while the DFU transfer progresses. The background mode is the default mode of operation, unless there is no valid application on the device, in which case it falls back to the bootloader.

Transfer banking

Devices receiving background transfers have to store the incoming transfer in a bank in an unused area of flash, to avoid overwriting themselves while they're running. While in progress, the DFU transfer data gets stored in the bank, and once finished, the application can tell the bootloader to copy the bank to the application area, effectively finalizing the update. Although the bootloader notifies the application about the completion of the transfer as soon as it can, the application is free to copy the bank at any point, or even not at all. There can only be one bank per transfer type at the time, and banks cannot overlap. Finishing a banked DFU transfer will remove any existing bank of the same transfer type.

Note that the bank must be placed in a flash area that is both large enough to fit the entire incoming application during the transfer, and that doesn't overlap with the new application or old application. To ensure maximum space for the incoming transfer, both as a bank and as a finished application, it's generally recommended to place the start of the bank right in the middle of the application section of the device. If the transfer is not able to fit both as a bank or as an application after the transfer is finalized, the device must fall back to the bootloader, and perform the transfer in the bootloader mode.

Memory map

The proprietary mesh DFU protocol uses the same flash memory map as the nRF5 SDK nRF5 SDK Bootloader and DFU modules, with one minor difference. Instead of placing the MBR parameter storage between the bootloader and the bootloader settings (called device page in the proprietary mesh DFU), the MBR parameter storage in the proprietary mesh DFU protocol goes between the bootloader and the application area.

bootloader_memory_nrf52.svg
Flash memory map

The memory map contains the following major firmware elements:

These correspond to the transfer types mentioned earlier. Each firmware element can be updated individually with a DFU transfer.

The application uses the bootloader to perform the receive-and-relay algorithm steps, even when working in the background mode. When initializing the Bluetooth mesh framework, the DFU module initializes a command handler module in the bootloader, which runs alongside the application.

To be able to run alongside the application, the bootloader reserves the last 768 bytes of RAM on the device. This reserved RAM is accounted for in all Bluetooth mesh project files and linker scripts. Failing to reserve these bytes causes unexpected behavior from the bootloader when the application starts.

Security

Similarly to the nRF5 SDK, the proprietary mesh DFU does not encrypt the DFU transfer data.

In the Bluetooth mesh case, this is a limitation inherited from the OpenMesh protocol, and means that under no circumstance should security-sensitive data (like keys) be sent as part of a DFU transfer.

The proprietary mesh DFU does however feature Elliptic Curve Digital Signatures (ECDSA) for authenticating the transfers. Although signing is optional, it is highly recommended to sign all transfers. Signing is performed with a private signing key when the DFU transfer is created, and all Bluetooth mesh devices can get preprogrammed with a matching public signing key to authenticate the firmware. If a Bluetooth mesh device has a public signing key, it will always require that the signature passes before the transfer is finalized.

The signing algorithm is performed by creating a SHA256 hash of the transfer metadata and firmware.

See the following table for the breakdown of the hash.

Field Offset (bytes) Size (bytes) Value
DFU type 0 1 DFU type from the DFU state packet.
Start address 1 4 Start address from the DFU start packet.
Firmware length in bytes 5 4 L, L = 4 * Firmware Length from the DFU start packet.
Padding 9 1 0
Firmware ID 10 F Firmware ID from the DFU state packet.
Firmware data 10 + F L The entire firmware image (not including signature).
Note
The size of the firmware ID (F) depends on the type of transfer. See DFU Firmware IDs.

The signature is created by ECDSA with the NIST P-256 curve (secp256r1):

signature = ecc_sign(curve=P-256, private_key, hash)

The signature is verified on the target device with the matching public key:

authenticated = ecc_verify(curve=P-256, public_key, hash, signature)
Warning
As the entire firmware data is required for the hash, the signature is not checked until after the entire transfer is complete. This design creates a possibility for a denial of service attack on the target devices, as an attacker might be able to initiate a false transfer. This false transfer could be indistiguishable from a normal transfer until the final signature check, at which point the target device may have spent significant resources receiving the transfer. However, this attack vector does not allow the attacker to execute any code on the target device, as the target device will delete all knowledge of the transfer when the signature check fails.

DFU Firmware IDs

All proprietary mesh DFU transfers are identified by a firmware ID. The structure of the firmware ID depends on the transfer type:

To decide whether to accept an incoming transfer or not, all Bluetooth mesh devices carry their current firmware IDs in their device page.

Application firmware ID

The application firmware ID identifies applications.

Every application has an ID and a version number. Generally, a device should accept DFU application transfers with the same application ID as their own firmware, and higher version numbers. The version number is a 32-bit number, and the versioning scheme is user-definable.

When in the bootloader mode, the prebuilt bootloader enforces a strictly increasing version number. This prevents malicious devices from downgrading firmware to a previous version, an attack that could be used to reintroduce old weaknesses in the firmware.

When in the background mode, this rule is not enforced, but strongly recommended, as there is no other native way to prevent malicious downgrades.

To create a unique firmware ID for each application, the application ID includes a 32-bit Company ID field, which identifies the device vendor. The Company ID field can either contain:

The randomly chosen identifier is not guaranteed to be unique, but it allows vendors that do not have an assigned Company ID to keep a high probability of uniqueness.

Field Offset (bytes) Size (bytes)
Company ID 0 4
Application ID 4 2
Application version 6 4

SoftDevice firmware ID

Nordic Semiconductor assigns a unique 16-bit SoftDevice identifier for every SoftDevice release, which can be read out from the firmware.

The SoftDevice firmware ID on the device is meant to match this number (although this is not explicitly required for correct operation). As the SoftDevice IDs represent the release IDs, and not the increasing version numbers, the strategy for whether to accept an incoming SoftDevice DFU transfer to take or not is user-definable.

When in the bootloader mode, the bootloader starts requesting SoftDevice updates if it receives a FWID beacon with an application ID that represents a higher version of its current application, but a different SoftDevice firmware ID.

When in the background mode, the upgrade strategy is user-definable.

Field Offset (bytes) Size (bytes)
SoftDevice ID 0 2
Note
Due to limitations in the bootloader implementation, the SoftDevice DFU transfers can only be accepted if the new SoftDevice is able to fit within the defined SoftDevice area (see Device page).

Bootloader firmware ID

The bootloader firmware ID consists of an 8-bit Bootloader ID field and an 8-bit Bootloader version field. Just like applications, bootloaders can come in different configurations, and each configuration can come in different versions.

When in the bootloader mode, the bootloader accepts incoming bootloader DFU transfers when the Bootloader ID field is identical to its current bootloader ID and the Bootloader version field is larger than the current bootloader version.

When in the background mode, the upgrade strategy is user-definable.

Field Offset (bytes) Size (bytes)
Bootloader ID 0 1
Bootloader version 1 1

Device page

All devices running the proprietary mesh DFU bootloader are required to keep a device page in flash. The device page defines the device configuration and acts as operational parameters for the bootloader.

The device page must be generated on a host computer and flashed on each device before deployment. The device_page_generator.py script for generating device pages can be found in tools/dfu/. For details, see Device Page Generator Tool.

Format

The device page is a single-page flash manager area in the last flash page of the device.

Contents

The device page contains all the information the bootloader needs to participate in the DFU transfers:

See the following table for the list of possible entries, including required and optional ones.

Entry ID Required
Signature public key 0x0001
Firmware ID 0x0002
Flags 0x0004
SoftDevice area 0x0010
Bootloader area 0x0011
Application area 0x0012
SoftDevice signature 0x001A
Bootloader signature 0x001B
Application signature 0x001C
SoftDevice bank 0x0021
Bootloader bank 0x0022
Application bank 0x0024

Signature public key

Public key used for signature verification.

Field Offset (bytes) Size (bytes)
Public key 0 64

Firmware ID

Current firmware ID. For details, see DFU Firmware IDs.

Note
The firmware ID entry is a concatenation of the three different proprietary mesh firmware IDs.
Field Offset (bytes) Size (bytes)
SoftDevice ID 0 2
Bootloader ID 2 1
Bootloader version 3 1
Company ID 4 4
Application ID 8 2
Application version 10 4

Flags

Current state of each firmware piece.

Field Offset (bytes) Size (bytes)
SoftDevice intact 0 1
Bootloader intact 1 1
Application intact 2 1
Device page invalid 3 1

SoftDevice area

Flash area where the SoftDevice can reside.

Field Offset (bytes) Size (bytes)
SoftDevice area start address 0 4
SoftDevice area length in bytes 4 4

Bootloader area

Flash area where the bootloader resides.

Field Offset (bytes) Size (bytes)
Bootloader area start address 0 4
Bootloader area length in bytes 4 4

Application area

Flash area where the application can reside.

Field Offset (bytes) Size (bytes)
Application area start address 0 4
Application area length in bytes 4 4

SoftDevice signature

Signature of the current SoftDevice.

Field Offset (bytes) Size (bytes)
SoftDevice signature 0 64

Bootloader signature

Signature of the current bootloader.

Field Offset (bytes) Size (bytes)
Bootloader signature 0 64

Application signature

Signature of the current application.

Field Offset (bytes) Size (bytes)
Application signature 0 64

SoftDevice bank

Information about a banked SoftDevice transfer.

Padding is a fixed data field that has always a 0 value.

Field Offset (bytes) Size (bytes)
Bank address 0 4
Bank length in bytes 4 4
Bank SoftDevice ID 8 2
Padding 10 8
Bank is signed 18 1
Bank state 19 1
Bank signature (optional) 20 64

Bootloader bank

Information about a banked bootloader transfer.

Padding is a fixed data field that has always a 0 value.

Field Offset (bytes) Size (bytes)
Bank address 0 4
Bank length in bytes 4 4
Bank Bootloader ID 8 1
Bank Bootloader version 9 1
Padding 10 8
Bank is signed 18 1
Bank state 19 1
Bank signature (optional) 20 64

Application bank

Information about a banked application transfer.

Field Offset (bytes) Size (bytes)
Bank address 0 4
Bank length in bytes 4 4
Bank Company ID 8 4
Bank Application ID 12 2
Bank Application version 14 4
Bank is signed 18 1
Bank state 19 1
Bank signature (optional) 20 64

Documentation feedback | Developer Zone | Subscribe | Updated