nRF5 SDK for Thread and Zigbee v1.0.0
Choose documentation:
Zigbee OTA Client Example

The OTA Client is typically only one of several ZCL clusters defined by the common Zigbee application. The client is based on the OTA cluster and Nordic's Bootloader and DFU modules that both create an integrated upgrade solution. This gives you a useful head start when populating the device with other functionalities.

The Zigbee OTA Client Example consists of two components:

  • bootloader - used to verify the integrity of the application and to install a new application image.
  • Zigbee OTA Client - a ZCL cluster that is needed 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 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 Client example accepts images that contain a new bootloader or application that contains the Zigbee stack. 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.

MBR setup

Zigbee OTA 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:

  1. Open a command prompt.
  2. Navigate to <InstallFolder>\components\softdevice\mbr\nrf52840\hex.
  3. In the PATH environment variable, ensure that there is a path to nrfjprog (from nRF5x Command Line Tools v9.2.0 or newer).
  4. 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 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 Thread 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 Master Boot Record (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 0x10001014 (see NRF_UICR_BOOTLOADER_START_ADDRESS).

To program the bootloader:

  1. Navigate to the armgcc folder of the example at <InstallFolder>\examples\thread\dfu\bootloader\pca10056\blank\armgcc.
  2. Open a command prompt.
  3. Run make to build the project.
  4. 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 3.6.0. Refer to the nrfutil installation section for details on possible ways to install the tool.

DFU client

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

The are two entities which participate in the Zigbee OTA process:

  • OTA client – the OTA 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 client incorporates a DFU controller (see Device Firmware Update process) that manages the DFU process. This means that each OTA target can be in a different state regarding the OTA process at a given point of time.
  • OTA server – the OTA server is a server that provides a firmware image. The OTA Server can be a standalone 3rd party device or it can be instantiated as a nRF52840 DK in conjuction with the nrfutil utility.

Because of the nature of the DFU implementation, the OTA Client cannot accept just any Zigbee OTA Upgrade file. The file must comply with several requirements. Apart from mandatory Zigbee OTA header, the image has to 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 nrfutil utility generates the OTA Upgrade file of the specified structure automatically, using the provided hex file with the image for upgrading firmware.

Configuration of the OTA Client

There are several defines in the main.c file of the Zigbee OTA Client example that can help you configure the parameters of the Zigbee OTA 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 Client (selection)

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 process, you need at least two nRF52840 Development Kit boards. One of these boards will be a OTA server that distributes the new firmware. The others will play the role of OTA clients that are updated.

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

  1. 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\thread\dfu. Use the path above.
  2. Build the bootloader:
    make -C bootloader\pca10056\blank\armgcc
  3. Prepare the Zigbee OTA Client:
    1. Install micro-ecc. This library is required by the Cryptography library , which is used by the Thread Secure DFU example.
    2. Compile the Zigbee OTA 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
  4. 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
  5. Prepare the firmware package for the DFU process:
    1. Modify the Zigbee OTA Client application. For example, add the following line to the main() function:
      bsp_board_led_on(BSP_BOARD_LED_3);
      Also, bumb the version: change the define OTA_UPGRADE_TEST_FILE_VERSION to 0x01020101
    2. Compile the modified DFU Client:
      make -C client\pca10056\blank\armgcc
    3. 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
  6. Prepare the Zigbee Coordinator (look in the Zigbee Light Control example for instructions).
  7. 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 is the serial number of the Zigbee OTA 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 Client - since the Zigbee stack memory consumption is configurable, the default avalues 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