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. 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 [1].

Communication via the OTA Upgrade Cluster takes place using the following command messages shown in Figure 90.

Figure 90. OTA client querying an image from the OTA server

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 according to TI BIM specification 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 IDE output binaries into Zigbee upgradable binaries; first a .hex 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 TI BIM specification 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 of the IDE in any OTA client sample app, such as zr_switch_ota_cc26xlp for CCS or zc_switch_ota for IAR. 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 device 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 TI BIM 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 IDE 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 BIM compatible image OAD header | Zigbee application binary, the second argument is 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 <workspace path>\otaFiles BEBE 2652 00000002

Note

OtaConverter.exe can be found here: C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_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 TI BIM specification.

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 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. 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 TI BIM specification.

3. Boot Image Manager (BIM)

The Boot Image Manager resides on the OTA target, and is responsible for loading new images after a download has completed. The BIM executes on a device reset and determines if a firmware update needs to be applied. If no update is being applied, then the BIM will transfer program execution to the main application image.

3.1 Overview & Software Architecture

BIM is a fully executable application that is independent of any high level protocol stack or user application. It is guaranteed to run on boot. BIM enables power loss fault tolerance during OTA. If the device power is lost during OTA, the BIM will still be able to run from reset and revert to a working image if one is available. The BIM is intended to reside permanently on the chip and cannot be updated via the OTA process.

BIM executes before kernel initialization takes place so the design is single threaded and bare metal. Hardware access is accomplished through driverlib.

As a separate application, BIM requires its own interrupt vector table and linker file. It will produce a fully executable image that must be merged with the user application image in order to create a functional OTA enabled firmware system.

In general, BIM is responsible for finding and analyzing OTA image header. From a high level BIM does the following:

1. Check for newly downloaded images from a recent OTA.
2. If available, copy the newly downloaded images to their target location in internal flash
3. Dynamically locate the entry point of the valid image and jump to it

The following section will cover the BIM boot procedure and image checking routine in detail.

3.2 Boot procedure

On reset, the software in the ROM of the CC26X2R1 will execute basic startup routines, and then jump to the location pointed to by the CCFG‘s IMAGE_VALID_CONF field. More information about the fields of the CCFG and the generic device boot procedure is detailed in the CC26x2 Technical Reference Manual. The BIM is setup to link the CCFG as part of its image. This is another failsafe mechanism to ensure that a CCFG is always present on the device. To enable this feature, BIM uses a custom CCFG where the value of the IMAGE_VALID_CONF field points to BIM’s reset vector table. More information about the CCFG and the IMAGE_VALID_CONF is available in the CC26x2 Technical Reference Manual.

In summary, the boot ROM code will jump to the ResetISR() in BIM’s vector table. Being a bare metal application, BIM uses the toolchain specific boot code provided in driverlib.

The reset ISR code can be found in driverlib under the startup folder. In summary, it performs the following:

1. Device specific trim functionality
2. C/C++ runtime initialization
3. Jump to BIM’s main()

See the figure below for a graphical representation of the boot procedure. Red boxes indicate driverlib/ROM code, blue boxes represent BIM code.

3.2.1 Device trim

The device trim function is responsible for tuning hardware settings of the device to ensure stable and optimal operation. It must run at least once every time the device boots, but may be ran more than once. Parts of the trim function are dependent on the CCFG which is another reason why it is linked with BIM.

By default, both BIM and the user application will trim the device.

This offers the benefit that the user application may link to a newer version of the trim function. This comes at the cost of a small amount of additional flash in the user application.

Warning

It is recommend to leave device trim enabled in both the BIM and the user application to enable development via a debugger without a BIM present.

Removing the device trim for the user application is only suggested for final production code. Additional validation should be performed on images with additional trimming disabled. App level trimming can be disabled by modifying the Boot module within the kernel’s *.cfg file.

3.3 Locating and Preparing a user application

Besides booting and trimming the device, BIM’s primary functionality is to find and prepare a user application to run on the CC26X2R1.

3.3.1 BIM for Off-Chip OTA

