15.4 CC13x2 OAD Example

This example contains the sensor_oad project intended to be used with the Linux collector for updating the a singed FW image over the 15.4 network. This project can also be used with a BLE Factory image to complete BLE OAD of a 15.4 image.

Note: BLE OAD is not yet supported for 1312 devices.

Out of Box example

The out of box example for sensor OAD uses the Linux collector (CC1352R1_LAUNCHXL A) to update the FW on a sensor (CC1352R1_LAUNCHXL B). The following steps walk through the process of using the pre-built binaries to perform an OAD:

Using Uniflash load <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ti154stack/hexfiles/coprocessor_cc13xx_lp.hex into a CC1352R1_LAUNCHXL A

Using Uniflash load <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ti154stack/hexfiles/oad/sensor_oad_cc13x2lp_v1.bin onto CC1352R1_LAUNCHXL B

Using Uniflash load <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ti154stack/hexfiles/oad/bim_offchip_cc13x2lp.hex onto CC1352R1_LAUNCHXL B as well.

Connect CC1352R1_LAUNCHXL A (the coprocessor) to a Linux machine and run the Linux Collector application. If the sensor has previously connected to the Linux collector and then been reprogrammed (erasing its network parameters stored in flash) you will need to remove the nv-simulation.bin file before launching the application. More information can be found on using the Linux collector in the Linux SDK Documentation, to use the Linux collector for OAD make sure it is built without the IS_HEADLESS pre-defined symbol. When ran the Linux Collector will display the following UI on the terminal:

TI Collector
Nwk: Started
Sensor 0x0001: Temp 25, RSSI -18


Info: ConfigRsp 0x0001
cmd:

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'

Once joined to the network the sensor must be selected with the command sx (where x is the short address of the device – i.e. s1 or s0x0001). This will display:

TI Collector
Nwk: Started
Sensor 0x0001: Temp 25, RSSI -18


Info: Selected device 0x0001
cmd: s1

The current FW version running on the sensor can be requested using the v command. The next time the sensor polls it will respond and the FW version will be displayed. This will include application version (sv) and bim version (bv) that the OAD image is intended for.

TI Collector
Nwk: Started
Sensor 0x0001: FW Ver sv:0001 bv:01


Info: Sending 0x0001 FW Version Req
cmd: v

Note that the version of BIM must match the BIM’s being used in the system.

Copy <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ti154stack/hexfiles/oad/sensor_oad_cc13x2lp_v2.bin to the Linux machine. Paste the ‘.bin’ file in the following location: /ti/simplelink/ti-15.4stack-2.03.00.01_eng/firmware/oad/cc13x2/.

The FW image file to update can be selected using the f <path_to_File/file_name.bin> command:

TI Collector
Nwk: Started
Sensor 0x0001: FW Ver sv:0001 bv:01 st:02


Info: OAD file ../../firmware/oad/cc13x2/sensor_oad_cc13x2lp_app_v2.bin
cmd: f ../../firmware/oad/cc13x2/sensor_oad_cc13x2lp_app_v2.bin

Entering just f will report the currently selected file.

A FW update of the selected sensor can be initiate with the u command. The next time the sensor polls it will process the request and if the FW update is accepted the sensor will start requesting OAD image blocks:

TI Collector
Nwk: Started
Sensor 0x0001: OAD Block 41 of 928


Info: Sending 0x0001 FW Update Req
cmd: u

Depending on the build options, the sensor may also display the block request on the serial port and/or LCD:

OAD Block: 1
of 928
OAD Block: 2
of 928

Once OAD is complete the sensor will reboot and depending on if the NV page was included in the image the sensor may join the network.

OAD Block: 927
of 928
OAD completed successfully
TI Sensor
State Changed: 2
Restarted: 0x1
Channel: 0
State Changed: 4

The Linux collector can then verify that the new FW version is running on the sensor with the v command:

TI Collector
Nwk: Started
Sensor 0x0001: FW Ver sv:0002 bv:01


Info: Sending 0x0001 FW Version Req
cmd: v

Generating the required binary images

The oad image is created as part of the post build process in the sensor_oad_cc13x2 project:

To update the version in the OAD header open the project in CCS and change the SOFTWARE_VER define in Application/oad/oad_image_header_app.c

When the project is rebuilt the resulting bin can be found in /sensor_oad_cc13x2lp/sensor_oad_cc13x2lp/sensor_oad_cc13x2lp.bin

