Z-Stack OTA Upgrade

1. Introduction

This document is a Developer’s Guide for the Over the Air (OTA), Upgrade Cluster in Texas Instruments Z-Stack ZigBee platform.

1.1 How to Read this Document

This document is presented in 3 parts. The first part, OTA Overview, gives a functional description of the OTA subsystem. The second part, Using the OTA Sample Application, provides step by step instructions for building, installing, and running the Sample OTA application that comes with Texas Instruments Z-Stack. The third part, Adding Client Functionality to an Application, provides step by step instructions for configuring a Z-Stack application to operate as an OTA Client.

1.2 Definitions, Abbreviations, Acronyms

Term Definition
IEEE 802.15.4 The IEEE 802.15.4 protocol specifies the physical and medium access layers for wireless Personal Area Networks targeted at low power, low data rate applications.
OTA Over the Air
OTA Client A device capable of down loading an image using the OTA cluster from an OTA Server.
OTA Server A device capable of hosting an image for download via the OTA cluster by an OTA Client.
PAN Personal Area Network
SoC System on Chip – processor core and radio are integrated on same device

1.3 References

[1] ZigBee Alliance Document 095264, ZigBee OTA Upgrade Cluster Specification.

[2] Reference to BIM specification.

2. OTA Overview

The OTA, Over the Air, Upgrade Cluster provides a standard mechanism for wirelessly upgrading a ZigBee devices firmware. Over the air upgrade sessions take place between a client and server. The OTA Client downloads an OTA Upgrade Image. The OTA Server hosts OTA Upgrade Images.

Texas Instruments Z-Stack ZCL, ZigBee Cluster Library, provides support for client and server operation of the OTA Upgrade Cluster. The Texas Instruments Z-Stack implementation of the OTA Upgrade Cluster consists of the following components:

  • BIM (TI’s Boot Image Manager)
  • OTA Image Converter Applications ZCL Implementation of the OTA Protocol
  • Sample OTA Application
  • OtaServer PC Application

2.1 OTA Theory of Operation

This section provides a simple description of how the OTA Upgrade Cluster is used to update a devices firmware. For more detail, see the ZigBee Alliance Document 095264, ZigBee OTA Upgrade Cluster Specification [1].

Communication via the OTA Upgrade Cluster takes place using the following command messages shown in the simple message chart below:

image13

Figure : OTA Message Exchange

The Image Notify message is sent unicast or is broadcast by an OTA Server to notify OTA Clients that new images are available. The Image Notify does not contain information about the new images. The Image Notify only indicates new images are available. OTA Clients determine if these new images apply to them using the Query Next Image request and response messages.

Periodically, or after receipt of an Image Notify message, an OTA Client sends a Query Next Image Request message to an OTA Server. The Query Next Image Request message contains the version of the firmware currently running on the client. On receipt of the Query Next Image Request, the server decides if an image update should take place and which image the client should update to. The server responds to the query next image request with a Query Next Image Response message.

The Query Next Image Response message may instruct the client to download new firmware, or it may inform the client that no firmware is available. Should a download take place, the client controls the download. During the download, the client sends Image Block Request messages to the server and receives Image Block Response messages from the server with chunks of the upgrade image. The client writes the received image blocks to a secondary storage location. In the current Z-Stack sample applications, this secondary storage is off-chip flash memory.

After the client has downloaded the entire upgrade image, the client sends the Upgrade End Request message to the server. The server then responds with an Upgrade End Response message. The Upgrade End Response message contains information about when the client should switch to the new firmware. The client may switch to the new firmware immediately or it may be instructed to wait a specified period of time.

In the Z-Stack sample applications, when it is time for a client to switch to the new image, the client writes the external flash accordingly to TI BIM specification [2] indicating new firmware is available, then the client reboots. BIM on the client sees that the new image is available and copies the new image from the external flash to the operational memory space; then the new firmware is started.

2.2 OTA Image Converter Applications

Some tools are used to convert CCS output binaries into Zigbee upgradable binaries; first CCS will output a .bin file of the sample app being compiled, which is used by oad_image_tool.exe command line tool to format the binary header according to BIM specifications [2] for an upgradable binary read from the external flash, then this binary (with _oad.bin appended to the binary name) will be used by zOTAfileGen.exe command line to append Zigbee OTA cluster header at the beginning of the binary content producing a .zigbee file which is the one send over the air.