At steady state, the normal case is that a valid image exists in internal flash and no image in the external flash has been marked as needing to be copied. In this case, BIM will validate that the image on internal flash and execute it by loading the stack pointer and jumping to the image’s reset vector location. BIM determines the location of the reset vector and stack pointer of the image through the OAD image header attached to it.

Note

As a convention, the vector table comes immediately after the image header in OTA enabled images. The BIM and the image header are tightly coupled, refer to the 4. OAD Image Header chapter for more detail on the image header vector and its fields.

Figure 91. Sequence diagram for BIM image selection process

The image above is illustrated in words below. In order to determine which image is best to run, BIM takes the following measures:

1. At startup, BIM looks for a valid image header in external flash by reading the first 8 bytes to find the valid External Flash Image Identification value.

2. After a valid header is found, it reads the entire header from ext flash and verifies the compatibility of BIM and image header versions. Then it checks if the ‘Image copy status’ is set to be copied to the on-chip flash(0xFE) and has a valid CRC (CRC status=0xFE).

   • If it finds status ‘CRC not calculated’(CRC Status = 0xFF), it calculates the CRC of the external flash contents and updates the CRC status byte in the external flash.
   • On finding the invalid CRC it moves on to read the next image’s header.

3. If a valid image is found, BIM copies the image to on-chip flash, as per the image copy procedure.

   • After the copy, the CRC is re-checked on internal flash to ensure the copy succeeded.
   • If the copy failed the status byte is updated and the bim will continue searching external flash.
   • If the copy succeeded, then the BIM will jump directly to the application image, and the search process ends.

5. If BIM reaches the end of the image header region in external flash without finding a valid image, then it will try to find an on-chip image and execute it.
6. If BIM fails to find a valid image internal flash, it will attempt to revert the factory image if there is one present.
7. BIM will put the device to low power mode if it fails to find a valid application image.

Note

An image is considered bad/invalid if it’s calculated CRC32 does not match the image’s CRC bytes embedded in the image header.

4. OAD Image Header

All firmware images delivered via OAD are in binary format and contain an image header. The information in the image header is used by the application and BIM to determine the suitability of an image for download or loading. In order to prevent this information from being calculated multiple times all TI OAD images use a standard image header.

This section explains the various fields within the image header and what they mean.

TI provides a tool to generate an OAD ready image, it is called OAD Image Tool. By default, this tool runs as a post-build step of all OAD enabled projects.

4.1 OAD Image Header Overview

The OAD image header is made up of two parts:

• The core image header which is fixed and mandatory for all OAD images
• The image segments which are optional and used to describe specific types of images

The OAD image header is composed of a core header and segments. The core header is required and common to all OAD image headers. The image segments are optional and may be different for a given OAD use case (i.e. on-chip vs off-chip OAD).

The image below illustrates the makeup of an image header, and compares two types. When added to an image by the OAD Image Tool the OAD core header and segments are packed together sequentially.

Note

In general it is not necessary for the customer or user to manually add or modify segments. The segments should be populated and packed out of the box by the TI oad_image_tool.

4.2 OAD Core Image Header

The core header contains the essential information required for all types of OAD across all supported wireless stacks. The core header must be present as the BIM relies heavily on it to boot and OAD image.

Table 1. below shows a description of the core image header.

Table 1. Description of the core image header.

Field	Size (in bytes)	Description
OAD Image Identification Value	8	Unique number to identify the start of an OAD image
CRC	4	Cyclic Redundancy Check
BIM Version	1	Version required to support image format
Image Header Version	1	Version of image header contained in image
Wireless Technology	2	Type of connectivity used in image
Image Information	4	Image information bytes
Image Validation	4	Check if image is valid to run
Image Length	4	The total length of the image including header
Program Entry Address	4	Application startup entry address
Image Software Version	4	Software version of the image
Image End Address	4	End address of the image
Header Length	2	Total length of the image header

The core header is defined in oad_image_header.h in the struct imgFixedHdr_t.

Each entry from Table 1. are described in the following sections.