Note the generated .out and .hex will not have the correct CRC, hence the BIM will not boot into the image. During development the BIM can be built with the JTAG_DEBUG define to allow the BIM to ignore the incorrect CRC. During normal operation when flashed for the first time the application .bin and the bim .hex file need to be loaded separately

Native 15.4 OAD Pause and Resume

The native 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 OAD_BLOCK_REQ_POLL_DELAY 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 OAD_MAX_TIMEOUTS.
  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 OAD_MAX_RETRIES.
  3. Aborts: The OAD is aborted after there are OAD_MAX_RETRIES block requests with no response. After an OAD abort the OAD is attempted to be resumed after OAD_BLOCK_AUTO_RESUME_DELAY 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.

BLE OAD of a 15.4 Image

Note: BLE OAD is not yet supported for 1312 devices.

When the LEFT Button is held down and a reset occurs (RESET Button or cord unplug/plug in) the sensor_oad_cc13x2 project will perform markSwitch function that invalidates itself as a bootable image candidate and performs a soft reset of the device. This will cause the BIM to boot up like normal, however, when the BIM checks to see if the image that is currently in internal flash (15.4 13x2 sensor iamge) it will see that the image is no longer valid. This will cause the BIM to copy the current Factory Image that is stored in External Flash to Internal Flash and perform a soft reset. Now when the BIM boots up again, the current running image (Factory Image) will be valid and the BIM will let the current image to start execution.

In order for this functionality to be useful however, one first needs to have a Factory Image saved into External Flash. Luckily, when the BIM boots up and there is no current Factory Image and the current internal image is valid, a copy of the current internal image will be made efectivly creating a backup of the current image. This is useful, but will not provide any special functionality other than redundency. Instead you can first flash the LP with a BLE Simple Peripheral OAD application and BIM so that it creates a backup of that image. Then using BLE OAD send the Sensor 15.4 Image to the LP. Now, whenever you want, you can switch to the Factory Image and upgrade to any image you want.

To achieve this demo you will need at least two 13X2 LaunchPads.

Using Uniflash load <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ble5/hexfiles/ble5_host_test_cc13x2r1lp_app.hex into a CC1352R1_LAUNCHXL A

Using Uniflash load <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ble5/hexfiles/oad/ble5_simple_peripheral_oad_offchip_cc13x2r1lp_app_FlashROM_Release_oad.bin onto CC1352R1_LAUNCHXL B

Using Uniflash load <SDK_DIR>/examples/rtos/CC1352R1_LAUNCHXL/ti154stack/hexfiles/oad/bim_offchip_cc13x2lp.hex onto CC1352R1_LAUNCHXL B as well.

Open up Btool which can be found in

and select port corresponding to CC1352R1_LAUNCHXL A. All other Serial Port Settings should be left at the defaults. Now Select the Scan button in the GUI and when the scan has completed Establish a connection with the CC1352R1_LAUNCHXL B’s BLE Address. **Note that the BLE Address can be seen by looking at UART output of the CC1352R1_LAUNCHXL B or by using Uniflash->Settings & Utilities->Read Primary BLE Address

When the connection has been established you can now switch over to the Over The Air Download tab in the top left hand corner of the GUI.

Now select Read Image File and navigate to the 13x2 15.4 sensor image you created earlier. Make sure to select the OAD To External Flash check box and the Send the image.

When the OAD has completed, CC1352R1_LAUNCHXL B will boot up into the new sensor image and you can perform native OAD as described above in this document. When the time comes you would like to switch back to the BLE Factory Image that was saved into the External Flash simply hold the LEFT button and reset the device.

CC1352R1_LAUNCHXL A will now boot into the BLE Simple Peripheral OAD image again and you can repeat the process as much as you’d like.

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.

Native 15.4 OAD parameters and default settings

Most OAD settings are defined in oad_cleint.c, and already discussed in the Pause and Resume section. In addition to this you can override the OAD_BLOCK_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.

When using a 2.4g network however the default OAD_BLOCK_SIZE will be 64. It is not suggested to modify this default value.

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.

Depending on the CONFIG_SUPERFRAME_ORDER and CONFIG_BEACON_ORDER that you choose to use in config.h, the time to complete an OAD will differ. It is suggested that you use a value of 4 for both CONFIG_SUPERFRAME_ORDER and CONFIG_BEACON_ORDER.

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