Note: To see how these tools are used, see post-Build actions in any OTA client sample app, such as zr_switch_ota_cc26xlp. These tools requires Microsoft Windows XP or newer.

After the binary conversion the format of the file will be the following:

Zigbee OTA Header | OAD header | Zigbee application binary

2.3 OtaServer PC Tool

The OtaServer PC tool is the front end of Texas Instruments’ Z-Stack OTA Server sample application. The OtaServer PC tool requires Microsoft Windows XP or newer. The OtaServer connects to a CC2652 Launchpad running the zc_ota_server sample application via a serial port (UART over USB).

2.3.1 OTA Upgrade Image File Format

This section contains a simple description of the OTA Upgrade Image File Format. For more detail, see the ZigBee Alliance Document 095264, ZigBee OTA Upgrade Cluster Specification.

OTA Update Image files are broken into the following parts:

  • Image Header
  • Image Data (OAD header | Zigbee application binary)
  • Certificate

The Image Header contains the following information about the image:

  • Header Version
  • Manufacturer ID
  • Image Type
  • File Version
  • Stack Version
  • Header String
  • Image Size
  • Hardware Version

The Image Data contains the machine code for the new firmware (OAD header | Zigbee application binary) from the CCS binary conversion process compatible with BIM specification.

2.3.2 OTA Image Converter Command Line Arguments

The first argument to the OTA Image Converter is the CCS BIM compatible image (OAD header | Zigbee application binary), after which the path in which the output file will be placed (the path must exist).

The following arguments are mandatory in exactly the following order:

  • Image Manufacturer Identifier
  • Image Type Identifier
  • Image Version

zOtafileGen.exe otaFile_oad.bin <CCS workspace>\otaFiles BEBE 2652 00000002

Note: the OtaConverter.exe program can be found here: simplelink_zigbee_sdk_plugin_x_xx_xx_xx\tools\zigbee_ota_image_converter

2.3.2.1 Image Manufacturer Identifier

The Manufacturer Identifier is a 16-bit hexadecimal number that specifies the manufacturer of the device the OTA Upgrade Image is intended for. Manufacturer IDs are assigned to ZigBee device manufacturers by the ZigBee Alliance.

2.3.2.2 Image Type Identifier

The Type Identifier is a 16-bit hexadecimal that specifies the type of device the OTA Upgrade Image is intended for. The type ID is manufacturer specific and typically corresponds to the model of the device being upgraded.

2.3.2.3 Image Version

The Image Version is a 32-bit hexadecimal that specifies the version of the OTA Upgrade Image.

2.4 Z-Stack Implementation of the OTA Upgrade Cluster for Client Device

The embedded firmware for the OTA Upgrade cluster for client device in Z-Stack is implemented in the following files:

  • ZCL functionality
    • zcl_ota.c
    • zcl_ota.h
    • ota_client_app.c
    • ota_client_app.h
  • BIM functionality
    • crc32.c
    • crc32.h
    • flash_interface_ext_rtos_NVS.c
    • oad_image_header_app.c
    • oad_image_header_app.h
    • oad_image_header.h
    • oad_switch_agama.c
    • oad_switch_agama.h

2.4.1 ZCL functionality

2.4.1.1 zcl_ota.c and zcl_ota.h

The zcl_ota.c and zcl_ota.h files contain the following functionality:

  • Format OTA Upgrade Cluster messages
  • Process the incoming image data for Zigbee OTA header, BIM header and application binary data.
2.4.1.2 ota_client_app.c and ota_client_app.h

The ota_client_app.c, ota_client_app.h, files contain the following functionality:

  • Application logic required to query server, download and upgrade to the new image.
  • Dedicated endpoint definition to host OTA client application (see ZCL_OTA_ENDPOINT definition).

As these files contains the application logic to perform the upgrade, is expected that application developers modify this to meet their specific requirements into how to perform the upgrade.

2.4.2 BIM functionality