OAD Image Identification Value

The OAD Image Identification Value for the CC26X2R1 is set based on the DeviceFamily_* defined that is provided by the SDK. The value is using the the OAD_IMG_ID_VAL define. Note the protocol specific implementation OAD should check that the OAD_IMG_ID_VAL field matches between the image currently resident on the device and the incoming image.

The OAD Image Identification Value serves two purposes:

• Provides the application a quick way to identify if it is receiving the correct image.
• Provides a means for the BIM to find the flash page containing the start of OAD image for on-chip OAD

Note

It is recommended that the customer customize the image identification field to uniquely identify their product.

CRC

The cyclic redundancy check (CRC) is a means to check the integrity of an image. This must be done in two steps. First the CRC must be calculated when the image is generated from the toolchain (by the OAD Image Tool), this will be stored in the CRC field within the image header.

Later, once the target has received the OAD image, CRC will be recalculated to determine if the image has been corrupted during transfer.

If the CRC is equivalent before and after the OAD, the target can assume that the image was not corrupted while sending over the air.

A CRC-32 algorithm is used to calculate the CRC. This algorithm results in a 1 in 2³² chance of collision. This allows for a 99.9999% error detection rate. In addition to this CRC, transfers through the protocol transport are also protected by a CRC. So the risk of an undetected data corruption is reduced even further.

BIM Version

The BIM Version byte is used to determine whether or not the image is compatible with the version of BIM that is running on the device.

Image Header Version

The image header Version byte is used to determine whether or image contains image header that is compatible with the current version of the application and BIM.

Wireless Technology

The Wireless Technology field in the image header describes what technology is used in the image to be downloaded. Multiple technologies can be selected here if the device used supports multiple technologies. These fields are added for future expansion. Bits are set to 1 by default. To select the Wireless Technology field, set the appropriate bit(s) to 0.

Bit Number	Type
0	Bluetooth Low Energy
1	IEEE 802.15.4 (Sub 1GHz)
2	IEEE 802.15.4 (2.4GHz)
3	Zigbee
4	RF4CE
5	Thread
6	Easy Link
7-15	Reserved

Image Information

The Image Information provides details about the OAD image status and type. The format is as follows:

Byte Number	Item	Description
0	Image Copy Status	0xFF: Default status, no action needed 0xFE: Image to be copied to on-chip flash at location indicated in the image header 0xFC: Image copied
1	CRC Status	0xFC: CRC Invalid 0xFE: CRC Valid 0xFF: CRC Not Calculated Yet
2	Image Type	Device Images (0x00-0x15) 0x00: Persistent application (for On-chip OAD) 0x01: Application 0x02: Stack 0x03: Application & Stack Merged 0x04: Network Processor 0x05: Factory Image 0x06: BIM 0x07: App & Stack Combined (App/Stack_Library) 0x10-0x1F: User data 0x20-0x3F: Host Processor Images 0x40-0xFF: Reserved
3	Image Number	Image number if more than one type is stored 0xFF: Default 0x00-0xFE: Image number

Note

Image type 0x03 (Application & Stack Merged) is different from 0x07 (App & Stack Combined). Image type 0x03 refers to the case where app and stack are build as separate split images and combined using a hex merging tool. Image type 0x07 refers to a app and stack being built as a single executable.

Note

BIM will not try to interpret user data/application (anything with image type > 0x10).

Image Validation

The image validation field is currently not used and is reserved for future use.

Image Length

The Image Length field is the total length of the executable portion of the image in bytes. Image length is calculated by the OAD image tool using the following equation:

Note that the tool will pad the image length to be word aligned, updating the length if needed.

Note

• imgEndAddr: Last used address in flash
• imgStAddr: The first address used in flash (starts at _imgHdr.imgID)

Program Entry Address

The Program Entry Address is a pointer to the application interrupt vector table or application program entry address. This provides flexibility so that if the program entry address changes between images, BIM will still be able to use this field to run the application.

Software Version

The Software Version field is used to keep track of the application and stack revision contained in the image. This field follows the following format:

