This example demonstrates how to implement a Zigbee OTA Upgrade Client for the purpose of Secure DFU. The OTA Upgrade Cluster is typically only one of several ZCL clusters defined by the common Zigbee application. The example is based on the OTA Upgrade Cluster and Nordic's Bootloader and DFU modules that create an integrated upgrade solution. This gives you a useful head start when populating the device with other functionalities.

The Zigbee OTA Upgrade Client Example consists of two components:

bootloader - used to verify the integrity of the application and to install a new application image.
Zigbee OTA Upgrade Client - an application that uses OTA Cluster to query the Zigbee network for the new image, install it, and reboot into it. The network notification and the distribution is handled by the Zigbee stack, while the image flashing and rebooting is handled by the IoT Background DFU module.
Master Boot Record (MBR) - a bootstrap code used for starting the bootloader.

The OTA Upgrade Cluster allows for downloading a new image while the device is running. This process differs from the one in BLE Secure DFU Bootloader, where a new image is downloaded and installed in the bootloader.

Zigbee OTA Upgrade Client example accepts images that contain an application which contains the Zigbee stack. The OTA Upgrade Client does not use the Zigbee OTA security architecture. Instead, it relies on the architecture of Bootloader and DFU modules for the Secure DFU process.

MBR setup

Zigbee OTA Upgrade Client Example does not use the SoftDevice. However, the bootloader requires the Master Boot Record (MBR). The example uses a standalone MBR provided as a hex file.

To program the MBR, perform the following steps:

Open a command prompt.
Navigate to <InstallFolder>\components\softdevice\mbr\nrf52840\hex.
In the PATH environment variable, ensure that there is a path to nrfjprog (from nRF5x Command Line Tools v9.2.0 or newer).
Run the following command: nrfjprog -f nrf52 -r --program mbr_nrf52_2.3.0_mbr.hex --chiperase.

Bootloader setup

The bootloader for the Zigbee OTA Upgrade Client Example is implemented through Bootloader and DFU modules. The main role of the bootloader is to check the integrity of the application and to transfer the new image to the active bank in case of dual-bank updates (see Dual-bank and single-bank updates). Unlike BLE Secure DFU Bootloader, the bootloader for Zigbee Secure DFU does not initialize any transports. Therefore, DFU is not possible in the bootloader. If a valid application is missing, the bootloader enters an infinite loop.

During system startup, the MBR is responsible for starting the bootloader. To do this, the MBR must know the start address of the bootloader. Therefore, you must set it to the correct value when you program the bootloader in UICR.BOOTLOADERADDR, located at address NRF_UICR_BOOTLOADER_START_ADDRESS.

To program the bootloader:

Navigate to the armgcc folder of the example at <InstallFolder>\examples\zigbee\experimental\ota\bootloader\pca10056\blank\armgcc.
Open a command prompt.
Run make to build the project.
Use nrfjprog (from nRF5x Command Line Tools v9.2.0 or newer) to program the .hex file that was created in the _build folder to the board.
Example: nrfjprog -f nrf52 -r --program _build\nrf52840_xxaa_blank.hex --sectoranduicrerase.

nrfutil

nrfutil is a PC tool that allows you to create and sign firmware packages, as well as perform the firmware update process on a PC. Support for Zigbee OTA images has been added to nrfutil in version 4.0.0. Refer to the nrfutil installation section for details on possible ways to install the tool.

To protect the target device against malicious attackers who try to impersonate the rightful sender of the firmware update, the initialization packet of the firmware package must be signed.

DFU client

The DFU process flow in the Zigbee OTA Upgrade Client is slightly different from the BLE Secure DFU Bootloader DFU process flow or others.

Two entities participate in the Zigbee OTA Upgrade process:

OTA Upgrade Client – the OTA Upgrade Client runs on a target, that is the device that is being upgraded, and is responsible for downloading and installing the new firmware. The OTA Upgrade Client incorporates a DFU controller that manages the DFU process (see Device Firmware Update process). This means that each OTA target can be in a different state regarding the OTA process at a given point of time.
OTA Upgrade Server – the OTA Upgrade Server is a server that provides a firmware image. The OTA Upgrade Server can be an example provided with this SDK (see Zigbee OTA Upgrade Server Example with image transfer over BLE), a standalone 3rd party device, or it can be instantiated as an nRF52840 DK in conjuction with the nrfutil utility.

Because of the nature of the DFU implementation, the OTA Upgrade Client cannot accept just any Zigbee OTA Upgrade file. The file must comply with several requirements. Apart from mandatory Zigbee OTA header, the image must consist of all the following Zigbee OTA subelements, in consecutive order:

The first subelement must be of Tag ID 0xCDEF and contain the DFU trigger structure.
The second subelement must contain the DFU Init packet of the generated image. Tag ID is irrelevant.
The third subelement must contain the binary of the upgrade firmware. Tag ID is irrelevant.

The trigger structure is defined in components/iot/background_dfu/background_dfu_state.h of nRF5 SDK:

/** @brief Trigger packet structure. */
typedef PACKED_STRUCT
{
 uint8_t flags; /**< Trigger message flags. Bits 7:4 (oldest) - trigger version, bit 3 - DFU mode, bits 2:0 - reserved. */
 uint32_t init_length;
 uint32_t init_crc;
 uint32_t image_length;
 uint32_t image_crc;
} background_dfu_trigger_t;

The nrfutil utility automatically generates the OTA Upgrade file of the specified structure, using the provided hex file with the image for upgrading the firmware.

Configuration of the OTA Upgrade Client

There are several defines in the main.c file of the Zigbee OTA Upgrade Client example that can help you configure the parameters of the Zigbee OTA Upgrade Client.