BIM files added to the project are to provide a set utilities that allows the proper generation of a binary compatible with TI BIM architecture and validate the binaries received OTA, further details on BIM specification can be found in [2].

2.4.2.1 crc32.c and crc32.h

These files contain utility functions to calculate the CRC32 of the binary received to validate that the received binary is not corrupted.

2.4.2.2 flash_interface_ext_rtos_NVS.C

This file provides the necesary API to perform the read/write operations of the binary in the storage system (in this case an external flash with SPI interface).

2.4.2.3 oad_image_header_app.c, oad_image_header_app.h and oad_image_header.h

Here is defined the header structure required by BIM to identify a valid image and its properties. This header is also validated during the OTA upgrade process in zcl_ota.c.

2.4.2.4 oad_switch_agama.c and oad_switch_agama.h

Sample code that implements a mechanism to invalid the current image loaded into internal flash to allow BIM revert to Factory New Image.

2.5 Z-Stack Implementation of the OTA Upgrade Cluster for Server Device

The embedded firmware for the OTA Upgrade cluster for a server device in Z-Stack is implemented in the following files:

  • ZCL functionality
    • ota_srv_app.c
    • ota_srv_app.h
    • ota_common.c
    • ota_common.h
  • Serial interface
    • znp_app.c
    • znp_app.h
    • (npi files)

2.5.1 ZCL functionality

2.5.1.1 ota_srv_app.c and ota_srv_app.h

The ota_srv_app.c, ota_srv_app.h, files contain the following functionality:

  • Application logic required serve upgrade images.
  • Dedicated endpoint definition to host OTA server application (see ZCL_OTA_ENDPOINT definition).
2.5.1.2 ota_common.c and ota_common.h

The ota_common.c and ota_common.h files contain OTA functionality like parsing OTA headers that are used by OTA Server applications, the OtaServer PC Tool, and the OTA Image Converter.

2.5.2 Serial interface

2.5.2.1 znp_app.c and znp_app.h

These files contain the stack application to process the serial messages coming from the host application.

2.5.2.2 NPI

These group of files implements the generic serial interface required that passes the serial frames up to the application.

2.5.3 OTA Upgrade API

Little interaction between the application and the ZCL OTA is necessary with Z-Stack’s implementation of the OTA Upgrade Cluster. Z-Stack provides an OTA API to notify the application about the beginning and end of an OTA; to give application the ability to permit/disallow OTA operation; to give the application the ability to send an image notify; and to give the application the ability to query servers for the next upgrade cluster.

2.5.3.1 OTA Callback Events

OTA application can notify about when the OTA upgrade starts or is completed in the application context inside of ota_client_app.c module in the function OTA_ProcessOTAMsgs(). The following events are provided to the application:

  • ZCL_OTA_START_CALLBACK
  • ZCL_OTA_DL_COMPLETE_CALLBACK

Events are sent as OSAL messages with the following code:

typedef struct
{
  osal_event_hdr_t hdr;
  uint8 ota_event;
} zclOTA_CallbackMsg_t;

The ZCL_OTA_START_CALLBACK is sent to indicate a successful or failed attempt to start a download. The ZCL_OTA_DL_COMPLETE_CALLBACK is sent when a download completes indicating the download completed successfully or failed to complete.

2.5.3.2 zclOTA_RequestNextUpdate

The zclOTA_RequestNextUpdate() function is called by applications to send an OTA Query Next Image message to an OTA Server.

The method of discovering servers and determining when to query the server is left up to the application. In the Z-Stack sample applications, the application performs a match descriptor request on the OTA Upgrade Cluster to discover a Server. The application then calls zclOTA_RequestNextUpdate() on all discovered servers until the application receives a successful ZCL_OTA_START_CALLBACK event.

2.5.3.3 zclOTA_SendImageNotify

The zclOTA_SendImageNotify() function can be called on an OTA Server to send an Image Notify message.

2.5.3.4 zclOTA_PermitOta

The zclOTA_PermitOta() function can be called to enable or disable OTA Upgrades. When OTA is disabled, the OTA Client ignores Image Notify messages and the OTA Server sends no image available responses to Query Next Image Request messages.

2.5.4 OTA Client Memory Partition