These values are assigned as shown in the table below.

Byte Number	Description
3-2	Stack version
1-0	Application version

For example an image with app version 1.0 and stack version 3.0 would be designated as: {'3', '0', '1', '0'}. This field is to be set by the user in their header implementation. (i.e. oad_image_header*.c)

Image End Address

The Image End Address is the last address in flash occupied by the image.

Header Length

The Header Length is the length of the core portion of the header. This is up to and including the rfu2 field in the structure defined in oad_image_header.h.

4.3 OAD Image Header segments

The segment structure was designed to make the current OAD implementation flexible and extensible. This makes it possible to expand the image header vector as features are added to the OAD implementation without breaking the existing system.

Table 2. Description of the image header segments.

Field	Size (in bytes)	Description
Boundary Information	24	Contains information about RAM and Flash boundaries
Contiguous Image Information	12	Contains information about image to be downloaded

Note

The current implementation only supports images of contiguous type, thus this segment is required.

The boundary segment is optional and only required for split image types.

4.3.1 Segment Header

Each segment has a common header structure. This is useful when parsing an image for segments. The header structure is used by all segments. The common header will be documented below so it does not have to be repeated for each segment type.

Field	Size (in bytes)	Description
Segment type = X	1	Segment header op-code
Wireless technology	2	Same options as in the main wireless technology table above. Only one bit may be set here.
Reserved	1	Default is set to 0xFF
Payload length	4	The length of the segment in bytes

Segment Type

The segment type field is a one byte op-code that is useful in identifying the segment type.

Wireless Technology

This is the type of wireless technology that is contained in the segment. Each segment may be built for only one wireless tech, thus only one bit can be set in this field.

Reserved

This field is currently unused and existing designs should not rely on this field.

Payload Length

The length of the entire segment in bytes.

4.3.2 Boundary Information Segment

The Boundary Information field is intended for split image type OAD (where the application and stack are separate images) and is optional. The boundary segment provides information to BIM on the flash and RAM boundaries of the image and its associated wireless stack image.

This information is formatted in the following way:

Item	Size (in bytes)	Description
Segment type = 0	1	Tells the BIM that the following fields provide RAM and stack boundary information
Wireless technology	2	Same options as in the main wireless technology table above. Only one bit may be set here.
Reserved	1	Default is set to 0xFF
Payload length	4	The length of the boundary information field in bytes
Stack Entry Address	4	Stack entry address
ICALL_STACK0_ADDR	4	Stack boundary address
RAM_START_ADDR	4	Start address of RAM
RAM_END_ADDR	4	End address of RAM

The boundary segment is defined in oad_image_header.h in the struct boundarySeg_t. See this structure in Doxygen for more information.

Stack Entry Address

This is the entry point to the stack image, required when the app and stack are of split image type.

Stack Boundary Address (ICALL_STACK0_ADDR)

The address of the app/stack boundary. This is the lowest address occupied by the stack.

Lower RAM Boundary (RAM_START_ADDR)

The lower address of the RAM region reserved by the stack image.

Upper RAM Boundary (RAM_END_ADDR)

The upper address of the RAM region reserved by the stack image.

4.3.3. Contiguous Image Information Segment

The Contiguous Image Information field provides information about the image to be downloaded during the OAD process. The information is formatted in the following way:

Item	Size (in bytes)	Description
Segment type = 1	1	Tells the BIM that the following fields provide information about the image payload
Wireless technology	2	Same options as in the main wireless technology table above. Only one bit may be set here.
Reserved	1	Default is set to 0xFF
Image Segment Len	4	The length of the contiguous image segment in bytes
Image Start Address	4	Address of executable image data

The contiguous image segment is defined in oad_image_header.h in the struct imgPayloadSeg_t. See this structure in Doxygen for more information.

Image Start Address

The starting address of the contigous image segemnt. The information in this segment will be filled in sequentially from the start address.

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

Note

OTA upgrade is supported for the three platforms CC26x2R1, CC1352R1 and CC1352P_2. While the following seccions will explain the process for CC26x2 platform, the same is true for the other two platforms just by changing the platform named used where CC26x2R1 platform is referenced (device used, file names, paths, etc.).

