Bluetooth Mesh: Device Firmware Update (DFU) target

The Bluetooth® Mesh DFU target sample demonstrates how to update device firmware over Bluetooth Mesh network. The sample implements the Target 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 Dongle	PCA10059	nrf52840dongle_nrf52840	nrf52840dongle_nrf52840
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:

• nRF Mesh mobile app for Android

• nRF Mesh mobile app for iOS

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:

• nRF Device Manager mobile app for Android

• nRF Device Manager mobile app for iOS

Point-to-point DFU requirements

The configuration overlay overlay-ptp_dfu.conf enables the Point-to-point DFU over Bluetooth Low Energy feature.

This feature can be used together with Bluetooth Mesh DFU. If the Bluetooth Mesh DFU procedure is suspended, failing, or if the Bluetooth Mesh network is not available, the point-to-point DFU feature can be used as a backup option for the DFU process.

Overview

This sample can be used as a base image or be transferred over Bluetooth Mesh to update existing nodes.

To distribute this sample as a new image over Bluetooth Mesh network, use the Bluetooth Mesh: Device Firmware Update (DFU) distributor sample.

Provisioning

The sample supports provisioning over both the Advertising and the GATT Provisioning Bearers (i.e. PB-ADV and PB-GATT). 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
Config Server
Health Server
BLOB Transfer Server
Firmware Update 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.

• Binary Large Object (BLOB) Transfer models are the underlying transport mechanism for the mesh DFU feature. BLOB Transfer Server is instantiated on the primary element and used to receive the firmware image binary from the Distributor node.

• The Firmware Update Server model is instantiated on the primary element. Together with the extended BLOB Transfer Server model, the Firmware Update Server model implements all the required functionality for receiving firmware updates over the mesh network.

Configuration

See Configuring and building an 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/target 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 Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, you can test it by using a smartphone with nRF Mesh mobile app installed. Testing consists of provisioning the device and configuring it for communication with the mesh models, then performing a Device Firmware Update.

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 Target 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 BLOB Transfer Server model and the Firmware Update Server on the primary element on the Mesh DFU Target node:

• Bind each model to Application Key 1.

Once the models are bound to the application key, together they implement all the required functionality for receiving firmware updates over the mesh network from the Distributor node.

Performing a Device Firmware Update

This sample can be transferred as a DFU over a mesh network to update the existing nodes. The sample can also be the Target node updated by any firmware image that is compiled as the MCUboot application and transferred over the mesh network. In both cases, the firmware needs to be signed and the firmware version increased to pass the validation when the MCUboot swaps the images.

To set a new version, alter the Kconfig option CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION to a version that is higher than the default version of: "1.0.0+0". Then, after rebuilding the sample, the binary of the updated sample can be found in samples/bluetooth/mesh_dfu/target/build/zephyr/app_update.bin.

To perform a DFU with this sample, the following additional information is required:

Firmware ID

Firmware ID used in this sample corresponds to the image version that is encoded in the format defined by the mcuboot_img_sem_ver structure. For example, when the new version is 2.0.0+0, the encoded value will be 0200000000000000.

Firmware metadata

This sample enables the CONFIG_BT_MESH_DFU_METADATA option and uses the format defined by the Bluetooth Mesh DFU subsystem. How to generate valid metadata for this sample is described in Generating the firmware metadata.

The firmware distribution process starts on a target node with checking a metadata supplied with a new firmware. If the metadata data is decoded successfully, the following checks are performed in this sample:

• That the new firmware version is higher than the existing one.

• That the new firmware fits into the flash storage.

If the metadata check completes successfully, the sample selects a value from bt_mesh_dfu_effect depending on whether the composition data changes after programming the new firmware or not. This has an effect on the Distributor and the Target node. Only 2 options are supported by this sample:

BT_MESH_DFU_EFFECT_NONE

This effect is chosen if the composition data of the new firmware doesn’t change. In this case the device will stay provisioned after the new firmware is programmed.

BT_MESH_DFU_EFFECT_UNPROV

This effect is chosen if the composition data in the new firmware changes. In this case, the device unprovisions itself before programming the new firmware. The unprovisioning happens before the device reboots, so if the MCUboot fails to validate the new firmware, the device will boot unprovisioned anyway.

Note

To create the new Composition Data and see the BT_MESH_DFU_EFFECT_UNPROV effect, you can, for example, turn off the Friend feature in the prj.conf file by setting the CONFIG_BT_MESH_FRIEND option to n.

In this sample, the device flash is split into partitions using the Partition Manager. When the DFU transfer starts, the sample stores the new firmware at the MCUboot secondary slot using the Flash map.

Note

For the nRF52840 Dongle, the sample has a static partition management file pm_static_nrf52840dongle_nrf52840.yml to reserve the space for the nRF5 SDK Bootloader.

When the DFU transfer ends, the sample requests the MCUboot to replace slot-0 with slot-1 and reboots the device. The MCUboot performs the validation of the image located at slot-1. Upon successful validation, the MCUboot replaces the old firmware with the new one and boots it. After booting, the sample confirms the image so the old image does not get reverted at the next reboot.

When the sample is used as a new firmware, independently of the provisioning state, it sets the Firmware Update Server model to Idle state after booting. If the device stays provisioned, it lets the Distributor successfully finalize the firmware distribution process. If the device is unprovisioned, it has no effect on the DFU Server. The firmware distribution process then succeeds on the Distributor side, if the Target node doesn’t respond to the Distributor after programming the new firmware.

For more information about the firmware distribution process, see Device Firmware Update (DFU).

Logging

In this sample, UART and SEGGER RTT are available as logging backends.

Note

With the nRF52840 Dongle, only logging over UART is available.

Dependencies

This sample uses the following nRF Connect SDK libraries:

• Bluetooth Mesh provisioning handler for Nordic DKs

• DK Buttons and LEDs

It also requires MCUboot and MCUmgr.

In addition, it uses the following Zephyr libraries:

• Bluetooth Mesh Profile:

  • include/bluetooth/mesh.h