Name	Description
OTA_UPGRADE_TEST_FILE_VERSION	Version of the installed firmware.
OTA_UPGRADE_TEST_MANUFACTURER	Manufacturer ID for the device.
OTA_UPGRADE_TEST_IMAGE_TYPE	Image Type of the device.
HARDWARE_REVISION	Hardware Revision of the device.

Defines for configuring Zigbee OTA Upgrade Client (selection)

Note: OTA_UPGRADE_TEST_MANUFACTURER, OTA_UPGRADE_TEST_IMAGE_TYPE, and HARDWARE_REVISION must correspond to the values set upon generating the firmware package. For a detailed description of these fields, refer to Zigbee OTA Upgrade Cluster specification.

Testing

Unless stated otherwise, run all of the presented commands in the main folder of the DFU Example: <InstallFolder>\examples\zigbee\experimental\ota.

Precondition: To test the Zigbee OTA Upgrade process, you need at least two nRF52840 Development Kit boards. One of these boards will be an OTA Upgrade Server that distributes the new firmware. The others will play the role of OTA Upgrade Clients that are updated.

Test the Zigbee OTA Client application by performing the following steps:

Create cryptographic keys for the example. See Working with keys for information about key generation.
1. Create a private key:
  nrfutil keys generate priv.pem
2. Create a public key in code format and store it in a file named dfu_public_key.c:
  nrfutil keys display --key pk --format code priv.pem --out_file dfu_public_key.c
3. Copy the dfu_public_key.c file to the project folder <InstallFolder>\examples\dfu. Replace the existing file.
  Note
  Do not copy the key to the folder <InstallFolder>\examples\zigbee\experimental\ota. Use the path above.
Build the bootloader:
make -C bootloader\pca10056\blank\armgcc
Prepare the Zigbee OTA Upgrade Client:
1. Install micro-ecc. This library is required by the Cryptography library , which is used by the Zigbee Secure DFU example.
2. Compile the Zigbee OTA Upgrade Client:
  make -C client\pca10056\blank\armgcc
3. Return to the Zigbee OTA example main folder and generate a bootloader settings hex file:
  nrfutil settings generate --family NRF52840 --application client\pca10056\blank\armgcc\_build\nrf52840_xxaa.hex --application-version 0x01010101 --bootloader-version 1 --bl-settings-version 1 settings.hex
4. Use mergehex (part of the nRF5x Command Line Tools) to merge the client hex file and the bootloader settings hex file:
  mergehex -m client\pca10056\blank\armgcc\_build\nrf52840_xxaa.hex settings.hex -o dfu_client.hex
Flash the DFU Client to the client boards:
1. Connect one or more DFU Client boards to the computer.
2. Flash the MBR as described in MBR setup.
  nrfjprog -f nrf52 -r --program ..\..\..\components\softdevice\mbr\nrf52840\hex\mbr_nrf52_2.3.0_mbr.hex --chiperase
3. Flash the bootloader as described in Bootloader setup.
  nrfjprog -f nrf52 -r --program bootloader\pca10056\blank\armgcc\_build\nrf52840_xxaa_blank.hex --sectoranduicrerase
4. Flash the merged DFU Client:
  nrfjprog -f nrf52 -r --program dfu_client.hex --sectorerase
Prepare the firmware package for the DFU process:
1. Modify the Zigbee OTA Upgrade Client application. For example, add the following line to the main() function:
  bsp_board_led_on(BSP_BOARD_LED_3);
2. Increase the version. For example, change the define OTA_UPGRADE_TEST_FILE_VERSION to 0x01020101.
3. Compile the modified DFU Client:
  make -C client\pca10056\blank\armgcc
4. Return to the DFU example main folder and prepare a firmware package (in zip format) with the new firmware. See Creating a firmware package for more information:
  nrfutil pkg generate --hw-version 52 --sd-req 0x00 --application-version 0x01020101 --application client\pca10056\blank\armgcc\_build\nrf52840_xxaa.hex --key-file priv.pem app_dfu_package.zip --zigbee True --zigbee-manufacturer-id 123 --zigbee-image-type 321 --zigbee-comment good_image
Prepare the Zigbee Coordinator (look in the Zigbee Light Control example for instructions).
Use nrfutil to run the DFU:
1. Connect the DFU server nRF52840 Development Kit board to your computer. This board serves as the connectivity IC to the Zigbee network. This board does not require installation of any firmware. It will be flashed by nrfutil.
2. Run the following command to start the DFU process over Zigbee, where 608123456 is the serial number of the Zigbee OTA Upgrade Server for the Development Kit, and 11 is the 802.15.4 channel number:
  nrfutil dfu zigbee -f 007B-0141-01020101-good_image.zigbee -snr 608123456 --channel 11

The device resets and runs the new application. BSP_BOARD_LED_3 is lit.

Memory layout

When adding a bootloader to your device, pay attention to where in the device memory the different firmware components are located. The following table shows the memory layout used by the Zigbee OTA Upgrade Client. Since the Zigbee stack memory consumption is configurable, the default values in kB are assumed.

Usage	Memory range nRF52840
Bootloader settings	0x000F F000 - 0x0010 0000 (4 kB)
MBR parameter storage	0x000F E000 - 0x000F F000 (4 kB)
Bootloader	0x000F 8000 - 0x000F E000 (24 kB)
Zigbee settings	0x000E C000 - 0x000F 8000 (48 kB)
Application area (incl. free space)	0x0000 1000 - 0x000E C000 (940 kB)
Master Boot Record (MBR)	0x0000 0000 - 0x0000 1000 (4 kB)

Zigbee OTA Client: Memory layout