5.1 Required Materials

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

• A compiler supported by Z-Stack, either:

• Code Compose Studio™ (CCS) 8.1.0.00011 or newer OR
• IAR Embedded Workbench for ARM 8.20.2 or newer

• SimpleLink™ CC26x2 SDK 2.20.00
• SimpleLink™ Zigbee SDK plugin 2.20.00
• Two Simplelink CC26x2R1 launchpad

5.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, CC1352R1 and CC1352P_2 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.

5.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 depending on the IDE used:

For CCS: C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\examples\nortos\CC26X2R1_LAUNCHXL\common\bim\nortos\ccs

For IAR: C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\examples\nortos\CC26X2R1_LAUNCHXL\common\bim\nortos\iar

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.

The CCFG used by BIM can be located here:

C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\examples\nortos\CC26X2R1_LAUNCHXL\common\bim\nortos\src

And it’s linker file here:

For CCS: C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\source\ti\common\cc26xx\ccs

For IAR: C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\source\ti\common\cc26xx\iar

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

5.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 for CCS or cc26x2lp_oad.icf for IAR 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:

For CCS: C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_switch_ota\tirtos\ccs

For IAR: C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_switch_ota\tirtos\iar

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:

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\common\rtos

The sample application for OTA client is provided for all three logical devices:

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_switch_ota\tirtos\ccs

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_switch_ota\tirtos\ccs

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zed_switch_ota\tirtos\ccs

for Coordinator, Router and End device. The projects for IAR are also provided in the same path just with termination iar, instead of ccs.

5.2.2.1 Generate OTA binaries

To generate the upgradable binaries in CCS, 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:

BEBE is the manufacturer ID

2652 is the image type

00000001 is the version of the application image.

Figure 92. OTA client postbuild steps in CCS.

For IAR, the post build actions are a bit different:

"$PROJ_DIR$\build.cmd" "$TOOLS_OAD_DIR$" "$PROJ_DIR$" "$TARGET_BPATH$" "$TOOLS_OAD_ZIGBEE_DIR$" "$TARGET_DIR$" "BEBE" "2652" "00000001"

From which:

BEBE is the manufacturer ID

2652 is the image type

00000001 is the version of the application image.

Figure 93. OTA client postbuild actions in IAR.

These three 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

Figure 94. OTA client predefined symbols in CCS.

Figure 95. OTA client predefined symbols in IAR.

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.

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

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zc_ota_server\tirtos\ccs

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_ota_server\tirtos\ccs

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zed_ota_server\tirtos\ccs

The projects for IAR are also provided in the same path just with termination iar, instead of 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: 38400
• Flow: CTS/RTS
• Parity: None
• Stop bits: 1
• Data bits: 8

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

5.3 Performing an Image Update

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

Figure 96. OTA server desktop app.

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

Figure 97. OTA Server Image Selection

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

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

6. 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 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
2. Add the OTA and BIM files
   1. Source code to the application.
3. Replace linker and app configure file
4. Add OTA include directory to the list of include directories.
5. Add the configuration OTA compile flags
6. Add post-build actions

6.1 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

   2. 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);
      }
      

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

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

6.2 Adding OTA Client Source Code

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

1. Open the project workspace

2. Create a folder in the workspace for OAD files named “oad”.

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

   1. crc32.c

   C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\source\ti\common\cc26xx\crc

   2. flash_interface_ext_rtos_NVS.c

   C:\ti\simplelink_cc26x2_sdk_x_xx_xx_xx\source\ti\common\cc26xx\flash_interface\external

   3. oad_image_header_app.c

   C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\source\ti\zstack\source\oad\15.4

   4. oad_switch_agama.c (optional)

   C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\source\ti\zstack\source\oad

Note

For CCS workspace, when prompted to link the files (Figure 98.), 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.

Figure 98. Adding header files relative path to workspace.

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

   5. zcl_ota.c and zcl_ota.h

   C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\source\ti\zstack\stack\zcl

