This guide offers step-by-step instructions on how to prepare and program the DFU example application, create a DFU file that contains example firmware, and transfer it. Use this guide to set up the proprietary mesh DFU to transfer any firmware to any device on the Bluetooth mesh network. The firmware to be transfered can be a bootloader, a new SoftDevice, or a new application.
Before configuring DFU over Bluetooth mesh, make sure that you are familiar with the proprietary mesh DFU protocol documentation and that you have integrated DFU process into your application.
The DFU example demonstrates the background mode DFU. For simplicity, various steps are provided for the application firmware upgrade and are using the default nRF Util options. Additional options and some debugging methods are documented in the last two sections of this guide.
Table of contents
To perform DFU transfers over Bluetooth mesh:
pc-nrfutil repository does not contain the additional code that is needed to handle the proprietary mesh DFU. To use the tool with the proprietary mesh DFU, use the mesh_dfu branch mentioned above. See the tool's documentation for more information about installation and prerequisites.-s <serial-number> option for each call to the nrfjprog command, where <serial-number> is the SEGGER ID of your device. This will make nrfjprog execute its operations on the specified device only.intelhex package is installed for your Python installation.Before you start properly preparing your devices for the proprietary mesh DFU, you can decide whether you want to generate a signing file with nRF Util and add the public key from nRF Util to your device page, for an additional verification feature.
DFU images can be signed to ensure they stem from a trusted source. If you want to use this signature verification functionality, you need a signing key.
Use the nRF Util tool to generate a signing key. Run the following command:
This command creates a private_key.txt file in your current directory.
This key must only be shared with trusted sources. If you lose it, you also lose the authorization to do DFU updates to your devices in the future. The only way to recover from the loss of the private key is to reflash the device manually.
Now that you have a private key, you can generate the public key for it, which you can safely share with everyone. You must then add this public key to the bootloader configurator file, which is used to create the device page. For details about the device page generator script, see DFU Utilities and Tools.
Complete the following steps:
tools/dfu folder, edit the bootloader_config_default.json file to prepare the device page:"public_key".Qx and Qy strings to this key. For example: Optionally, you can also change the company ID entry in the device page. The company ID works as a namespace for application IDs in the proprietary mesh DFU. In this way, any company with an assigned company ID can use any application ID for its products, without risking an application ID conflict.
In the example, the company ID is set to 89, which is the decimal version of Nordic Semiconductor's Company ID assigned by Bluetooth SIG. If your company has an assigned ID, you can use that ID number. If you do not represent a company with an assigned ID, use a random 32-bit number higher than 65535.
Complete the following steps to prepare your devices for the background mode of the proprietary mesh DFU:
To do a DFU transfer, you must create a DFU archive with nRF Util, giving arguments that match the device page. The DFU archive is a zip file that contains the application binary along with some metadata.
You need the HEX file of an example application that causes a LED to blink on the boards. The file is generated when you build the Bluetooth mesh stack and is located in the bin/blinky folder. Use the HEX file that corresponds to the chip and the SoftDevice you are using.
To generate the DFU archive, run the nrfutil command that corresponds to your SoftDevice. For example:
This command generates a DFU archive called dfu_test.zip in the current directory. You can call nrfutil dfu genpkg --help to get a list of possible command line arguments and their meaning.
bin/blinky application does not include the support for DFU over Bluetooth mesh. Once you upgrade your existing application with blinky, the device cannot be upgraded further using DFU over Bluetooth mesh.--company-id and the --application-id values must match the values used for generating the device page. The --application-version must be higher than the version number that you used for the previous firmware image.2. A device only accepts application transfers that match its current company and application IDs and have a higher version number.To generate a HEX version of your device page, use the device_page_generator.py script located in the device page file folder: tools/dfu. For details about the device page generator script, see DFU Utilities and Tools.
You have to specify the device series (-d option), and the SoftDevice version (-sd option). All device pages contain a SD_VERSION entry, which must match the --sd-req value passed to nrfutil when generating the DFU archive in the previous step. Failing to match the SoftDevice version requirement parameters will make the device reject the transfer, as its own firmware ID will not match the one in the transfer.
To generate a device page hex file for an nRF52 Series device (for example, nRF52832) using s132 SoftDevice version 7.2.0, run the following command from inside the tools/dfu folder:
This creates a device page HEX file in the tools\dfu\bin folder. This file will be used for flashing the first application on all devices.
Use nrfjprog (available on nordicsemi.com) to erase all data on your device (including UICR) and flash the SoftDevice.
SoftDevices for the nRF51 and nRF52 chips are located in the bin/softdevice folder.
Run the following nrfjprog command with the correct name of the HEX file:
For example, to erase data and flash the S132 SoftDevice v7.2.0, run the following command:
For this step, use the precompiled bootloader with the serial support. You can find the precompiled versions of the bootloader under bin/. The bootloader version must match your chip version, as per table.
| Chip version | Bootloader |
|---|---|
| nRF51422_xxAC | mesh_bootloader_serial_<compiler>_nrf51422_xxAC.hex |
| nRF52832_xxAA | mesh_bootloader_serial_<compiler>_nrf52832_xxAA.hex |
| nRF52833_xxAA | mesh_bootloader_serial_<compiler>_nrf52833_xxAA.hex |
| nRF52840_xxAA | mesh_bootloader_serial_<compiler>_nrf52840_xxAA.hex |
Flash the precompiled bootloader with the following nrfjprog command:
For example, you can run the following command to flash a bootloader compiled with GCC ARM compiler on an nRF52832_xxAA device:
To be able to do Device Firmware Updates, you must flash an application that supports DFU. You can use the DFU example application in examples/dfu/.
You must flash the DFU example application from your build folder, using the HEX file that matches your chip version and SoftDevice. For example, build/examples/dfu/dfu_nrf52832_xxAA_s132_7.2.0.hex if your device is an nRF52832_xxAA with the s132 SoftDevice v7.2.0.
Run the following nrfjprog command:
To flash the device page HEX file to the devices, run the following nrfjprog command:
Then, reset the device to start the application:
After the reset, observe that for every development kit that you programmed, all LEDs are OFF. At this point, you have everything ready for performing the DFU over Bluetooth mesh.
Before you start transfering data:
dmesg command after you have plugged in a device to see which serial port file has been assigned to the device. The serial ports for J-Link devices are called ttyACMx, where x is an integer, and are located in the /dev directory.To start the DFU transfer, run the following command:
A progress bar appears. The transfer takes a couple of minutes.
When finished, the bootloader switches to the application and one of the LEDs starts blinking on each kit. Note that you cannot do the DFU twice with the same DFU archive, because the application version in the device page on your device is incremented to the latest version. Therefore, the bootloader will reject any attempt to transfer the same firmware again.
If your newly transferred application also includes the DFU support, you can update it again in the future when needed. To carry out a subsequent DFU transfer, run the preparation steps and the transfer command again, but with an increased version number. For example, --application-version 3. Also, use the new zip file.
So far, this guide described how to configure and carry out the application firmware upgrade. The procedure for carrying out bootloader and SoftDevice firmware upgrade is quite similar, except for the generation of a DFU archive.
If you want to upgrade the bootloader on the device, during Step 1 you need to prepare the DFU archive using the new bootloader hex file and version number. To do this, use the following command line options with the nrfutil commands:
--bootloader (instead of the --application option) - This option provides the bootloader hex file.--bootloader-id - This option specifies the bootloader ID and version.--bootloader-id is a uint16 number that has the bootloader ID as the least significant byte and the bootloader version as the most significant byte.bootloader_id that is specified in the bootloader_config_default.json file that was used to create the device page on the device undergoing upgrade.For example, to create a DFU archive to upgrade the bootloader from version 1 (see bootloader_config_default.json snippet) to version 2, the command would be the following:
If you want to upgrade the SoftDevice on the device, during Step 1 you need to prepare the DFU archive using the new SoftDevice hex file. To do this, use the following command line options with the nrfutil commands:
--softdevice (instead of the --application option) - This option provides the SoftDevice hex file.For example, to create DFU archive to upgrade SoftDevice to a new SoftDevice with the version 0x0101, the command would be the following:
This section describes additional nRF Util options and scripts that can be used for debugging the issues in the DFU procedure.
Each DFU packet is transmitted after a certain interval by the source device. The default value of the interval is 500 ms (see Transfer rate). You can change this interval by using -i option while starting the DFU.
For example, to start DFU with the interval of 100 ms, use the following command:
The higher values of the interval are better for dense networks with a lot of noise, even despite the drawback of increased overall transfer time. This is because the longer interval gives more time for devices to recover missing segments during the transfer.
To get a more verbose output during the DFU transfer using nRF Util, add --verbose before the arguments:
To verify that the bootloader is working correctly, run the bootloader verification script.