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 the following components:

Master Boot Record (MBR) – a bootstrap code used for starting the bootloader.
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.

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.

Note: - For information about all OTA features implemented by this Zigbee stack, see the PICS documents in the Implemented features section.; - The memory configuration must not be changed between firmware versions if the firmware is going to be upgraded using the OTA DFU.

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 nRF Util tool.

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 nRF Util utility automatically generates the OTA Upgrade file of the specified structure, using the provided hex file with the image for upgrading the firmware. See nRF Util setup below for information about how to install nRF Util.

Memory layout of the Zigbee OTA Upgrade Client

When adding a bootloader to your device (see Bootloader setup), 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	Memory size nRF52840 (kB)	Memory range nRF52833	Memory size nRF52833 (kB)
Bootloader settings	0x000F F000 - 0x0010 0000	4	0x0007 F000 - 0x0008 0000	4
MBR parameter storage	0x000F E000 - 0x000F F000	4	0x0007 E000 - 0x0007 F000	4
Bootloader	0x000F 8000 - 0x000F E000	24	0x0007 9000 - 0x0007 E000	20
Zigbee production configuration page	0x000F 7000 - 0x000F 8000	4	0x0007 8000 - 0x0007 9000	4
Zigbee settings	0x000E F000 - 0x000F 7000	32	0x0007 4000 - 0x0007 8000	16
Application area (incl. free space)	0x0000 1000 - 0x000E F000	974	0x0000 1000 - 0x0007 4000	471
Master Boot Record (MBR)	0x0000 0000 - 0x0000 1000	4	0x0000 0000 - 0x0000 1000	4

Zigbee OTA Client: Memory layout

Warning: In case the application uses both DFU and FDS modules, it is required to adjust bootloader settings to protect FDS pages from being overwritten by the DFU image transfer. By default, the DFU is configured to protect only the Zigbee settings page:
#define NRF_DFU_APP_DATA_AREA_SIZE (ZIGBEE_NVRAM_PAGE_SIZE * ZIGBEE_NVRAM_PAGE_COUNT + ZIGBEE_NVRAM_CONFIG_PAGE_SIZE * ZIGBEE_NVRAM_CONFIG_PAGE_COUNT)

If the application uses FDS, the size of the protected flash area must be increased:
#define NRF_DFU_APP_DATA_AREA_SIZE ((ZIGBEE_NVRAM_PAGE_SIZE * ZIGBEE_NVRAM_PAGE_COUNT + ZIGBEE_NVRAM_CONFIG_PAGE_SIZE * ZIGBEE_NVRAM_CONFIG_PAGE_COUNT) + (FDS_VIRTUAL_PAGES * FDS_VIRTUAL_PAGE_SIZE * sizeof(uint32_t)))

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:

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\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.

nRF Util setup

nRF Util 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 nRF Util in version 4.0.0. Refer to the nRF Util 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.

OTA Upgrade Client setup

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.

Setup

You can find the source code files in the following folder: <InstallFolder>\examples\zigbee\ota\client.

LED assignments

The example uses LED assignments as described in Zigbee BSP LED and button reference.

The following LEDs reserved for user application purposes are assigned in this example:

LED4 (BSP_BOARD_LED_3) – Used to indicate that the board is running the new application.

Testing

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

Precondition

To test the Zigbee OTA Upgrade process, you need at least two nRF52 Development Kit boards:

One nRF52840 Development Kit for the OTA Upgrade Server that distributes the new firmware.
One nRF52833 or nRF52840 Development Kit for the OTA Upgrade Client that will be updated.

Note: Because of the memory constraints, nRF Logger module is disabled by default in the OTA Upgrade Client example for nRF52833.

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\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 2 --app-boot-validation VALIDATE_ECDSA_P256_SHA256 --key-file priv.pem 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. Erase the flash memory on all connected DFU Client boards.
  nrfjprog -f nrf52 --eraseall
3. Flash the MBR as described in MBR setup.
  nrfjprog -f nrf52 -r --program ..\..\..\..\components\softdevice\mbr\nrf52840\hex\mbr_nrf52_2.4.1_mbr.hex --chiperase
4. Flash the bootloader as described in Bootloader setup.
  nrfjprog -f nrf52 -r --program bootloader\pca10056\blank\armgcc\_build\nrf52840_xxaa_mbr.hex
5. 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. 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-boot-validation VALIDATE_ECDSA_P256_SHA256 app_dfu_package.zip --zigbee True --zigbee-manufacturer-id 123 --zigbee-image-type 321 --zigbee-comment good_image --zigbee-ota-hw-version 52 --zigbee-ota-fw-version 0x01020101
Prepare the Zigbee Coordinator (look in the Zigbee Light Control example for instructions).
Use nRF Util 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. LED4 is lit.

Table of Contents