When an OTA Client downloads a new upgrade image, it must store the image in secondary storage, where the binary is validated, currently only external flash is supported in SimpleLink CC26x2 Launchpad devices. Later, when the device reboots, BIM validates the binary received and copies the image from secondary storage into the operational space. The memory partition is fully described in [2].

3. Using the Sample OTA Applications

The sample application supplied for the OTA update feature are:

  1. zc/zr/zed_ota_server: This example application contains the OTA Server.
  2. zc/zr/zed_switch_ota: This example application contains the OTA Client.

3.1 Required Materials

The following equipment and software are required for use of the Sample OTA Applications:

  • Code Compose Studio™ (CCS) 7.4.0.00015 or newer
  • SimpleLink™ CC26x2 SDK 1.60.00
  • SimpleLink™ Zigbee SDK plugin 1.60.10
  • Two Simplelink CC26x2R1 launchpad

3.2 Building and Downloading Target Applications

This section describes the process of building and downloading the Sample OTA Application. Two boards need to be programmed. One board will run the OTA Server application. One board will run the Switch OTA application.

IMPORTANT NOTICE: Simplelink CC26x2R1 launchpad board come out-of-the-box with BLE project zero sample app flashed. This sample application as part of its initialization process will create a default Factory New image into the external flash of the launchpad. Zigbee OTA application assumes that any Factory New image exist, as the downloaded image will be stored as the second image available (right after Factory New image). If no Factory New image exists, the OTA client will abort the upgrade process.

3.2.1 OTA BIM

The OTA Boot Image Manager (BIM) application is only required for the OTA Clients and is automatically imported with the Switch OTA sample application. The BIM project can be located here:

simplelink_cc26x2_sdk_1_xx_xx_xx\examples\nortos\CC26X2R1_LAUNCHXL\common\bim\nortos\ccs

This sample application is flashed at the last page of flash along with a modified CCFG registers forcing the start address to be the BIM address, this allows BIM execute when the MCU is powered and it may decide the boot sequence.

As CCFG used by BIM can be located here:

simplelink_cc26x2_sdk_1_xx_xx_xx\examples\nortos\CC26X2R1_LAUNCHXL\common\bim\nortos\src

And it’s linker file here:

simplelink_cc26x2_sdk_1_xx_xx_xx\source\ti\common\cc26xx\ccs

This application must be downloaded along with the Zigbee application that supports the OTA client (Switch OTA application).

3.2.2 OTA Client Applications

In order to generate a bootable image, the application binary must have an offset of 0x50 bytes in which the OAD header (header parsed by BIM) is stored. This offset is defined in the linker file cc26x2lp_ota.cmd, along with the flash pages for the application (BIM takes the last page for itself). Also CCFG is removed from linker file as BIM already defines it; is important that application do not overwrite CCFG configuration, as this would prevent the execution of the boot sequence, which would cause the upgrade process to not work. As reference, the linker file with the modified flash regions can be found in:

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_switch_ota\tirtos\ccs

To reposition the reset vector defined in the link, the configuration file needs to be modify as follow appending the following definition for the reset vectors:

/*
* Address to place reset vector on target device.
* See the application's linker command file for further section
* information.
*/
m3Hwi.resetVectorAddress  = 0x50;

The oad_app.cfg with this adjustment to the reset vector is located here as reference:

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\common\rtos

Sample applications that implement OTA client can be found in:

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_switch_ota\tirtos\ccs

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_switch_ota\tirtos\ccs

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zed_switch_ota\tirtos\ccs

for Coordinator, Router and End device.

3.2.2.1 Generate OTA binaries

To generate the upgradable binaries, make sure the last postbuild action is set in the project and is configured with the right application parameters

${TOOLS_OAD_ZIGBEE_DIR}/zOTAfileGen.exe ${PROJECT_LOC}/${ConfigName}/${ProjName}_oad.bin ${PROJECT_LOC}/${ConfigName}/ BEBE 2652 00000001

From which:

  1. BEBE is the manufacturer ID
  2. 2652 is the image type
  3. 00000001 is the version of the application image.

image1

These parameters are used to generate the OTA header appended to the binary, but the actual parameters used by the application in run time are set by MACROS at compile time in the Predefined Symbols:

