TI 15.4-Stack OAD

This section describes the TI 15.4-Stack specific implementation of OAD. First the OAD protocol is explained, then the various software modules (OAD Client, OAD Storage, etc).

OAD Protocol

The OAD protocol is based on the principle that the OAD Server initiates and the OAD Client the request the OAD FW image blocks. The OAD client is responsible for requesting image blocks ad handling an error conditions and re-requesting image block when required. Once the OAD has completed the OAD Client will reset and start running the new image.

Warning

If the device is connected to an external debugger when performing an OAD, the device could potentially not reset properly after a successfull OAD. This is a known issue, however, simply unplugging/replugging or hard reset the device will make the device boot properly. Read more about this in detail in Section Halt In Boot (HIB).

OAD Messages

The OAD Protocol uses requests and responses between the OAD Server (Distributer) and OAD Client (Target). The supported messages are described in Table 20..

Table 20. OAD Protocol Message Types
Message Client Server Description
FwVersionReq RX TX Request Firmware version of an OAD Client node.
FwVersionRsp TX RX Response sent from an OAD Client node contatining the firmware version currently running. The OAD Server uses this information to determine if an update is nessisary.
ImgIdentifyReq RX TX Request containing the OAD header of the new FW image sent to a specific OAD client node.
ImgIdentifyRsp TX RX Response from the OAD client node. If the OAD image header is accepted by the OAD client node then the response will contain a success status, if not it will contain a fail status. The reasons for an OAD client node to send a fail status could include: Invalid image type, Invalid version (Client is running a newer version), or Invalid binary size.
SendOadImgBlockReq TX RX If the OAD client node accepts the image header in the ImgIdentifyReq then it will request OAD blocks using the SendOadImgBlockReq. The OAD client will implement a timeout for the SendOadImgBlockRsp and will re-request the OAD block n times if a timeout occurs.
SendOadImgBlockRsp RX TX The requested OAD block will be sent by the OAD server in a SendOadImgBlockRsp. The SendOadImgBlockReq’s and SendOadImgBlockRsp’s will continue until all blocks have been received by the OAD client. Default OAD_BLOCK_SIZE = 128.

OAD Message Flow

Figure 42. shows the flow of OAD messages throughout the entire OAD process.

../_images/fig-oad-protocol-flow.png

Figure 42. OAD Protocol Flow Diagram

The following sequence diagrams illustrate the message flow for the various stages in the OAD. The message flow assumes that the Server is a Fully Functional Device (FFD) and the Client is a Reduced Functional Device (RFD).

FW Version

The FW version is requested by the application on the Server and responded to by the Application on the Client. The Client will only receive the request when it sends a Data Request to the Server.

../_images/fig-oad-fw-version.png

Figure 43. FwVersionReq and FwVersionRsp

Initiating OAD

An OAD is initiated by the OAD Server and is accepted by the OAD Client. The client will only receive the request when it sends a Data Request to the server. The OAD Initiate request will only be accepted by the client if the image header in the request is valid.

../_images/fig-oad-init.png

Figure 44. OAD process being initiated.

OAD Block Transfers

An OAD Client sends a Image Block Request to to OAD Server. There are three possible outcomes of this request:

  • A single block is transfered successfully
  • A single block is transfered, but requires multiple poll requests
  • A request time-out occurs and the request is retried

Figure 45. illustrates a message flow for a single block transfer, and assumes no timeouts occur. Block n represent block 0 to the 2nd to last image block.

../_images/fig-oad-block-transfer.png

Figure 45. Single Block Transfer.

Figure 46. illustrates a message flow for a single block transfer, where the OAD Server does not retrieve the image block before the clients Data Request. Block n represent a random block in the image where the image block is not ready in time for the Data Request.

../_images/fig-oad-block-poll.png

Figure 46. Single Block Transer with Multiple Poll Requests.

Figure 47. illustrates a message flow for a single block transfer, where the OAD clients block request is lost, possibly due to a queue overflow. Block n represent a random block in the image where the image block request is lost. The below assumes a maximum of 3 Data Request time-outs.

