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.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF54LM20 DK	PCA10184	nrf54lm20dk	nrf54lm20dk/nrf54lm20a/cpuapp
nRF54L15 DK	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l15/cpuapp
nRF54L15 DK (emulating nRF54L10)	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l10/cpuapp
nRF52840 DK	PCA10056	nrf52840dk	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

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 and building 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, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Note

To prevent an unauthenticated access to the device over SMP, it is strongly recommended to enable the CONFIG_MCUMGR_TRANSPORT_BT_PERM_RW_AUTHEN option. This will enforce a remote device to initiate a pairing request before accessing SMP characteristics. See SMP over Bluetooth authentication for more information.

Testing

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 Bluetooth 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 does not require an external Initiator to control the DFU procedure.

To activate the new firmware image on the Target node, the new image to be distributed must satisfy acceptance crieria for the target (for example: see Target sample requirements stated in Performing a Device Firmware Update).

There are two ways to perform a Device Firmware Update on a mesh network using the Distributor sample:

• Through the shell management subsystem of MCU manager.

• Through the nRF Mesh mobile application.

nRF Mesh app (iOS)Shell

Note

If you plan to use the nRF Mesh app, the Mesh DFU feature is currently supported only in the nRF Mesh app for iOS.

Obtain the firmware image archive for the target node from the build directory and copy it to your mobile device. Then follow the steps in the DFU over Bluetooth Mesh guide to perform the firmware distribution.

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 and UART 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 and nrf54l15dk_nrf54l15_cpuapp.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.

• Tap 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 Image Upload area, tap the Select File button and select the copied image.

• Tap the Start button.

• Select target.signed.bin.

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 will not receive the image.

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

This sample also provides support for Point-to-point DFU over Bluetooth Low Energy, so it is possible to self-update using the Simple Management Protocol (SMP).

SMP over Bluetooth authentication

By default, the SMP characteristics do not require authentication when using SMP over Bluetooth to access the management subsystem. To prevent an unauthenticated access to the device over SMP, it is strongly recommended to enable the CONFIG_MCUMGR_TRANSPORT_BT_PERM_RW_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.

The sample supports the LE Pairing Responder model that allows sending a passkey over a mesh network when the Distributor has no means of displaying the passkey. When the model and the CONFIG_MCUMGR_TRANSPORT_BT_PERM_RW_AUTHEN option are enabled while a remote device tries to read the SMP characteristics, the pairing request will be initiated and the sample will require the remote device to enter the passkey generated by the model.

To enable the LE pairing authentication with the LE Pairing Responder model support, set EXTRA_CONF_FILE to overlay-smp-bt-auth.conf file when building the sample.

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.

External flash support

This sample supports two types of external flash usage: DFU firmware image storage and settings partition storage.

DFU firmware image storage

This sample supports external flash memory as secondary storage partition for saving of the firmware images, both as for self update as well as for distribution. See Using external flash memory partitions for more information on external flash support as a partition in the MCUboot and NSIB. The default configuration does not support external flash memory. To enable external flash support, set FILE_SUFFIX to dfu_ext_flash when building the sample.

Build the sample using the following command:

west build -p -b *board_name* -- -DFILE_SUFFIX=dfu_ext_flash

Currently, DFU external flash is supported on the nrf52840dk/nrf52840 and nrf54l15dk/nrf54l15/cpuapp board targets.

Settings partition storage

This sample supports relocating mesh settings to external flash on nrf52840dk/nrf52840, nrf54l15dk/nrf54l15/cpuapp, nrf54l15dk/nrf54l10/cpuapp, and nrf54l15dk/nrf54l05/cpuapp board targets. See the nRF52840 DK User Guide or the nRF54L15 DK User Guide for details about the external flash memory available on the board. This provides additional storage space for mesh persistent data.

To enable external flash settings storage, set FILE_SUFFIX to settings_ext_flash when building the sample.

Build the sample using the following command:

west build -p -b *board_target* -- -DFILE_SUFFIX=settings_ext_flash

Note

The external flash is not erased during the internal flash erasing procedure. See nRF Util for more information on how to erase the external flash.

The settings subsystem requires allocating some persistent memory area, which is done through the settings subsystem backend configuration in the form of an allocated number of sectors.

For NVS backend:

• CONFIG_SETTINGS_NVS_SECTOR_COUNT

• CONFIG_SETTINGS_NVS_SECTOR_SIZE_MULT

For ZMS backend:

• CONFIG_SETTINGS_ZMS_CUSTOM_SECTOR_COUNT

• CONFIG_SETTINGS_ZMS_SECTOR_COUNT

• CONFIG_SETTINGS_ZMS_SECTOR_SIZE_MULT

The sector size depends on the flash memory layout.

Apart from this, the allocated partitions are defined in a devicetree (DTS) overlay file. The size of the storage_partition node defined in the DTS overlay must be equal to the memory size configured for the settings subsystem.

Note

You can use only one FILE_SUFFIX at a time. The sample does not support both DFU firmware image storage and settings partition storage on external flash simultaneously.

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