OTA_MANUFACTURER_ID=0xBEBE

OTA_TYPE_ID=0x2652

OTA_APP_VERSION=0x00000001

image2

There are other compilation flags required in order to configure the OTA files to work as Client device

OTA_CLIENT_CC26XX use in sample application files to integrate OTA functionality.

OTA_CLIENT=TRUE Enables the client side of the cluster in zcl_ota.c

OTA_HA Enables OTA for HA profile instead of SE wich requires additional security level (SE not supported in this release).

SWITCH_OTA Enables application permission to perform OTA upgrade. (the code enabled is meant to be controlled by application to decide wheter or not OTA upgrade process is allowed, see zclOTA_Permit() and zclOTA_PermitOta() API).

Once these parameters have been set, the application can be compiled and flashed into the device. Also .zigbee file will be generated at the workspace location which can be used later with by the server to perform an OTA upgrade.

3.2.3 OTA Server

The OTA server application uses a serial interface to communicate the host application (which serves the binaries) with the remote OTA client. The example application can be located in:

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_ota_server\tirtos\ccs

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_ota_server\tirtos\ccs

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zed_ota_server\tirtos\ccs

Even when the OTA server is not restricted to any logical device implementation, it is not recommended to use an End Device for this purpose as it increases the upgrade time considerably due to End Device routing limitations.

The serial configuration by default for this sample application is:

Baud: 115200

Flow: CTS/RST

Parity: None

Stop bits: 1

Data bits: 8

3.2.3.1 OTA Server Compilation Flags

The OTA server application requires the following compilations flags:

OTA_SERVER=TRUE Enables the OTA server functionality in zcl_ota.c

OTA_HA Enables OTA for HA profile instead of SE which requires additional security level (SE not supported in this release).

The serial interface requires the following flags:

NPI Enables the NPI, which is the generic serial interface.

NPI_USE_UART Instruct the NPI to use UART.

ZTOOL_P1 Enables callbacks to parse the incoming serial messages.

MT_TASK Enables main task to parse the incoming serial messages.

MT_APP_FUNC Enables processing of application specific serial commands.

MT_SYS_FUNC Enables processing of system message commands.

MT_ZDO_FUNC Enables processing of ZDO message commands.

MT_ZDO_CB_FUNC Enables notifications to host application about ZDO process.

MT_UTIL_FUNC Enables processing of util message commands.

MT_OTA_FUNC Enables processing of OTA application messages.

3.3 Performing an Image Update

3.3.1 OtaServer Operation (desktop application)

  1. Build and flash an Ota Server device that is one of the following: a Coordinator, Router or an End Device.
  2. Select a file method:
    1. Use Image File – Select a single image file for the update. Using this option, it is possible downgrade an image. To downgrade uncheck the “Version Check Image File” in the Options menu.
    2. Use Image Directory – All images in the directory are automatically loaded and the newest compatible image is automatically selected during the Image Notify process. It is not possible to downgrade image files using this option.

image3

  1. The File List display area will now show the available image(s) for the updating of OTA devices. Expanding the plus sign on each image provides extra information about the image. It is not possible to select image files in the File List display area.

image4

Figure : OTA Server Image Selection

  1. Check and modify the Port Settings as necessary. Pressing the Open button will open the port and OtaServer will begin monitoring the Ota Server device. If OtaServer does not see a proper regular message from Ota Server device, it will automatically close the port and report the issue to the user.

  2. Optionally disable Image Version Checking in the OTA Server.

    Options -> Uncheck “Version Check Image File”

    This can be used to allow more flexible image selection including download older revision files.

If your Ota Server Device is a router follow these steps:

  1. The Device List will update within 5 seconds with the PAN IDs.
  2. If any of PAN IDs say “In Network” your Ota Server Device has joined that PAN ID.
  3. If that is not the desired PAN ID or you wish to see all the PAN IDs available: Right click on the “In Network” PAN ID, and then select “Leave PAN”. It may take up to a minute for the device to reset and scan for PANs. Right click on one of the displayed PAN IDs and select “Join PAN”. When the PAN ID shows “In Network” you are ready to proceed to the next step.
  4. Right click on the “In Network” PAN ID and select Device Scan.
  5. As nodes respond to the request they will appear in the device list. Note that only OtaClient coordinators and routers will respond. OtaClients that are end devices will only appear as they join the network.