../_images/fig-oad-block-transfer-retry.png

Figure 47. Single Block Timeout and is Retried.

The down fall here is that the OAD Client will continue sending poll requests for a block response that will not come. This should be considered when choosing the OAD_POLL_INTERVAL. The trade off is that for longer OAD_POLL_INTERVAL’s the OAD Server will need to queue the block request in the MAC data queue of the Embedded collector for longer. Queuing OAD blocks in the MAC data buffer for large amounts of time could lead to a queue overflow and further block requests not being serviced.

OAD Configurable Parameters

The following parameters can be configured at compile-time:

  • OAD_POLL_INTERVAL: This define is measured in ms and controls the timing on the OAD Client from the sending the Block Request to sending the poll request for the OAD Block Response. A smaller OAD_POLL_INTERVAL decreases the amount of time the OAD Block is queued in the collector and hence the chance that the collector will suffer a buffer overflow. However the Collector will take a finite amount of time to retrieve the OAD block, and queue the OAD Block Response, so care must be taken to make the OAD_POLL_INTERVAL long enough to allow the collector to retrieve the OAD block after receiving the OAD Block request. It is advisable to make this as small as possible in large networks where the collector needs to queue messages for many RFD’s.
  • OAD_REQ_TIMEOUT: This define is measured in ms. It defines the amount of time on the OAD Client between 1 block request and the next block request. Reducing this will reduce the time taken to send an OAD. How quickly the OAD takes to complete is application dependent, severaly power constrained devices may need large periods between block req to allow the power source to recover. Other applications may require the OAD to complete quickly, such as in systems where a service engineer is required to performing the OAD.
  • OAD_BLOCK_SIZE: This define also effects the time taken to complete the OAD. The OAD_BLOCK_SIZE is the number of bytes sent in an OAD Block and can be a minimum of 16 and a maximum of 496B. Care must be taking when setting this to a high value in environments where noise is a concern, as the chances of a block being corrupted due to an interfere increases with the size of the block.

Warning

Increasing OAD_BLOCK_SIZE past 128 on a linux VM may cause instability.

OAD Architecture

Figure 48. shows the SW Architecture for the OAD feature.

../_images/fig-oad-block-diagram.png

Figure 48. TI 15.4-Stack OAD Block Diagram

Modules

TI 15.4-Stack OAD comprises of the following software modules:

  • OAD Protocol Module
  • OAD Storage Module
  • OAD Client Module

The OAD Server Module is simpler to than the OAD client, and does not need to handle events, error conditions or retires. The OAD server functionality is embedded into the existing Linux Collector module.

OAD Protocol Module

The OAD Protocol interface provides device independent APIs, data types, and macros. The Over the Air Download (OAD) Protocol module provides protocol functionality for transferring an OAD image. The APIs in this module serve as an interface to a TI-RTOS application and offers functionality for an OAD messaging protocol between OAD Sever and the OAD Client. The module handles the formatting and parsing of messages.

Initialization

In order to use the OAD Protocol APIs, the application is required to provide application specific configuration and callbacks. For the application to process OAD Messages the following callback table must be provided:

/** @brief OADProtocol callback table
 *
 */
typedef struct
{
    fwVersionReqCb_t      pfnFwVersionReqCb; ///< Incoming FW Req
    fwVersionRspCb_t      pfnFwVersionRspCb; ///< Incoming FW Version Rsp
    oadImgIdentifyReqCb_t pfnOadImgIdentifyReqCb; ///< Incoming Image IdentifyReq
    oadImgIdentifyRspCb_t pfnOadImgIdentifyRspCb; ///< Incoming Image IdentifyRsp
    oadBlockReqCb_t       pfnOadBlockReqCb; ///< Incoming OAD Block Req
    oadBlockRspCb_t       pfnOadBlockRspCb; ///< Incoming OAD Block Rsp
} OADProtocol_MsgCBs_t;