5. Create another folder in the workspace inside of zcl folder.

6. Add the files by drag and drop into the new folder from Windows Explorer.

   6. ota_client_app.c and ota_client_app.h

   C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\source\ti\zstack\stack\zcl\app

6.3 Replace OTA linker and oad configuration file

6.3.1 Replace OTA linker and oad configuration file in CCS

For CCS, 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:

For CCS: C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_switch_ota\tirtos\ccs

Figure 99. CCS linker file to be used.

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:

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\common\rtos

Figure 100. CCS RTOS config file to be used.

6.3.2 Replace OTA linker and oad configuration file in IAR

For IAR, go to the options menu of the project in the linker section and replace the linker file cc26x2lp.icf for the oad linker file cc26x2lp_oad.icf located in the same path:

For IAR: C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\zr_switch_ota\tirtos\iar

Figure 101. IAR linker file to be used.

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:

C:\ti\simplelink_zigbee_sdk_plugin_2_20_00_xx\examples\rtos\CC26X2R1_LAUNCHXL\zstack\common\rtos

Figure 102. IAR RTOS config file to be used.

6.4 Add OTA Includes Directories

6.4.1 Add OTA Includes Directories in CCS

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

Figure 103. CCS include path menu.

6.4.2 Add OTA Includes Directories in IAR

1. Open the project workspace in IAR
2. Click Projects>Options… from the menu.
   1. Go to C/C++ Compiler section
   2. Select the Extra Options tab
   3. Add the following directories:
      1. -I$ZSTACK_SOURCE$/stack/zcl/app
      2. -I$ZSTACK_SOURCE$/source/oad
      3. -I$COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR$/source/ti
      4. -I$COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR$/source/ti/common
      5. -I$COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR$/source/ti/common/cc26xx/oad
      6. -I$COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR$/source/ti/common/cc26xx/flash_interface
      7. -I$COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR$/source/ti/common/cc26xx/bim
      8. -I$COM_TI_SIMPLELINK_CC26X2_SDK_INSTALL_DIR$/source/ti/common/cc26xx/crc
      9. -I$MAC_APPS$/common/startup
      10. -I$MAC_APPS$/common/ota

Figure 104. IAR include path menu.

6.5 Adding Configuration Compile Time Flags

6.5.1 Adding Configuration Compile Time Flags in CCS

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. SWITCH_OTA
      9. CC26X2

Figure 105. CCS Predefined symbols

6.5.2 Adding Configuration Compile Time Flags in IAR

1. Open the project workspace in IAR
2. Click Projects>Options… from the menu.
   2. Select the Extra Options tab
   3. Add the following compile flags:
      1. -DOTA_CLIENT_CC26XX
      2. -DOTA_CLIENT=TRUE
      3. -DOTA_HA
      4. -DOTA_MANUFACTURER_ID=0xBEBE
      5. -DOTA_TYPE_ID=0x2652
      6. -DOTA_INITIAL_IMAGE
      7. -DOTA_APP_VERSION=0x00000001
      8. -DSWITCH_OTA
      9. -DCC26X2

Figure 106. IAR Predefined symbols

6.6 Adding Post-Build Actions

6.6.1 Adding Post-Build Actions in CCS

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

Figure 107. CCS Postbuild actions

6.6.2 Adding Post-Build Actions in IAR

1. Open the project workspace in IAR
2. Click Projects>Options… from the menu.
   1. Select the Build Actions tab and make sure the following post-build actions are set:
      1. "$PROJ_DIR$\build.cmd" "$TOOLS_OAD_DIR$" "$PROJ_DIR$" "$TARGET_BPATH$" "$TOOLS_OAD_ZIGBEE_DIR$" "$TARGET_DIR$" "BEBE" "2652" "00000001"

Figure 108. IAR Postbuild actions

This will execute the build.cmd batch file that executes the oad_image_tool and zOTAfileGen with the proper parameters to generate the upgrade binaries with the specified parameters.

7. 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 5.2.2.1).

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