Introduction

This section serves as a guide to the Texas Instruments 15.4-Stack Over-the-Air Download (OAD) ecosystem including the custom protocol specification, application architecture, drivers, and middleware. OAD is a device firmware upgrade method that allows the firmware image running on a device to be updated over the air using a TI 15.4-Stack network while providing power loss protection.

The guide will cover the principles of the OAD process, the out of the box examples included in the SimpleLink CC13x0 SDK, and the process for adding OAD to an existing project.

The OAD guide section will cover:

  • OAD theory of operation and architecture
  • How to run the OAD examples included in the SimpleLink CC13x0 SDK
  • How to add OAD to an existing sample application

The supported development kit for OAD is the CC13x0 Launchpad. To follow the procedures listed in this guide, two CC13x0 Launchpad development kits are required.

OAD Concept Overview

This section aims to explain the major concepts involved in the OAD process from a high level. The concepts here will be expanded upon further in the following sections. Some concepts, such as the Boot Image Manager (BIM), may vary in their implementation details. Wherever possible, the concepts will be covered in this chapter with their implementation details covered in the following chapters.

OAD Types

TI 15.4-Stack only supports off-chip OAD. During off-chip OAD, the candidate image is stored in a low power external flash and loaded into the CC13x0 internal flash by the BIM.

OAD Topology Overview

A TI 15.4-Stack network with at least one sensor node is required to run a successful OAD. The collector application must run on a linux machine using TI 15.4-Stack Linux SDK. The terms for the devices involved in an OAD exchange are listed below:

The OAD Target is always the device that implements the OAD service and is responsible for keeping track of the OAD process once it has been initiated. Typically this is the sensor device being updated. The OAD Target uses a Boot Image Manager (BIM) to facilitate the application of a new firmware update image. The BIM executes on a device reset and determines if a firmware update is to be applied. If no update is being applied, then the BIM will transfer program execution to the main application image.

The OAD Distributor is always the central device that notifies the OAD Target when a new image is available and supplies the firmware update.

OAD Image Metadata

All firmware images delivered via OAD are in binary format and contain an image metadata header The information in the metadata header is used by the OAD service to determine whether or not an image is acceptable for download or by the BIM to determine which image should be loaded/executed in the main system flash. In order to prevent this information from being calculated multiple times all TI OAD images use a standard 16-byte metadata vector. This metadata vector is embedded at the beginning of the image, occupying the first 16 bytes before the application code firmware content.

This section explains the various fields within the metadata vector and what they mean.

Most metadata checking is done in OADTarget_validateNewImage().

TI provides a tool to generate an OAD ready image, which contains a metadata vector called the OAD Image Tool. See OAD Image Creation.

Table 17. below shows a description of the metadata vector.

Table 17. Description of the metadata vector.
Field Size (in bytes) Description
CRC 2 Cyclic Redundancy Check
CRC Shadow 2 Place holder for CRC
Version 2 Version
Length 2 Length of the image in words*
UID 4 User Identification
Start Address 2 The destination address of the image in words*
Image Type 1 The type of image to be downloaded
State 1 The status of this image
[*]

These fields are measured in 32-bit words.

For example, an image length of 0x100 describes an image that is 1024 bytes in size. This OAD word size is defined by EFL_OAD_ADDR_RESOLUTION for off-chip OAD

CRC and CRC Shadow

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, this will be stored in the CRC field within the metadata vector.

This initial CRC will be sent over the air via the OAD Protocol.

Later, once the target has received the OAD image, CRC shadow will be calculated to determine if the image has been corrupted during transfer. The target will re-calculate the CRC of the downloaded image and store the result in the CRC shadow field of the metadata vector.

If the CRC and CRC shadow are equivalent, the target can assume that the image was not corrupted while sending over the air.

The algorithm selected for CRC calculations is the CRC-16-CCITT, it is a 16 bit CRC calculation that has a 99.9984% error detection rate in the worst case. In addition to this CRC, all data transfers in TI 15.4-Stack are protected by a CRC on the link layer so the risk of an undetected data corruption is even further reduced.

Version

The image version field is used to track revisions of images and ensure upgrade compatibility. Customers may implement their own versioning scheme; however, there are additional checks imposed by the TI OAD profile. See the function OADTarget_validateNewImage() within oad_target_external_flash.c to see how these version checks are done in Off-chip OAD.

Length

The length field is the length of the image in words, where the word size is defined by EFL_OAD_ADDR_RESOLUTION for Off-chip OAD. Off-chip OAD customers who are using different external flash parts may need to modify EFL_OAD_ADDR_RESOLUTION to match the word size of their part.

User Identification (UID)

This field is un-used by the TI OAD profile, but the hooks are in place for a customer to add their own implementation of verifying images based on UID.

Off-chip images use ‘E’, ‘E’, ‘E’, ‘E’ by default.

Start Address

The start address is the first address where the proposed image is to be stored in internal flash. Similar to the length field, this is calculated in words. Off-chip OAD solutions put restrictions on the start address based on image type (more on this in the next section).

Image Type

TI 15.4-Stack only support APP+STACK merged updates.

Image State