For the OAD module to allocate buffers and send messages the following platform specific call back must be provided:

/** @brief OADProtocol platform access functions
 *
 */
typedef struct
{
    plaformAccessAllocMsg_t         pfnRadioAccessAllocMsg;   ///< Function for allocating a message buffer
    platformAccessPacketSend_t      pfnRadioAccessPacketSend; ///< Function for sending message over the radio
} OADProtocol_PlatformAccessFxns_t;

OADProtocol_init() must be called before any other OADProtocol APIs. The following parametric configuration is passed:

/** @brief RF parameter struct
 *  RF parameters are used with the OADProtocol_open() and OADProtocol_Params_init() call.
 */
typedef struct {
    OADProtocol_PlatformAccessFxns_t  *pPlatformAccessFxns;    ///< Platform access function table
    OADProtocol_MsgCBs_t              *pProtocolMsgCallbacks;  ///< Application Callbacks for pressing packets
} OADProtocol_Params_t;

Application Interface

The OAD Protocol module formats and parses the OAD messages. The following API is exposed:

/** @brief  Function to initialize the OADProtocol_Params struct to its defaults
 *
 *  @param  params      An pointer to RF_Params structure for
 *                      initialization
 *
 *  Defaults values are:
 *      maxretires          = OADProtocol_DEFAULT_MAX_RETRIES
 *     pRadioAccessFxns     = {0}
 *      pCallbacks          = {0}
 */
extern void OADProtocol_Params_init(OADProtocol_Params_t *params);

/** @brief  Function that initializes the Wsn Protocol Task and creates all TI-RTOS objects
 *
 */
extern void OADProtocol_init(void);

/** @brief  Function to open the OADProtocol module
 *
 *  @param  params      An pointer to RF_Params structure for initialization
 */
extern void OADProtocol_open(OADProtocol_Params_t *params);

/** @brief  Function to parse OADProtocol packets
 *
 *  @param  srcAddr             address of the device that sent the message
 *  @param  incomingPacket      pointer to packet to be parsed
 *  @param  packetLen           length of the message
 */
extern OADProtocol_Status_t OADProtocol_ParseIncoming(void* pSrcAddr, uint8_t* incomingPacket, uint8_t packetLen);


/** @brief  Function to send a FW version request packet
 *
 *  @param  dstAddress          Address to send the request to
 *
 *  @return                     Status
 */
extern OADProtocol_Status_t OADProtocol_sendFwVersionReq(void* pDstAddress);

/** @brief  Function to send a FW version response packet
 *
 *  @param  dstAddress          Address to send the response to
 *  @param  fwVersion           Firmware version string to send
 *
 *  @return                     Status
 */
extern OADProtocol_Status_t OADProtocol_sendFwVersionRsp(void* pDstAddress, char *fwVersion);

/** @brief  Function to send an OAD image identify request packet
 *
 *  @param  dstAddress          Address to send the request to *
 *  @param  imgId               image ID used for requesting image blocks
 *  @param  pImgInfoData        Image header
 *
 *  @return                     Status
 */
extern OADProtocol_Status_t OADProtocol_sendImgIdentifyReq(void* pDstAddress, uint8_t imgId, uint8_t *pImgInfoData);

/** @brief  Function to send an OAD image identify request packet
 *
 *  @param  dstAddress          Address to send the response to
 *  @param  status              status to send
 *
 *  @return                     Status
 */
extern OADProtocol_Status_t OADProtocol_sendOadIdentifyImgRsp(void* pDstAddress, uint8_t status);

/** @brief  Function to send an OAD block request packet
 *
 *  @param  dstAddress          Address to send the request to
 *  @param  imgId               image ID of image blocks
 *  @param  blockNum            block Number to request
 *  @param  multiBlockSize      Numer of blocks in the multi Block transfer (0 or 1 for none-multiblock)
 *
 *  @return                     Status
 *
 */
