Bluetooth mesh: Device Firmware Update (DFU) distributor

The Bluetooth® mesh DFU distributor sample demonstrates how device firmware can be distributed over a Bluetooth mesh network. The sample implements the Firmware Distribution role of the Bluetooth mesh DFU subsystem.

The specification that the Bluetooth mesh DFU subsystem is based on is not adopted yet, and therefore this feature should be used for experimental purposes only.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

For provisioning and configuring of the mesh model instances, the sample requires a smartphone with Nordic Semiconductor’s nRF Mesh mobile app installed in one of the following versions:

For uploading an image to the Distributor, this sample also requires a smartphone with Nordic Semiconductor’s nRF Connect Device Manager mobile app installed in one of the following versions:

Overview

The following are the key features of the sample:

  • The sample is configured as an application for the MCUboot.

  • The image management subsystem of the MCU manager (mcumgr) is used to upload firmware images to the Distributor.

  • A set of shell commands is provided to control the firmware distribution over a Bluetooth mesh network.

  • Self-update is supported.

Provisioning

The sample supports provisioning over both the Advertising and the GATT Provisioning Bearers, PB-ADV and PB-GATT respectively. The provisioning is handled by the Bluetooth mesh provisioning handler for Nordic DKs. It supports four types of out-of-band (OOB) authentication methods, and uses the Hardware Information driver to generate a deterministic UUID to uniquely represent the device.

Use nRF Mesh mobile app for provisioning and configuring of models supported by the sample.

Models

The following table shows the mesh composition data for this sample:

Element 1

Element 2

Config Server

BLOB Transfer Server

Health Server

Firmware Update Server

BLOB Transfer Client

Firmware Update Client

BLOB Transfer Server

Firmware Distribution Server

The models are used for the following purposes:

  • Config Server allows configurator devices to configure the node remotely.

  • Health Server provides attention callbacks that are used during provisioning to call your attention to the device. These callbacks trigger blinking of the LEDs.

  • The Binary Large Object (BLOB) Transfer models, BLOB Transfer Server and BLOB Transfer Client, provide functionality for sending large binary objects from a single source to many Target nodes over the Bluetooth mesh network. It is the underlying transport method for the DFU. BLOB Transfer Client and BLOB Transfer Server are instantiated on the primary element. An additional BLOB Transfer Server is instantiated on the secondary element.

  • To implement the Firmware Distribution role, the sample instantiates the models Firmware Distribution Server and Firmware Update Client. The Firmware Distribution Server model and its base models are instantiated on the primary element. These models are also used to support the self-update of the sample.

  • To implement the Target node functionality of the Device Firmware Update (DFU) subsystem, the Firmware Update Server model and its base models are instantiated on the secondary element.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Source file setup

This sample is split into the following source files:

  • A main.c file to handle Bluetooth mesh initialization, including the model handling for Device Composition Data, Health and Configuration Server models.

  • File dfu_target.c with the Target role implementation.

  • File dfu_dist.c with the Distributor role implementation.

  • File smp_bt.c implementing SMP Bluetooth service advertisement.

Building and running

This sample can be found under samples/bluetooth/mesh/mesh_dfu/distributor in the nRF Connect SDK folder structure.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Note

To prevent an unauthenticated access to the device over SMP, it is strongly recommended to enable the CONFIG_MCUMGR_TRANSPORT_BT_AUTHEN option. This will enforce a remote device to initiate a pairing request before accessing SMP characteristics. See Zephyr Bluetooth LE Security for more details about securing the Bluetooth LE connection.

Testing

This sample has been tested with the nRF52840 DK (nrf52840dk_nrf52840) board.

Provisioning the device

The provisioning assigns an address range to the device, and adds it to the mesh network. Complete the following steps in the nRF Mesh app:

  1. Tap Add node to start scanning for unprovisioned mesh devices.

  2. Select the Mesh DFU Distributor device to connect to it.

  3. Tap Identify, and then Provision, to provision the device.

  4. When prompted, select an OOB method and follow the instructions in the app.

Once the provisioning is complete, the app returns to the Network screen.