The image state is a one byte metadata field that is used only by Off-chip OAD solutions. The state informs the BIM whether or not the image is ready to run or currently running. This prevents the BIM from copying the same image from external to internal flash on every boot.

Flash Layout

Table 18. shows the default flash layout for an OAD Client. The default configuration is common across BLE, therefore; a CC1350 can be update via BLE OAD or TI 15.4-Stack OAD.

Table 18. Default Internal Flash Layout of an OAD Client
Section Flash Range
BIM Reset Vectors 0x0 - 0x3C
BIM Driver Lib 0x3D - 0xFFF
OAD Image Header (metadata) 0x1000 - 0x100F
Application Reset Vectors 0x1010 - 0x104C
Application Image 0x104D - 0x1CFFF
NV Storage 0x1D000 - 0x1EFFF
BIM 0x1F000 - 0x1FF89
CCA 0x1FF8A - 0x1FFFF

If interoperability is not a requirement and TI 15.4-Stack OAD is the only method being used, then an addition 5.5KB of flash can be saved by using TI-RTOS in ROM. When TI-RTOS is running from ROM it assumes that there is constant data placed at the beginning of page 1 (0x1000), which means a link conflict occurs when using the default flash layout. To prevent this conflict the internal flash layout can be rearranged, but this breaks compatibility with BLE and EasyLink OAD. To enable this optimization to the following:

  1. Modify the BIM CCS project by adding TIRTOS_IN_ROM to Project->Properties->Arm Compiler->Predefined Symbols

  2. Modify the sensor_oad application:

    1. Add TIRTOS_IN_ROM Project->Properties->Arm Compiler->Predefined Symbols
    2. Add TIRTOS_IN_ROM to Project->Properties->Arm Linker->Advanced Options->Command File Processing
    3. Add NO_ROM=1 to Project->Properties->XDCtools->Advanced Options->Configuration Script Arguments

The resulting flash layout is shown in Table 19..

Table 19. Optimized Internal Flash Layout
Section Flash Range
BIM Reset Vectors 0x0 - 0x3C
BIM Driver Lib 0x3D - 0xFFF
RCFG (TI-RTOS constants) 0x1000 - 0x14EF
OAD Image Header (metadata) 0x14F0 - 0x14FF
Application Reset Vectors 0x1500 - 0x153C
Application Image 0x153D - 0x1CFFF
NV Storage 0x1D000 - 0x1EFFF
BIM 0x1F000 - 0x1FF89
CCA 0x1FF8A - 0x1FFFF

OAD Image Creation

For generating the images the following tools are required:

A python script oad_image_tool.py is used to convert hex files generated by CCS to an OAD compatible binary. This script can be found:

<SDK_DIR>\tools\common\oad

Usage follows

oad_image_tool.py -h
usage: Texas Instruments OAD Image Tool [-h] [-t {onchip,offchip}]
                                        [-i {app}]
                                        [-v IMGVER] [-o OUT] [-ob [OUTBIN]]
                                        [-f FILL] [-m META] [-r RANGE] [-n]
                                        [-q] [--round ROUND] [--version]
                                        [hexfile [hexfile ...]
python tools/oad_image_tool.py -v 0x0200 -i app sensor_oad_cc13x0lp_app_v2.hex -ob sensor_oad_cc13x0lp_app-nverase_v2.bin -m 0x1000

Halt In Boot (HIB)

There is a bug with the emulation software package that would cause the processor to enter Halt In Boot (HIB) on the next bootup when previously connected to JTAG. In the case of OAD, that is when a system reset is invoked at the end of an OAD procedure.

Note

This only affects devices connected to JTAG, such as the XDS110 on LaunchPads. This issue should not appear in field devices or devices that are not connected to JTAG in general.

The reason why the bug occurs is that the TCK pin (which powers up the JTAG power domain) is left in tri-state. When a system reset occurs after an active debug connection, the TCK pin could potentially experience unwanted toggling from noise. HIB erroneously detects this as debug activity, and subsequently halts the processor.

../_images/oad_hib.png

Figure 40. Reset problems after programming with JTAG

A symptom of this bug occurring is that OAD does not reboot into BIM after a successful OAD. A temporary workaround is to simply unplug/replug or hard reset the device, and the device will boot as normal.

However, a permanent fix is available. As of version 8.0.27.9 of the emulation software package, the XDS110 emulator now drives the TCK pin high instead of leaving it in tri-state. This removes any unwanted toggling on the TCK pin after a system reset, which no longer triggers HIB.

To update the emulation software packages, start by downloading the latest XDS Emulation Software Package. Then, depending on which tool you are using, follow the corresponding step-by-step guide below.

  • For Flash Programmer 2:
    1. Run the above installer
    2. Copy the contents of the emulation software package to <Flash Programmer 2>/config/xds/*
  • For Code Composer Studio:
    1. Run the above installer
    2. Follow the steps described in Section Manual CCS Installation from the XDS Emulation Software Package page
  • For IAR:
    1. Run the above installer
    2. Change the debugger options of the project to point to the newly installed package
../_images/oad_hib_update_xds.png

Figure 41. Update XDS emulation software package in IAR