extern OADProtocol_Status_t OADProtocol_sendOadImgBlockReq(void* pDstAddress, uint8_t imgId, uint16_t blockNum, uint16_t multiBlockSize);

/** @brief  Function to send an OAD block response packet
 *
 *  @param  dstAddress          Address to send the response to
 *  @param  imgId               image ID of image blocks
 *  @param  blockNum            Block number
 *  @param  block               pointer to image block
 *
 *  @return                     Status
 *
 */
extern OADProtocol_Status_t OADProtocol_sendOadImgBlockRsp(void* pDstAddress, uint8_t imgId, uint16_t blockNum, uint8_t *block);

Usage

To use the OAD Protocol module to format and parse OAD messages, the application calls the following APIs:

  • OADProtocol_init(): Initialize the OADProtocol module/task
  • OADProtocol_Params_init(): Initialize a OADProtocol_Params structure with default values. Then change the parameters from non-default values as needed.
  • OADProtocol_open(): Open an instance of the OADProtocol module, passing the initialized parameters.
  • OADProtocol_sendFwRequest(): This is an example of an OAD message that is formated and sent.

The following code example opens OADProtocol, sends a FW version request and processes the response.:

OADProtocol_packetCBs_t OADProtocolCbs = {
  NULL, //Incoming FW Req
  fwVersionReqCb, //Incoming FW Version Rsp
  NULL, //Incoming Image Identify Req
  NULL, //Incoming Image Identify Rsp
  NULL, //Incoming OAD Block Req
  NULL, //Incoming OAD Block Rsp
  NULL, //Error callback
};

static void fwVersionRspCb(uint16_t srcAddr, char *fwVersionStr)
{
  //Do something with srcAddr and fwVersionStr
}

void someTaskInit(void)
{
  OADProtocol_init();
}

void someTaskFxn(void)
{
  // Set Default parameters structure
  static OADProtocol_Params_t OADProtocol_params;

  // Initialize and open the Wsn Protocol Task
  OADProtocol_Params_init(&OADProtocol_params);
  OADProtocol_params.pCallbacks = &OADProtocolCbs;
  OADProtocol_params.devType = OADProtocol_DevType_Concentrator;
  OADProtocol_params.devAddress = OADProtocol_CONCENTRATOR_ADDRESS;
  OADProtocol_open(&OADProtocol_params);

  OADProtocol_sendFwVersionReq(nodeAddress);

}

OAD Storage Module

The OAD Storage interface provides device independent APIs, data types, and macros for Storing the OAD image. The OAD Storage module calls into oad_target, which provide the device dependent functionality to write the OAD image into flash. oad_target contains the support for internal (on-chip) and external (off-chip) OAD Image storage.

OAD Storage Configuration

The oad_target module can be configured at build time to use on-chip or off chip storage by linking in the correct target c file:

  • oad_target_external_flash.c
  • oad_target_internal_flash.c

Note

For on-chip OAD, the OAD Storage module must be built with FEATURE_OAD_ONCHIP defined.

Initilization

OADStorage_init() must be called before any other OADTarget APIs.

Application Interface

The OAD Storage module exposes the following API for staring the OAD image:

/*********************************************************************
 * @fn      OADStorage_init
 *
 * @brief   Initialise the OAD Target Profile.
 *
 * @param   None.
 *
 * @return  None.
 */
extern void OADStorage_init(void);

/*********************************************************************
 * @fn      OADStorage_imgIdentifyWrite
 *
 * @brief   Process the Image Identify Write.  Determine from the received OAD
 *          Image Header if the Downloaded Image should be acquired.
 *
 * @param   pValue     - pointer to data to be written
 *
 * @return  status
 */
extern OADStorage_Status_t OADStorage_imgIdentifyWrite(uint8_t *pValue);

/*********************************************************************
 * @fn      OADStorage_imgBlockWrite
 *
 * @brief   Process the Image Block Write.
 *
 * @param   connHandle - connection message was received on
 * @param   pValue - pointer to data to be written
 *
 * @return  status
 */
