Zigbee OTA Upgrade Server Example with image transfer over BLE

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 three components:

• bootloader - used to verify the integrity of the application and to install a new OTA Upgrade Server application image.
• ZCL cluster - an application that uses Zigbee OTA Upgrade Cluster to propagate a new image inside the Zigbee network.
• SoftDevice - used to transfer DFU images through the BLE connection.

The Zigbee OTA Upgrade Server is built in two versions:

• BLE-enabled solution - in this version, the user can transfer a new Zigbee image through a BLE connection. The server detects the new image and notifies the Zigbee network about it. The transfer of the distribution package with a Zigbee image is done by the same set of tools as with BLE Secure DFU Bootloader. The server upgrade is done by a slightly modified version of BLE Secure DFU Bootloader. The transfer is done in the application context, allowing the Zigbee OTA Upgrade server to stay connected to the Zigbee network. The new firmware is installed by the background bootloader.
• Zigbee-only solution - which requires you to program a Zigbee image into the device internal flash at address 0x80000, apart from the server application. This OTA Upgrade Server version is used by nrfutil tool as a connectivity firmware. Swapping the firmware image is done by changing contents of the device flash memory, which results in a reset. It is not possible to perform the OTA Server upgrade in this case.

  Note

  Due to its limited functionality, this solution is not described in this documentation.

  The Zigbee OTA Upgrade Server example accepts:
• application upgrade version for self-upgrade, and
• Zigbee images that contain an application which 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 for both server upgrade and Zigbee OTA image inside the distribution package must be signed.

SoftDevice usage

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

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

1. Navigate to the armgcc folder of the example at <InstallFolder>\examples\zigbee\experimental\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 --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.

Configuration of the OTA Upgrade Server

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:

• NRF_BL_FW_COPY_PROGRESS_STORE_STEP
• NRF_BL_SETTINGS_PAGE_PROTECT
• NRF_DFU_BLE_ADV_NAME (only for BLE transport)
• NRF_DFU_BLE_MIN_CONN_INTERVAL (only for BLE transport)
• NRF_DFU_BLE_MAX_CONN_INTERVAL (only for BLE transport)
• NRF_DFU_BLE_CONN_SUP_TIMEOUT_MS (only for BLE transport)
• NRF_DFU_BLE_BUFFERS_OVERRIDE (only for BLE transport)
• NRF_DFU_BLE_BUFFERS (only for BLE transport)
• NRF_DFU_PROTOCOL_FW_VERSION_MSG
• NRF_DFU_PROTOCOL_VERSION_MSG
• NRF_DFU_HW_VERSION
• NRF_DFU_SAVE_PROGRESS_IN_FLASH
• NRF_DFU_REQUIRE_SIGNED_APP_UPDATE

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

• NRF_BL_DFU_INACTIVITY_TIMEOUT_MS
• NRF_BL_DFU_CONTINUATION_TIMEOUT_MS
• NRF_BL_APP_CRC_CHECK_SKIPPED_ON_GPREGRET2
• NRF_BL_APP_CRC_CHECK_SKIPPED_ON_SYSTEMOFF_RESET
• NRF_BL_DFU_ENTER_METHOD_BUTTON
• NRF_BL_DFU_ENTER_METHOD_BUTTON_PIN
• NRF_BL_DFU_ENTER_METHOD_PINRESET
• NRF_BL_DFU_ENTER_METHOD_GPREGRET
• NRF_BL_DFU_ENTER_METHOD_BUTTONLESS
• NRF_BL_WDT_MAX_SCHEDULER_LATENCY_MS

The following parameters must not be changed:

• NRF_DFU_TRANSPORT_BLE
• NRF_DFU_APP_DOWNGRADE_PREVENTION
• NRF_DFU_SINGLE_BANK_APP_UPDATES
• NRF_DFU_BLE_SKIP_SD_INIT

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

• ZIGBEE_OTA_SERVER_USE_CLI

Setup

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

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 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\experimental\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 1 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. Flash the SoftDevice and the example according to the instructions in Running examples.
   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 Server:

      nrfjprog -f nrf52 -r --program dfu_server_s140.hex --sectorerase 

8. Use either nrfutil 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 nrfutil:
      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. nrfutil 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 nrfutil'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 BSP_BOARD_LED_3 on the server board. After the BLE transfer is finished, the LED stops blinking. If BSP_LED_3 is lit, the server has a valid Zigbee image installed in its internal flash memory.
10. Observe BSP_BOARD_LED_3 on the client board. After the Zigbee DFU is finished, the LED stops blinking.

The client board resets and runs the new application. BSP_BOARD_LED_3 is lit.

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