If your Ota Server Device is a coordinator, follow these steps:

  1. The Device List will update within 5 seconds with your coordinators PAN ID.
  2. Any nodes that have already joined the pan will not be displayed. Any nodes that join after OtaServer displays the PAN ID will be displayed. The easiest thing to get all the nodes displayed is to right click on the PAN ID that is “In Network”. Selecting “Leave PAN” causes the Ota Server Device to reset. It may take a number of minutes for all the nodes to rejoin.
  3. As each node joins OtaServer will automatically read the attributes of each node. Press the plus next to the node name to see the information.

If your Ota Server Device is an end device (not recommended), follow these steps:

  1. The Device List will update within 5 seconds with the PAN IDs.
  2. If any of PAN IDs say “In Network” your Ota Server Device has joined that PAN ID.
  3. If that is not the desired PAN ID or you wish to see all the PAN IDs available: Right click on the “In Network” PAN ID, and then select “Leave PAN”. It may take up to a minute for the device to reset and scan for PANs. Right click on one of the displayed PAN IDs and select “Join PAN”. When the PAN ID shows “In Network” you are ready to proceed to the next step.
  4. Right click on the “In Network” PAN ID and select Device Scan.
  5. As nodes respond to the request they will appear in the device list. Note that only OtaClient coordinators and routers will respond. OtaClients that are end devices will NOT appear as they join the network.

These remaining steps are for all configurations:

  1. There are two ways to start the image download:

    Right click a Device List node and select Image Notify.

    <Or>

    Right click the “In Network” PAN ID and select Broadcast Image Notify.

  2. The image download(s) will begin shortly and may take quite a while (minutes) to complete.

  3. When the image download is successful, the node is deleted from the Device List and will reappear in a few minutes after the updated device completes its OTA image upgrade process. If your Ota Server Device is an end device, you will need to do a Device Scan after the device completes the OTA process to see the node again.

4. Adding Client Functionality to an Application

The following steps must to be taken to add OTA Client functionality to a Z-Stack application:

  1. Add the OTA and BIM files
    1. Source code to the application.
  2. Replace linker and app configure file
  3. Add OTA include directory to the list of include directories.
  4. Add the configuration OTA compile flags
  5. Add the OTA code under OTA_CLIENT_CC26XX in OTA sample application (switch ota).
    1. OTA_Client_Init
    2. OTAClient_SetEndpoint
    3. OTA_ProcessMatchDescRsp
    4. zclOTA_event_loop
  6. Add post-build actions

4.1 Adding OTA Client Source Code

To add the OTA source code to an application’s project, perform the following:

  1. Open the project workspace in CCS

  2. Create a folder in the workspace for OAD files:

    1. Right click on the application New>Folder from the pull down menu, and name it “oad”

  3. Add the files by drag and drop the file into the “oad” folder from Windows Explorer.

    1. crc32.c

    simplelink_cc26x2_sdk_1_xx_xx_xx\source\ti\common\cc26xx\crc

  1. flash_interface_ext_rtos_NVS.c

    simplelink_cc26x2_sdk_1_xx_xx_xx\source\ti\common\cc26xx\flash_interface\external

  2. oad_image_header_app.c

    simplelink_zigbee_sdk_plugin_x_xx_xx_xx\source\ti\zstack\source\oad\15.4

  3. oad_switch_agama.c (optional)

    simplelink_zigbee_sdk_plugin_x_xx_xx_xx\source\ti\zstack\source\oad

Note: When prompted to link the files, do it relative to the project location by pressing OK. It is important to not change the project path or name, otherwise the project will no longer work.

image5

  1. Add the files by drag and drop the following files into common>zcl from Windows Explorer.

    1. zcl_ota.c and zcl_ota.h

    simplelink_zigbee_sdk_plugin_x_xx_xx_xx\source\ti\zstack\stack\zcl

  1. ota_client_app.c and ota_client_app.h

    simplelink_zigbee_sdk_plugin_x_xx_xx_xx\source\ti\zstack\stack\zcl\app

