Turbo OAD Protocol¶

The Turbo OAD Protocol was designed to speed up the traditional OAD protocol, specifically in terms of power consumption and over the air time.

Turbo OAD enables the support of using delta software updates in the OAD protocol. Delta updates are software updates that contain only the changed or updated content in the new software image.

This section describes the Turbo OAD process and how it is used in conjunction with the traditional OAD protocol described above. For information on how to enable Turbo OAD, please refer to the TI 15.4 stack OAD examples’ readme files.

Figure 72. High Level Overview of Turbo OAD integration

As shown in Figure 72., the core logic of Turbo OAD to create delta images is done with the Turbo OAD Image Tool, while reconstructing the delta image is done on the OAD Target device.

Turbo OAD Image Tool¶

The Turbo OAD Image tool is a Python script that must be ran by the user, as similarly done for the 13x0 OAD Image Tool. More information regarding the usage can be found in the sensor_oad project’s README file.

The purpose of the tool is to perform the delta and run-length encoding processes. The Turbo OAD Image tool takes in two binary images and outputs one delta image, which is then sent to the target OAD device through the OAD protocol described above.

The tool will also determine if a Turbo OAD is needed based on the delta image. If there is no power / image size savings by using Turbo OAD, then regular OAD will be used. The tool will output an error message indicating that the delta image was not created.

Turbo OAD Block Transfer Overview¶

The OAD protocol for transferring the image mainly remains the same. However, instead of directly writing received OAD blocks to external/internal flash, OAD blocks are cached in RAM and are decoded (during the OAD image transfer) before writing to flash. This has the following implications:

No additional flash space is required to store the delta image.

RAM is required to store received OAD blocks and a write buffer to store decoded image data before flashing. In general, the more RAM used, the faster the OAD and decoding process will be.

Since the RAM used is dynamically allocated, the OAD update could fail on initialization if there are insufficient resources to decode the delta image.

OAD block requests may need to be temporarily ‘paused’ if the block buffer cache is full and the device is still decoding data. OAD block requests will resume once there is space in the storage buffer to continue the transfer.

Turbo OAD Image Reconstruction Process Overview¶

The 15.4 OAD protocol initiates the OAD transfer by having the collector select the delta image to transfer and sending the ImgIdentifyReq to the sensor. The Turbo OAD segment header fields have been added to the ImgIdentifyReq to facilitate the transfer of delta images. For more information regarding the Turbo OAD header segment, see the Turbo OAD Delta Image Header section.

../_images/ImgIdentifyReq-Validation.png

Figure 73. Turbo OAD Image Validation and Reconstruction Overview

Warning

Performing a Turbo OAD to a target device that has been flashed with traditional OAD firmware is not supported.

The image reconstruction process is done during the OAD transfer. The decoding process consists of a temporary block cache (ring buffer) that stores received blocks which have not been decoded. Decoded blocks are written to an image buffer that is then flashed to the device when filled.

The process begins with receiving an OAD block from the collector. After a control block instruction has been received, the decoding process will begin. When the data from the OAD block has been decoded, the block will be marked to indicate that the space can be used to store a subsequent OAD block.

Note that each OAD block is a pre-determined size as specified by the OAD_BLOCK_SIZE define. A Delta Image block can be any arbitrary size, and typically will be larger than OAD_BLOCK_SIZE. The implication of this is that multiple OAD blocks must be received by the sensor until a decoding instruction can fully be processed. However, the complete instruction does not need to be received in order to begin the decoding process.

OAD blocks are still requested at the rate defined by OAD_BLOCK_REQ_RATE. However, if the OAD block cache is full, the OAD transfer will be paused until there is room to store the next block.

Figure 74. Turbo OAD Decoding State Machine

Table 23. Turbo OAD Decoding State Machine Descriptions¶
State	Description
Uninitialized	Starting state before the Turbo OAD module has been initialized
Idle	The module is waiting for new data to be received in the block cache
Decoding	The module is currently decoding a delta block
Waiting	The module is either currently decoding a delta block or is ready to begin decoding the next block. However, not enough data is available in the block cache to continue decoding
Done	Completion of decoding the delta image