void OADStorage_Status_t OADStorage_imgBlockWrite(uint8_t *pValue);

/*********************************************************************
 * @fn      OADStorage_imgFinalise
 *
 * @brief   Checks the image CRC and marks the image for use. The BIM
 *          will than copy the image (for off-chip) and execute.
 *
 * @param  none
 *
 * @return  status
 */
OADStorage_Status_t OADStorage_imgFinalise(void);

/*********************************************************************
 * @fn      OADStorage_close
 *
 * @brief   Releases the resource required for OAD storage.
 *
 * @param  none
 *
 * @return none
 */
void OADStorage_close(void);

OAD Client Module

The OAD client module has been designed to provide a simple and customizable implementation for the customer. In its most rudimentary form, this module is responsible for accepting/rejecting an OAD interaction based on image header criteria, storing the image in its appropriate location, and causing a device reset if the download is successful so that the downloaded application image is run by the BIM.

The OAD Client module provides a service to process and generate application events for OAD Client functionality, it is specific to a TI 15.4-Stack application. It houses the code required for the application to act as an OAD Target, reducing the code needing to be added in the application files. The OAD Client uses the services provided by the OAD_Protocol and OAD_Storage modules.

Initialization

In order for the OAD Client module to process and generate application events it needs to be initialized with an event handle used to set event masks as they occur and the applications semaphore that can be used to wake up the application after an event is set.

OADClient_init() must be called before the module can process OAD events. The following parametric configuration is passed:

/** @brief RF parameter struct
*  RF parameters are used with the SOADProtocol_open()
*   and SOADProtocol_Params_init() call.
*/
typedef struct {
    uint16_t *pEvent;             ///< Event handle to post to
    ICall_Semaphore eventSem;    ///< Semaphore to post event
} OADClient_Params_t;

Application Interface

The OAD Client module formats and parses the OAD messages. The following API is exposed:

/** @brief  Function to open the OADProtocol module
*
*  @param  params      An pointer to OADClient_Params_t structure
*  for initialization
*/
extern void OADClient_open(OADClient_Params_t *params);

/** @brief  Function to process OAD events
*
*  @param  pEvent      Event to process
*/
extern void OADClient_processEvent(uint16_t *pEvent);

/** @brief  Function abort OAD
*
*  @param  resume      set to true if a auto resume is required
*/
void OADClient_abort(bool resume);

/** @brief  Function abort OAD
*
*  @param  delay      time in ms to start resume
*/
void OADClient_resume(uint32_t delay);

Example Function Trace

Figure 49. shows the typical function flow for an OAD Client to send a message from the Application through the OAD Client and OAD Protocol modules to the MAC API.

../_images/fig-oad-req-message-flow.png

Figure 49. Block Request message flow.

Figure 50. shows the typical function flow for an OAD Client receiving a messge from the OAD Server through the OAD Protocol module to the MAC API.

../_images/fig-oad-rsp-message-flow.png

Figure 50. Block Response processing.

OAD Server

There is no separate tool for the OAD Server, OAD Server functionality is provided by the Linux Collector Application, part of the TI 15.4-Stack Linux SDK. When the collector application is built without the IS_HEADLESS flag an interactive command-line interface to the collector application exposes the following functionality:

  • Devices can be selected
  • A firmware file can be selected for transfer
  • LED toggle requests can be sent to the selected device
  • Version requests can be sent to the selected device
  • Firmware update requests can be sent to the selected device

A typical view of this interface

TI Collector
Nwk: Started
Sensor 0x0001: Temp 25, RSSI -18
Sensor 0x0002: OAD Block 211 of 960


Info: Sending 0x0002 FW update Req
cmd: u

The available commands are:

  • sxx: Select a device. Example ‘s1’| ‘s0x1234’
  • o: Toggle the permit join
  • l: List devices
  • t: Send an LED toggle request to selected device
  • v: Send a version request to selected device
  • u: Send FW update request to selected device
  • d: Send disassociation request to selected device
  • fxx: Set FW file from configured OAD FW dir. Example ‘f sensor_mac_oad_cc13x2lp_app.bin’