4.2 Replace OTA linker and oad configuration file

To replace the linker file, select cc26x2lp.cmd file and delete it, after which you have to add the new OTA linker file (cc26x2lp_ota.cmd) located at OTA sample application such as:

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_switch_ota\tirtos\ccs

image6 image7

To replace the configuration file, select app.cfg file and delete it, after which you have to add the new OTA configuration file (oad_app.cfg) located at:

simplelink_zigbee_sdk_plugin_x_xx_xx_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\common\rtos

image8 image9

4.3 Add OTA Includes Directories

  1. Open the project workspace in CCS
  2. Click Projects>Options… from the menu.
    1. Expand Build>ARM Compiler>Include Options
    2. Add the following directories:
      1. ${ZSTACK_SOURCE}/stack/zcl/app
      2. ${ZSTACK_SOURCE}/source/oad
      3. ${COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR}/source/ti
      4. ${COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR}/source/ti/common
      5. ${COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR}/source/ti/common/cc26xx/oad
      6. ${COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR}/source/ti/common/cc26xx/flash_interface
      7. ${COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR}/source/ti/common/cc26xx/bim
      8. ${COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR}/source/ti/common/cc26xx/crc
      9. ${MAC_APPS}/common/startup
      10. ${MAC_APPS}/common/ota

image10

4.4 Adding Configuration Compile Time Flags

  1. Open the project workspace in CCS
  2. Click Projects>Options… from the menu.
    1. Expand Build>ARM Compiler>Predefined Symbols
    2. Add the following compilation flags:
      1. OTA_CLIENT_CC26XX
      2. OTA_CLIENT=TRUE
      3. OTA_HA
      4. OTA_MANUFACTURER_ID=0xBEBE
      5. OTA_TYPE_ID=0x2652
      6. OTA_INITIAL_IMAGE
      7. OTA_APP_VERSION=0x00000001
      8. HAL_IMG_AREA=0
      9. SWITCH_OTA
      10. CC26X2

image11

4.5 Add OTA initialization and event process code

  1. Open the project workspace in CCS

  2. Add the OTA Client initialization and Application endpoint supporting OTA

    1. In your initialization function (e.g. zclSampleSw_initialization()) add at the end the following two functions with their respective input parameters defined by the application.
      1. OTA_Client_Init
      2. OTAClient_SetEndpoint

  3. Enable the processing of the ZDO Match descriptor response and add the following OTA processing function

    1. Enable application processing of ZDO match descriptor response by setting ZDO callbacks

      static void SetupZStackCallbacks(void)
{
    zstack_devZDOCBReq_t zdoCBReq = {0};

    // Register for Callbacks, turn on:
    //  Device State Change,
    //  ZDO Match Descriptor Response,
    zdoCBReq.has_devStateChange = true;
    zdoCBReq.devStateChange = true;

#if defined(OTA_CLIENT_CC26XX)
    zdoCBReq.has_matchDescRsp = true;
    zdoCBReq.matchDescRsp = true;
    zdoCBReq.has_ieeeAddrRsp = true;
    zdoCBReq.ieeeAddrRsp = true;
#endif

    (void)Zstackapi_DevZDOCBReq(zclSampleSw_Entity, &zdoCBReq);
}

    2. Add OTA_ProcessMatchDescRsp into zstackmsg_CmdIDs_ZDO_MATCH_DESC_RSP stack notification:

      #if defined (OTA_CLIENT_CC26XX)
  case zstackmsg_CmdIDs_ZDO_MATCH_DESC_RSP:
  {
    zstackmsg_zdoMatchDescRspInd_t  *pInd =
       (zstackmsg_zdoMatchDescRspInd_t *) pMsg;

    ZDO_MatchDescRsp_t              *pRsp;

    /*
     * Parse the Match Descriptor Response and give it
     * to the ZCL EZMode module t+o process
     */
    pRsp = (ZDO_MatchDescRsp_t *) ICall_allocMsg(
       sizeof(ZDO_MatchDescRsp_t) + pInd->rsp.n_matchList);
    if(pRsp)
    {
      pRsp->status = pInd->rsp.status;
      pRsp->nwkAddr = pInd->rsp.nwkAddrOfInterest;
      pRsp->cnt = pInd->rsp.n_matchList;
      memcpy(pRsp->epList, pInd->rsp.pMatchList, pInd->rsp.n_matchList);

      OTA_ProcessMatchDescRsp ( pRsp );
      ICall_freeMsg(pRsp);
    }
  }
  break;