Since the length of the uncompressed delta block is variable, the decoding process will yield to the application task if the image buffer has been flushed, or a full instruction has been decoded. If an instruction has not been fully decoded, the decoding process will resume after any pending application code has been executed.

Turbo OAD Delta Image Header¶

Upon completion of the OAD transfer and delta image decoding, the Turbo OAD process is complete, and the normal process of verifying the image CRC and rebooting remains the same.

The modified OAD Image Header can be seen in oad_target.h as shown here:

{
    uint16_t ver;
    uint16_t len;                           // Image length in 4-byte blocks (i.e. HAL_FLASH_WORD_SIZE blocks).
    uint8_t uid[4];                         // User-defined Image Identification bytes.
    uint8_t res[4];                         // Store start address, image type, and image status
#ifdef FEATURE_TOAD
    uint8_t deltaImgID[TOAD_IMG_ID_LEN];    // Indicates if payload is delta image
    uint8_t toadMetaVer;                    // Turbo OAD header version
    uint8_t toadVer;                        // Turbo OAD version
    uint16_t oldImgCrc;                     // CRC of the current app image
    uint16_t newImgLen;                     // Length of the uncompressed image in 32-bit words
    uint16_t oldImgLen;                     // Length of the old image in 32-bit words
#endif
    }

Table 24. Turbo OAD Segment Header¶
Field	Size (in bytes)	Description
deltaImgID	8	ID: “TURBOOAD”
toadMetaVer	1	Version of the delta image header segment
toadVer	1	Version of the Turbo OAD decoding algorithm
oldImgCrc	2	Crc value of the old/current application image running on the device
newImgCrc	2	Crc value of the new/updated application image to be flashed on the device
oldImgLen	2	Length of current application image with padding bytes removed

Table 25. Modified OAD Header data¶
Field	Value	Notes
Image Length	Delta Image Length	Uncompressed image’s length is stored in the Turbo OAD segment header after image is reconstructed

The Turbo OAD Version and Original Image CRC field is used during the ImgIdentifyReq to ensure that the delta image can properly be reconstructed. The length of the new image is stored in the Turbo OAD header because the OAD header’s length field is the size of the delta image and not the reconstructed image size. When the OAD header is received from delta image, the length field will be replaced with the value stored in the ‘Image Length’ field, also the Turbo OAD header segment will not be re-written from the binary image into flash when the OAD target receives the image. This is done to preserve compatibility with CC13x0 BIM.

Typical Turbo OAD workflow¶

Enable Turbo OAD by definining “-DFEATURE_TOAD” in the <PROJECT_DIR>/Application/Defines/sensor_oad_offchip.opts file and build the project.
Build the BIM project.
Create a combined BIM and sensor image by using the hexmerge tool.
- python <PYTHON_DIR>/Scripts/hexmerge.py -o sensor_oad_cc1350lp_tirtos_ccs_all.hex “–overlap=error” sensor_oad_cc1350lp_tirtos_ccs.hex bim_extflash_cc13x0lp.hex
Load the device with the newly created hex file.
Create an OAD bin file for the sensor application. This is needed when creating the diff image later in the process.
- python ../../../../../../tools/common/oad/oad_image_tool.py -v [0xXXYY] -i app sensor_oad_cc1350lp_tirtos_ccs.hex -ob sensor_oad_cc13x0lp_app.bin -m 0x14F0 -r :0x1E000
Make changes to the sensor project, for example changing the name or version number, and rebuild the project.
Create an OAD image for the new image.
- python ../../../../../../tools/common/oad/oad_image_tool.py -v [0xXXYY] -i app sensor_oad_cc1350lp_tirtos_ccs.hex -ob sensor_oad_cc13x0lp_app.bin -m 0x14F0 -r :0x1E000
Create a delta image.
- python <SDK_DIR>/tools/ti154stack/turbo_oad/toad_image_tool.py -oimg original_app.bin -nimg new_app.bin -o sensor_oad_cc13x0lp_app.dim
Perform an OAD to update to the new image.