OAD Process

This section explains the Over-the-Air Download (OAD) process in a proprietary RF application when using the TI BIM bootloader. It explains the available software modules that enable the OAD process.The OAD process can be integrated in a custom RF application. The TI BLE stack and the TI 15.4 stack for CC13xx share the same OAD image format, but implement the update process in different ways.

The following steps are part of the update process:

  1. Creating an OAD-able binary image for the target. This step is identical to OAD with BLE or TI 15.4 Stack.

  2. Uploading the target image to the distributor device.

  3. Reading the firmware version from the remote target.

  4. Downloading the image from the distributor to the target device.

  5. Invoking the BIM and replacing the existing firmware image.

The OAD message protocol between distributor and target is characterized by various requests and responses. The next graph shows all relevant message types:

hide footbox participant "OAD Distributor application" as d participant "OAD Target application" as t activate d activate t == Reading the target firmware version == d -> t : Firmware version request d <- t : Firmware version response == Downloading the image to the target == d -> t : Image identify request d <- t : Image identify response d <- t : Block request (0) d -> t : Block response (0) == Repetition == d <- t : Block request (n) d -> t : Block response (n)

Figure 68. High-level communication protocol

Proprietary RF OAD software architecture

The update process involves two participants:

Note

In the Proprietary RF OAD system, the OAD Client refers to the Target side software OAD server refers to the Distributor side software.

There are two tools involved in the oad process:

  • oad_img_tool.py - Prepares the target image for over the air transfer

  • oad_write_bin.py - Writes a target image on to the server’s storage

The OAD distributor buffers new firmware target images using the OAD Storage service. The OAD target responds to the distributor’s requests and may download a new firmware. The firmware is then stored using the OAD Storage service. After the download process, the target invokes the BIM to copy the image to its final position and to boot the new firmware.

The whole Proprietary RF OAD system can be visualized as shown in the figure.

../_images/oad-proprf-topology.PNG

OAD Client

The behavior of the OAD client during the OAD process is explained in this state machine.

../_images/oad_control_flow_target.png

OAD Client Protocol Functions and Callbacks

The functions and callbacks used in the OAD client application is listed in this section. These functions fucntions and callbacks are picked from oad_protocol.h which is included in the project.

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

/** @brief  Function to send a FW version response packet
*
*  @param  pDstAddress         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  pDstAddress         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  pDstAddress         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 a OAD reset response packet
*
*  @param  pDstAddress         Address to send the response to
*
*  @return                     Status
*/
extern OADProtocol_Status_t OADProtocol_sendOadResetRsp(void* pDstAddress);

OAD Server

The behavior of the OAD server during the OAD process is explained in this state machine.

../_images/oad_control_flow_server.png

OAD Server Protocol Functions and Callbacks

The functions and callbacks used in the OAD server application is listed in this section These functions fucntions and callbacks are picked from oad_protocol.h which is included in the project.

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

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

/** @brief  Function to send an OAD image identify request packet
*
*  @param  pDstAddress         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  pDstAddress         Address to send the response to
*  @param  status              status to send
*
*  @return                     Status
*/
extern OADProtocol_Status_t OADProtocol_sendOadIdentifyImgRsp(void* pDstAddress, uint8_t status);

OAD Storage

The OAD storage module provides the APIs to store and retrieve images and version number of images from flash memory. The APIs are used in both the server and the client oad projects. These functions fucntions and callbacks are picked from oad_storage.h which is included in the project.

/*********************************************************************
* @fn      OADStorage_init
*
* @brief   Initialise the OAD Target Profile.
*
* @param   None.
*
* @return  None.
*/
extern void OADStorage_init(void);
/*********************************************************************
* @fn      OADStorage_imgIdentifyRead
*
* @brief   Read Image header and return number of blocks.
*
* @param   imageType   - image type indicating which image to read
* @param   pImgHdr     - pointer to image header data
*
* @return  Total Blocks if image accepted, 0 if Image invalid
*/
uint16_t OADStorage_imgIdentifyRead(uint8_t imageType, OADStorage_imgIdentifyPld_t* pImgId);

/*********************************************************************
* @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  Total Blocks if image accepted, 0 if Image rejected
*/
extern uint16_t OADStorage_imgIdentifyWrite(uint8_t *pValue);

/*********************************************************************
* @fn      OADStorage_imgBlockRead
*
* @brief   Read Image Block.
*
* @param   blockNum   - block number to be written
* @param   pBlockData - pointer for data to be read
*
* @return  none
*/
extern void OADStorage_imgBlockRead(uint16_t blockNum, uint8_t *pBlockData);

/*********************************************************************
* @fn      OADStorage_imgInfoRead
*
* @brief   Read an Image info.
*
* @param   pimgInfo - pointer for data to be read
*
* @return  none
*/
extern void OADStorage_imgInfoRead(uint8_t *pimgInfo);

/*********************************************************************
* @fn      OADStorage_imgBlockWrite
*
* @brief   Write Image Block.
*
* @param   blockNum   - block number to be written
* @param   pBlockData - pointer to data to be written
* @param   len        - length fo block
*
* @return  status
*/
extern uint8_t OADStorage_imgBlockWrite(uint32_t blockNum, uint8_t *pBlockData, uint8_t len);

/*********************************************************************
* @fn      OADStorage_eraseImgPage
*
* @brief   Erases an Image page. Note this is only needed if an image
*          page has been corrupted typically OADStorage_imgBlockWrite
*          pre-erase all pages
*
* @param  none
*
* @return  OADStorage_Status_t
*/
extern OADStorage_Status_t OADStorage_eraseImgPage(uint32_t page);

/*********************************************************************
* @fn      OADStorage_imgFinalise
*
* @brief   Process the Image Block Write.
*
* @param  none
*
* @return  status
*/
extern OADStorage_Status_t OADStorage_imgFinalise(void);

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