On/Off Server Switch OTA Client ZED

• Introduction
• Software Prerequisites
• Functional Description
  • Software Overview
    • Application Files
• Configuration With SysConfig
  • OTA Client Image Slot Configuration
• Example Usage
  • Buttons
  • Commissioning the Device Into the Network
  • OTA Client Required Images
  • Flashing Client Image
    • Flashing with Uniflash
    • Flashing with CCS
  • OTA Client Signing Image for Server

Introduction

This document discusses how to use the On/Off Server Switch OTA Client ZED Sample App and the different parts that compose it. On/Off Server Switch OTA Client Sample Application is an example that exercises different features of TI Zigbee for a Zigbee End Device (ZED) implementation.

Some of the features exercised include:

• Zigbee End Device commissioning
• Switch device that acts as Initiator of Finding and Binding
• On/Off Toggle data frame
• Support for OTA upgrades

Software Prerequisites

• Code Composer Studio™ (CCS) v12.7 or newer

• SimpleLink™ LOWPOWER SDK

Functional Description

Software Overview

This section describes the software components and the corresponding source files.

Application Files

The On/Off Server Switch OTA Client ZED Sample App works in conjuction with a Zigbee Coordinator (ZC), which is assumed to have formed a Zigbee network that the On/Off Server Switch OTA Client ZED can join. Upon startup, On/OffSwitch OTA Client ZED sends a commissioning request to attempt to join the network. Once it has joined the network successfully, BTN1 on the Launchpad can be pressed to send a Toggle command.

The OTA Client will automatically find a OTA Server in the network and query it for a new image. If new image is avaiable, it will then reqeust to start the OTA upgrade process.

• on_off_switch_ota_client.c: Contains the application's event loop, device initialization function calls, and commissioning and on/off toggle command specific logic.

• ota_client_interface.c: Handles the OTA Client initialization and signals from the stack.

Configuration With SysConfig

SysConfig is a GUI configuration tool that allows for TI driver and stack configurations.

To configure using SysConfig, import the SysConfig-enabled project into CCS. Double click the *.syscfg file from the CCS project explorer, where * is the name of the example project. The SysConfig GUI window will appear, where Zigbee stack and TI driver configurations can be adjusted. These settings will be reflected in the generated files.

The example project comes with working default settings for SysConfig. For the purposes of this README, it is not recommended to change the default driver settings, as any changes may impact the functionality of the example. The Zigbee stack settings may be changed as required for your use case.

Note that some Zigbee settings are stored in non-volatile storage, and Zigbee prioritizes stored settings over SysConfig settings. To guarantee SysConfig settings are applied, perform a factory reset of the device to clear non-volatile storage.

OTA Client Image Slot Configuration

The MCUBoot settings must match in both MCUBoot example and OTA Client Example.

OTA Client Example

OTA Client example -> on_off_switch_ota*.syscfg -> MCUBoot App

• The default settings here are to be used as referrences to set MCUBoot seetings.

• When updating the image slots, you must also update the on_off_switch_ota*.syscfg -> TI DRIVERS -> STORAGE INTERFACES -> NVS:

  • CONFIG_NVSINTERNAL1 (on-chip)

  • CONFIG_NVSEXTERNAL (off-chip)

    The region base/size will need to match the secondary image slot base/size.

• If using OTA compression, the secondary image slot can be up to 27% smaller than primary image slot.

• NOTE: When toggling the "enable compression" setting, the slot settings will be changed to high level defaults, which will need to be modified for app function.

MCUBoot example

MCUBoot example -> mcuboot.syscfg -> MCUBoot

MCUBoot Settings:

• Upgrade Mode - Set to Overwrite mode.
• Enable Image Compression - Check this box when using Compression.
• Enable External Flash - Check this box when using External Flash
• Bootloader Configurations -
  • Base: 0x00000000
  • Size: MCUboot App -> Base Address
• Image 1 -> Primary Image -
  • Base Address: MCUboot App -> Base Address
  • Image Size: MCUboot App -> Slot Size
• Image 2 -> Secondary Image -
  • Base Address:
    • On-Chip: (MCUboot App -> Base Address) + (MCUboot App -> Slot Size)
    • Off-Chip: 0x00000000
  • Image Size:
    • If using Compression: MCUboot App -> Compressed Slot Size
    • If NOT using compression: MCUboot App -> Slot Size

Example Usage

This section describes how to use this sample application.

Buttons

• BTN-1: Sends On/Off Toggle commands

Commissioning the device Into the network

Zigbee End Devices can only join networks. At startup, the On/Off Server Switch ZED Sample App goes into ZB_BDB_NETWORK_STEERING mode where it will first send a Beacon Request, wait for beacons, and then send a Network Commissioning Request packet to a ZC/ZR. The ZR/ZC then responds and the commissioning process will continue until the ZED is joined into the network.

OTA Client Behavior

15s after joining the network, the OTA Client will start its OTA process. It first sends a Match Descriptor Request. If an OTA Server is found, 60s later the OTA Cient will start the upgrade process by sending a Query next Image Request.

OTA Client Required Images

This OTA Client requires two images to be flash to the device:

1. MCUBoot Image

   • Example: <SDK_INSTALL_DIR>/examples/nortos/<PLATFORM>/mcuboot/mcuboot

2. Signed on_off_switch_ota_client image binary. This will be writen into image slot 1 in flash.

   • This image is created with the post build steps. Look for the file "Project name"_ota_1st_slot.bin.This image will always be uncompressed.

   • The "Project name"_ota_2nd_slot.bin is meant for the secondary slot and may be compressed if enabled. This image is meant to be signed with a Zigbee OTA header and used in the OTA upgrade.

NOTE: Both ota_*_slot.bin images will have the same application version. To update the application version, there are two location:

1. OTA Client example -> on_off_switch_ota*.syscfg -> Image BootLoarders -> MCUBoot Application -> Version
2. on_off_switch_ota_client.c --> g_dev_ctx.ota_attr.file_version

Flashing Client Image

Flashing with Uniflash

1. Connect device
2. Under Program, first select MCUBoot flash image path.
3. Then click + to add \
4. Enter Load Addr. This will be the base address of the Primary Image slot.

5. Click Load Images

   Flashing with CCS

6. With MCUBoot project highlighted, click debug on toolbar (or navigate to Run -> Debug). This will flash MCUBoot.

7. Once the Deubugger is connected, navigate to Tools -> On-Chip Flash. In the On-Chip Flash window, select Do not erase. NOTE: deselect Do not erase to flash another image (mcuboot or other).
8. Now we need to load Image 1 into its slot.
   1. Navigate to View -> Memory Browser.
   2. In the Memory Browser window, next to the Save Memory icon, click the down arrow and select Load Memory.
   3. Set File Type to Binary and file to the path of \
   4. Set Start Address to the base address of the Primary Image slot. Then click finished.

OTA Client Signing Image for Server

To test this OTA Client, the CC13XX_26XX family of devices with the _ota_server example can be used. Prepare the client image by signing it with /tools/zstack/zigbee_ota_image_converter/zOTAfileGen.

zOTAfileGen args:

zOTAfileGen inputFileName outputDirectory manufactCode imgType fileVer

Example call:

OTAfileGen <EXAMPLE_BUILD_DIR>\onoff_switch_ota_client_offchip_src_LP_EM_CC2340R5_freertos_ticlang_ota.bin <OUTPUT_DIR> BEBE 2340 00000002

The output of this tool can then be provided to the OtaServer PC tool.

For more details, please follow the ota_server readme and the Zstack user guide in the CC13XX_26XX SDK.