Configuring models

See Configuring mesh models using the nRF Mesh mobile app for details on how to configure the mesh models with the nRF Mesh mobile app.

Configure the Firmware Distribution Server, Firmware Update Client, BLOB Transfer Server and BLOB Transfer Client models on the primary element on the Mesh DFU Distributor node:

  • Bind each model to Application Key 1.

Configure the Firmware Update Server and BLOB Transfer Server models on the secondary element on the Mesh DFU Distributor node:

  • Bind each model to Application Key 1.

Performing a Device Firmware Update

The Bluetooth mesh defines the Firmware update Initiator role to control the firmware distribution. This sample supports, but doesn’t require an external Initiator to control the DFU procedure. The Bluetooth mesh DFU subsystem also provides a set of shell commands that can be used instead of the Initiator. Follow the description in the DFU over Bluetooth mesh guide on how to perform the firmware distribution without the Initiator.

The commands can be executed in two ways:

  • Through the shell management subsystem of MCU manager (for example, using the nRF Connect Device Manager mobile application or Mcumgr command-line tool).

  • By accessing the Shell module over UART.

Uploading a firmware image

A firmware image can be uploaded to the device in two ways:

  • In-band, using BLOB Transfer models by an Initiator device.

  • Out-of-band, using the image management subsystem.

For out-of-band upload, the sample uses the image management subsystem of the MCUmgr. The management subsystem uses the Simple Management Protocol (SMP), provided by the Mcumgr library, to exchange commands and data between the SMP server (the sample device) and the SMP client. This sample supports Bluetooth Low Energy as the SMP transport. See Device Management for more information about Mcumgr and SMP.

In this sample, the device flash is split into fixed partitions using devicetree as defined in nrf52840dk_nrf52840.dts. The firmware image that is to be distributed over Bluetooth mesh network should be stored at slot-1. The sample uses Flash map to read the firmware image from slot-1 when distributes it to Target nodes.

When the image is sent in-band, the Firmware Distribution Server will store the firmware image in slot-1.

To upload an image to slot-1 on the sample device out-of-band, use a smartphone with Nordic Semiconductor’s nRF Connect Device Manager installed.

Note

Because the same slot (slot-1) is used by the MCUboot bootloader for local DFU, do not request to test the image when uploading the firmware to the sample device. Otherwise, the bootloader will try swapping the distributor image with the uploaded one at the next reboot.

Copy the new image to the mobile phone. Then, in the mobile app, do the following:

  • Find and select the Mesh DFU Distributor device.

  • Go to the Image tab.

  • Press the ADVANCED button in the right top corner. This will allow uploading the image to slot-1 without swapping the image on the Distributor.

  • Under the Firmware Upload area, press the SELECT FILE button and select the copied image.

  • Press the UPLOAD button.

  • Select Application Core (0) and tap OK.

Once the image upload is done, the State field is set to UPLOAD COMPLETE.

Changing the firmware distribution phase

When the firmware distribution phase changes, the sample will print a corresponding message. For example, when the distribution is completed, the sample will print:

Distribution phase changed to Completed

Self-update

This sample instantiates the DFU and BLOB Transfer Server models on its secondary element and thus can also be updated over Bluetooth mesh by any other Distributor or by itself.

To update this sample, use the address of the secondary element of the sample as the address of the Target node.

When the Distributor updates itself, the DFU transfer will end immediately after start as the image is already stored on the device.

Note

Do not add other Target nodes but the Distributor when performing a self-update. If the Firmware Distribution Server on the Distributor finds itself in the list of Target nodes, it skips the DFU transfer as the image is already stored on the device. Thus, other nodes won’t receive the image.

When this sample is used as a Target, it behaves as described in Performing a Device Firmware Update.

Logging

In this sample, the UART console is occupied by the shell module. Therefore, it uses SEGGER RTT as a logging backend. For the convenience, printk is also duplicated to SEGGER RTT.

Dependencies

This sample uses the following nRF Connect SDK libraries:

It also requires MCUboot and MCUmgr.

In addition, it uses the following Zephyr libraries: