nRF5 SDK for Thread and Zigbee v4.1.0
Zigbee OTA Upgrade Server Example with image transfer over BLE

Table of Contents

This information applies to the nRF52840 SoC only.

This example demonstrates how to transfer a Zigbee OTA image over a BLE connection and distribute it in the Zigbee network. The example provides an implementation of an OTA Upgrade Server as a BLE/Zigbee multiprotocol device.

The OTA Server is a device that serves as the OTA image file server inside the Zigbee network. It must be mains powered and have a capability to store at least one firmware image for OTA Upgrade Clients. This example uses only internal flash to store images, limiting its functionality to store only a single image.

The server is based on the OTA Upgrade Cluster and Nordic's Bootloader and DFU modules that create an integrated upgrade solution.

The Zigbee OTA Upgrade Server Example consists of the following components:

The Zigbee OTA Upgrade Server is built in two versions:

To protect the target device against malicious attackers who try to impersonate the rightful sender of the firmware update, the initialization packet for both server upgrade and Zigbee OTA image inside the distribution package must be signed.

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.

SoftDevice usage

The Zigbee OTA Server Example with BLE transport uses the SoftDevice. For instructions about how to flash the SoftDevice, see Running examples.


Memory layout of the Zigbee OTA Upgrade Server

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 Server. 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)
Bank 1 (distributed Zigbee image) (OTA server application end address) - 0x000E C000
Application area (excl. free space) 0x0025 0000 - (OTA server application end address)
SoftDevice S140 0x0000 0000 - 0x0025 0000 (148 kB)
Zigbee OTA Server: Memory layout

Bootloader setup

The bootloader for the Zigbee OTA Upgrade Server 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 of the server application 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 Master Boot Record (MBR), which is part of the SoftDevice, is responsible for starting the bootloader. MBR can be provided as part of the SoftDevice (if application uses a SoftDevice) or as a stand-alone binary firmware (if application does not use a SoftDevice). To start the bootloader, the MBR must know the start address of the bootloader. This start address is defined either in the MBR itself or in UICR.BOOTLOADERADDR. It must be set to the correct value when you program the bootloader. See the S132 SoftDevice Specification for more details.

To program the bootloader:

  1. Navigate to the armgcc folder of the example at <InstallFolder>\examples\zigbee\ota\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.
Note
The size of the bootloader is fixed for the lifetime of the device. This is because it is not possible to safely update the location that stores the start address of the bootloader (MBR_BOOTLOADER_ADDR). See the SoftDevice Specification for more information.

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.


OTA Upgrade Server setup

There are several configuration parameters available in the sdk_config.h file that can help you configure the Secure DFU Bootloader. Not all of them can be changed or are relevant for the Zigbee OTA Upgrade Server.

You can change the the following parameters:

The following parameters have no effect on the Zigbee OTA Upgrade Server functionality:

The following parameters must not be changed:

The Zigbee OTA Upgrade server has one additional parameter, which enables the CLI interface:


Setup

You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\zigbee\ota\experimental_server.

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:


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 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 Server 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\zigbee\ota. Use the path above.
  2. Build the bootloader:
    make -C bootloader\pca10056\blank\armgcc
  3. Prepare the Zigbee OTA Upgrade Client (see Zigbee OTA Upgrade Client Example for instructions in the Testing section).
  4. 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: 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
  5. Prepare the Zigbee Coordinator (see Zigbee Light Control example for instructions in the Testing section).
  6. Prepare the Zigbee OTA Upgrade Server:
    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 Server:
      make -C server\pca10056\s140\armgcc
    3. Return to the Zigbee OTA example main folder and generate a bootloader settings hex file:
      nrfutil settings generate --family NRF52840 --application server\pca10056\s140\armgcc\_build\nrf52840_xxaa.hex --application-version 1 --bootloader-version 1 --bl-settings-version 2 settings.hex
    4. Use mergehex (part of the nRF5x Command Line Tools) to merge the server hex file and the bootloader settings hex file:
      mergehex -m server\pca10056\s140\armgcc\_build\nrf52840_xxaa.hex settings.hex -o dfu_server_s140.hex
  7. Flash the DFU Server to the server board:
    1. Connect one DFU Server board to the computer.
    2. Erase flash memory on DFU Server board.
      nrfjprog -f nrf52 --eraseall
    3. Flash the SoftDevice and the example according to the instructions in Running examples.
    4. Flash the bootloader as described in Bootloader setup.
      nrfjprog -f nrf52 -r --program bootloader\pca10056\blank\armgcc\_build\nrf52840_xxaa_blank.hex
    5. Flash the merged DFU Server:
      nrfjprog -f nrf52 -r --program dfu_server_s140.hex --sectorerase
  8. Use either nRF Util or a mobile app to transfer the Zigbee image distribution package. If you use the mobile app, you can use either the nRF Toolbox app (Android: 1.17 or later, iOS: 4 or later) or the nRF Connect app (currently available only on Android 4.4 or later).
    1. With nRF Util:
      1. Connect a Development Kit board to your computer. This board serves as a connectivity IC to run the DFU on the device that contains the DFU bootloader.
      2. Enter the following command to start the DFU process over BLE, where app_dfu_package.zip is the name of the firmware package that you want to upload:
        nrfutil dfu ble -ic NRF52 -f -pkg app_dfu_package.zip
      3. nRF Util will ask you to choose a serial port. The port you specify must correspond to the port of the development kit that you connected.
      4. To choose a specific target device, use nRF Util's -n or -a options. For more information, enter:
        nrfutil dfu ble --help
    2. With a mobile app, transfer the zip firmware package that you want to upload to the mobile device:
      1. On iOS:
        1. Connect the mobile device to your computer and open iTunes.
        2. Select the mobile device and then Apps > nRF Toolbox (or nRF Connect).
        3. Drag and drop a file directly into the application's internal storage. Alternatively, send an email attachment to the app from the mobile device itself. See the application documentation for more information.
      2. On Android:
        1. Connect the mobile device to your computer.
        2. Enable file transfer between the computer and the device.
        3. Copy the zip file into a folder of your choice.
    3. Use the nRF Toolbox or nRF Connect app to select a target device and a zip package and to start the process.
  9. Observe LED4 on the server board. After the BLE transfer is finished, the LED stops blinking. If LED4 is lit, the server has a valid Zigbee image installed in its internal flash memory.
  10. Observe LED4 on the client board. After the Zigbee DFU is finished, the LED stops blinking.

The client board resets and runs the new application. LED4 remains lit.


Documentation feedback | Developer Zone | Subscribe | Updated