#endif

    3. Add zclOTA_event_loop into the sample application process event loop:

      static void zclSampleSw_process_loop(void)
{
    /* Forever loop */
    for(;;)
    {
        ICall_ServiceEnum stackid;
        ICall_EntityID dest;
        zstackmsg_genericReq_t *pMsg = NULL;

        /* Wait for response message */
        if(ICall_wait(ICALL_TIMEOUT_FOREVER) == ICALL_ERRNO_SUCCESS)
        {
            /* Retrieve the response message */
            if(ICall_fetchServiceMsg(&stackid, &dest, (void **)&pMsg)
               == ICALL_ERRNO_SUCCESS)
            {
                if( (stackid == ICALL_SERVICE_CLASS_ZSTACK)
                    && (dest == zclSampleSw_Entity) )
                {
                    if(pMsg)
                    {
                        zclSampleSw_processZStackMsgs(pMsg);

                        // Free any separately allocated memory
                        Zstackapi_freeIndMsg(pMsg);
                    }
                }

                if(pMsg)
                {
                    ICall_freeMsg(pMsg);
                }
            }

#if defined (OTA_CLIENT_CC26XX)
            zclOTA_event_loop();
#endif
...

4.6 Adding Post-Build Actions

  1. Open the project workspace in CCS
  2. Click Projects>Options… from the menu.
    1. Select Build, and select Steps tab and make sure the following post-build actions are set:
      1. ${CCS_INSTALL_ROOT}/utils/tiobj2bin/tiobj2bin ${BuildArtifactFileName} ${BuildArtifactFileBaseName}.bin ${CG_TOOL_ROOT}/bin/armofd ${CG_TOOL_ROOT}/bin/armhex ${CCS_INSTALL_ROOT}/utils/tiobj2bin/mkhex4bin
      2. ${CG_TOOL_HEX} -order MS --memwidth=8 --romwidth=8 --intel -o ${ProjName}.hex ${ProjName}.out
      3. ${TOOLS_OAD_DIR}/oad_image_tool --verbose ccs ${PROJECT_LOC} 7 -hex1 ${ConfigName}/${ProjName}.hex -o ${ConfigName}/${ProjName}_oad
      4. ${TOOLS_OAD_ZIGBEE_DIR}/zOTAfileGen.exe ${PROJECT_LOC}/${ConfigName}/${ProjName}_oad.bin ${PROJECT_LOC}/${ConfigName}/ BEBE 2652 00000001

image12

5. OTA Client Application Binary Usage

Once the application is ready, it can be compiled as any CCS project. From the build several binaries will be generated:

  • zr_switch_ota_cc26x2lp.hex
    • This hex file is the plain binary application. The OAD header used by BIM is not formatted yet with proper CRC, but can still be used to flash using CCS or any other flashing tool such as SmartRF Flash Programmer 2 or UniFlash.
  • zr_switch_ota_cc26x2lp.bin
    • This is the raw binary required by oad formatting tool that can calculate the CRC and fit it into the OAD header for BIM to use.
  • zr_switch_ota_cc26x2lp_oad.bin
    • This binary has the right CRC and flags set to be usable by BIM, which is the actual payload of the Zigbee Application binary delivered by OTA cluster during upgrade.
  • BEBE-2652-00000001.zigbee
    • This is Zigbee formatted binary with the Zigbee OTA header used by OTAServer desktop application.

Subsequent builds of the application must increase the version number of the application by changing the post-build parameters (as indicated in 3.2.2.1).

5.1 Flashing OTA client sequence

In order to use OTA Client functionality, the BIM must be loaded into the device. It is recommended that prior loading any application, a memory erase operation is performed on the device to avoid previous configuration or Nv usage affects the device.

  1. Erase complete flash
  2. Flash BIM
  3. Flash Client OTA application
  4. Perform any upgrade operation