OAD Pause and Resume

The TI 15.4-Stack OAD feature supports the following robustness features:

  1. Timeouts: This is when a the data request for a block response is not answered. The data request delay from an OAD block request being sent is set by OADBLOCKREQPOLLDELAY ms, it is advised that this be set as short as possible to avoid unnecessary queueing of data in the Co-Processor. A timeout is typically caused by the Linux Collector taking too long to read the OAD Block from the FW Image file (due to CPU load). The number of timeouts before a retry is set by OADMAXTIMEOUTS.
  2. Retries: A retry is when the maximum number timeouts has expired before the OAD Block Response has been received. In his case the OAD Block Request is resent. The number of retires before an OAD Abort is set by OADMAXRETRIES.
  3. Aborts: The OAD is aborted after there are OADMAXRETRIES block requests with no response. After an OAD abort the OAD is attempted to be resumed after OADBLOCKAUTORESUMEDELAY ms, if the OAD abort again on the same block number the OAD is terminated.

The OAD is aborted if the device Orphans, when the device rejoins an OAD resume is attempted. If the device is reset / powered off during an OAD the device will attempt to resume when it rejoins. The block it resumes from is set to the first block of the page it was aborted from in case the flash page was corrupted by the power cycle.

Support for multiple OAD files

The OAD protocol supports multiple OAD images by using an Image ID that is sent when the Collector initiates the OAD and then in each OAD block request / response. This insures that the device always receives a block from the correct FW image, especially in the case where a device loses power or orphans and it is not known when it will come back on line. When an OAD image file is selected on the collector it is assigned a new image ID and added to a table, when a block request is received the image ID in the block request is used to find the correct FW image file. This insures that a device will always get a block from the correct image, no matter how long it is off line.

OAD Default Settings

Most OAD settings are defined in oad_client.c, and already discussed in the Pause and Resume section. In addition to this you can override the OADBLOCK_SIZE from the default of 128 by defining it in the project options. Setting this higher than 128 is not advised as this is the setting used during system testing.

Beacon Mode, Non Beacon Mode and Frequency Hoping network modes are supported. In Non Beacon Mode and Frequency Hoping the default OAD parameters are:

#define OAD_BLOCK_REQ_RATE            200
#define OAD_BLOCK_REQ_POLL_DELAY      40
#define OAD_MAX_TIMEOUTS              3
#define OAD_MAX_RETRIES               3
#define OAD_BLOCK_AUTO_RESUME_DELAY   5000

Under normal conditions the sensor sends a block request every 200ms, with a typical file of 920 blocks this takes ~3 minutes. In Beacon Mode only one data request can be sent during 1 beacon interval. The default OAD settings are:

#define OAD_BLOCK_REQ_RATE            ((CONFIG_SUPERFRAME_ORDER * 1000) - 500)
#define OAD_BLOCK_REQ_POLL_DELAY      (CONFIG_SUPERFRAME_ORDER * 1000)
#define OAD_MAX_TIMEOUTS              3
#define OAD_MAX_RETRIES               3
#define OAD_BLOCK_AUTO_RESUME_DELAY   (CONFIG_SUPERFRAME_ORDER * 5)

Under normal conditions the OAD will take CONFIG_SUPERFRAME_ORDER * 920 seconds.

The sensor_oad project has 2 defines related to te OAD feature, defined by default in the project options:

  • FEATURE_OAD This includes the OAD linker command file and OAD TI-RTOS config file.
  • FEATURE_NATIVE_OAD This includes the TI 15.4-Stack OAD client. This results in an application that supports the OAD messages needed to receive an OAD update over the TI 15.4-Stack network.

Removing the FEATURE_NATIVE_OAD symbol will result in an application that is capable of being updated through a BLE link only. For a TI 15.4-Stack OAD both FEATURE_OAD and FEATURE_NATIVE_OAD should be defined.