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.
The sample supports the following development kits:
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:
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.
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.
The following table shows the mesh composition data for this sample:
BLOB Transfer 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
attentioncallbacks 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.
See Configuring your application for information about how to permanently or temporarily change the configuration.
This sample is split into the following source files:
main.cfile to handle Bluetooth mesh initialization, including the model handling for Device Composition Data, Health and Configuration Server models.
dfu_target.cwith the Target role implementation.
dfu_dist.cwith the Distributor role implementation.
smp_bt.cimplementing SMP Bluetooth service advertisement.
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.
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:
Tap Add node to start scanning for unprovisioned mesh devices.
Select the Mesh DFU Distributor device to connect to it.
Tap Identify, and then Provision, to provision the device.
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.
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:
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.
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
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.
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.
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.
This sample uses the following nRF Connect SDK libraries:
In addition, it uses the following Zephyr libraries: