BLE-Stack OAD Profile

The TI OAD Profile has been designed to provide a simple and customizable. In its most basic form, for both on-chip and off-chip OAD, this profile is responsible for accepting an OAD interaction based on image header criteria, storing the image onto the flash, and causing a device reset if the download is successful so that the downloaded application image is run by the BIM. The OAD distributor and OAD target perform the GATT client role and server role respectively. The TI OAD Profile consists of two services:

  • OAD Service
  • OAD Reset Service. (used for on-chip OAD only)

Over the Air Message Sequence

The following section details the over the interaction between the target and distributor. See the following sections for description of the individual messages and how to decode them.

The following diagram

@startuml
Distributor <- Target: Advertisements
Distributor -> Target: Connect Req
Distributor <-> Target: OAD Service Discovery

Distributor -> Target: Enable Notifications on OAD Img Identify Char
Distributor -> Target: Enable Notifications on Ext Control Char

Distributor -> Target: ATT_ExchangeMTUReq
Distributor <- Target: ATT_ExchangeMTURsp

note right of Target
Target uses negotiated MTU to select OAD block size in the range of
[20, 244]
end note

Distributor -> Target: Get OAD Block Size Ext Ctrl Command
Distributor <- Target: OAD Block Size Response

group Optional Throughput Enhancements
    Distributor -> Target: LE Set Data Length (4.2 Data length extension)
    Distributor <- Target: LE Set Data Length Response
end group

Distributor -> Target: Write to Image Identify Char

note right of Target
Target validates image identify command
end note

alt Image is rejected by Target
Distributor <- Target: Notification on Image ID Char with failed status
note over Distributor, Target
  OAD process terminates in the case of rejected image identify
end note

else Image is accepted by Target
Distributor <- Target: notification on Image ID Char with OAD_SUCCESS
end

note left of Distributor
Read requested block
from image file
end note

Distributor -> Target: Write 1st block with block num to Image Block Char

group Repeat For Each Block In the Image

Distributor <- Target: Notification on Image Block Char requesting next block
note left of Distributor
Read requested block
from image file
end note

Distributor -> Target: Write requested block with block num to Image Block Char

note right of Target
Write block to flash
end note
end

...Repeat above until all blocks are sent...

Target -> Target: Validate Received Image
alt Image fails post download checks

Distributor <- Target: Notification on Ext Ctrl Char: FAILURE_CODE
note over Distributor, Target
  OAD process terminates in the case of rejected image, never jump to BIM
end note
else Image passes post download checks
Distributor <- Target: Notification on Ext Ctrl Char: OAD_SUCCESS
Distributor -> Target: Enable Image Ext Ctrl Command
Distributor <- Target: Enable Image Ext Ctrl Command Rsp
end

note right of Target
Reboot device (jump to bim)
end note

note over Distributor, Target
  Supervision Timeout
end note

@enduml

Figure 88. Sequence diagram for OAD process

OAD Service (0xFFC0)

The OAD service is responsible for accepting/rejecting an OAD interaction based on image header criteria, storing the image in its appropriate location, and causing a device jump to the newly downloaded user application if the download is successful so that the downloaded application image can be run by the BIM.

A screenshot of BTool displaying the OAD service is shown below:

../_images/image3.png

Figure 89. OAD Service Overview

The OAD service is a primary service with three characteristics. The characteristics of the OAD service, their UUIDs, and descriptions are listed in Figure 89.

Table 14. OAD Service Description.
UUID Name Description
0xFFC0 OAD Service OAD service declaration
0xFFC1 Image Identify Used to send image image header over the air so that the OAD target device can determine if it should accept or reject the proposed image
0xFFC2 Image Block Actual block of image data along with offset into the image.
0xFFC5 OAD Control Controls various aspects of OAD process

The primary method for sending data from the OAD distributor to the OAD target is the GATT writes with no response message with the exception of the image identify message. This reduces code size and increases data throughput as much as possible. Using GATT Notifications would require adding the GATT_ClientInit() call. However, in a noisy or otherwise poor RF-environment, the “write with no response” GATT message may not be sufficient to successfully transmit an entire image and software driven timeouts and retries may need to be added.

The primary method for sending data from the OAD target to the OAD distributor is GATT notifications since the GATT_Client will have already been initialized.

Note

Both GATT notifications and GATT write without response are non-acknowledged message types. To ensure reliability, it is recommended to limit OAD payload transfers to one procedure per connection event.

You can refer to the OAD Types Overview for an overview of the OAD verification and image download process.

OAD Image Identify (0xFFC1)

The Image Identify characteristic is used to exchange image header information between OAD distributor and target. The OAD process begins when the OAD distributor sends the image header information of the proposed OAD image to the target. The target will determine whether or not the proposed image should be downloaded based on the following fields from the image header for the candidate image. Note that a GATT long write was selected for this procedure becasue the entire image ID message will not fit in a single write no response packet for MTU < 25.

Image Identify Payload (fields must be in the following order):
  • OAD Image Identification Value
  • BIM Version
  • Image Header Version
  • Image Information
  • Image Length
  • Software Version

See OAD Image Header for more information about each field.

“01:00” shall be written to the CCCD of this characteristic so that notification for image header rejection is enabled.

If the target accepts the image it will continue the OAD process as seen in OAD Application. The successful image identify will be notified with response code ‘SUCCESS’. Otherwise the target returns the error code. The “01:00” shall be written to the CCCD of this characteristic to enable the notification. The error codes are listed in OAD Return Values.

A successful OAD initiation is shown in below:

../_images/image5.png

Figure 90. Successful OAD Initiation Sniffer Capture

OAD Image Block Characteristic (0xFFC2)

The OAD Image Block characteristic is used to request and transfer a block of data of an OAD Image. “01:00” shall be written to the CCCD of this characteristic to enable the notification for block write. The target requests the next block of the image by sending a GATT notification to the OAD distributor with the requested block number from the OAD Control Point characteristic. The OAD distributor will respond (GATT write, no response) with the block number and the OAD image block. The image block contains the actual binary data from the OAD image offset by the block number multiplied by the size of a block. The OAD distributor shall get the block size from target device by issuing the ‘Get OAD Block Size command’ to the OAD Control Point characteristic described in OAD Control Point Characteristic (0xFFC5).

Figure 91. shows a block request/response sniffer capture.

../_images/image6.png

Figure 91. Block Request/Response Sniffer Capture

In Figure 91. above, the Image Block Write Char Response is shown in gray (0x12), status of last block is shown in teal (0x00 = “SUCCESS”), block number field is 4 bytes (little endian) and highlighted in red. The OAD image block highlighted in purple.

OAD Control Point Characteristic (0xFFC5)

The OAD control characteristic is written with the intent of extending the TI OAD Profile by adding a characteristic that can handle multiple commands. Commands are sent unidirectionally from the OAD Distributor application to the target using GATT Write No Response. The target will send command status and return values back to the OAD distributor using GATT Notifications. If the target doesn’t support a command it shall respond with OAD_EXT_NOT_SUPPORTED, sent as a single byte notification on the OAD Control Char with value 0xFF. 0xFF is defined as a reserved command ID. If target receives any of the control commands without receiving ‘Image Identify’ it will return ‘OAD_AUTH_FAIL’.

Below is the list of commands that are supported by the OAD Control Point Characteristic:

Table 15. OAD Control Characteristic Supported Commands.
Description CMD_ID LEN Payload
Get OAD Block Size Command 0x01 0 None
Get OAD Block Size Response 0x01 3 OAD_BLOCK_SIZE
Set Image Count Command 0x02 1 Number of images to be downloaded
Set Image Count Response 0x02 2

Byte 0: Command ID (0x02)

Byte 1: Return Status

Start OAD Process Command 0x03 0 None
Start OAD Process Response 0x03 5

Byte 0: Command ID (0x03)

Byte 1-3: Block Number

Enable OAD Image Command 0x04 0/4

LEN = 0: none

LEN = 4: Image type and image number of image to be downloaded

Enable OAD Image Response 0x04 2

Byte 0: Command ID (0x04)

Byte 1: Return Status

Cancel OAD Command 0x05 0 None
Cancel OAD Response 0x05 2

Byte 0: Command ID (0x05)

Byte 1: Return Status

Disable OAD Image Block Write Command 0x06 0 None
Disable OAD Image Block Write Response 0x06 2

Byte 0: Command ID (0x06)

Byte 1: Return Status

Get Software Version Command 0x07 0 None
Get Software Version Response 0x07 5

Byte 0: Command ID (0x07)

Byte 1-4: Software Version of currently running image

Get OAD Image Status Command 0x08 0 None
Get OAD Image Status Response 0x08 2

Byte 0: Command ID (0x08)

Byte 1: Return Status

Get Profile Version Command 0x09 0 None
Get Profile Version Response 0x09 2

Byte 0: Command ID (0x09)

Byte 1: Version of OAD profile supported by target

Get Device Type Command 0x10 0 None
Get Device Type Response 0x10 5

Byte 0: Command ID (0x10)

Byte 1-4: Value of Device ID register

Image Block Write Char Response 0x12 6

Byte 0: Command ID (0x12)

Byte 1: Status of the previous block received

Byte 2-5: Block number

Erase All Bonds Request 0x13 0 None
Erase All Bonds Response 0x13 2

Byte 0: Command ID (0x13)

Byte 1: Return status

Get OAD Block Size CMD/RSP

The Get OAD block size command is used to return the active OAD block size. The OAD block size is always set by the target (CC26xx) device based on the negotiated MTU size. For optimal throughput, the distributor shall perform an MTU exchange and wait for the exchange to complete before issuing this command.

The block size is returned in the Get OAD Block Size RSP as a 16-bit value.

See OAD Block Size Rules for restrictions on block size.

Set Image Count CMD/RSP

The off-chip OAD solution can be used to download more than one image in one OAD session. The ‘OAD Image Count’ control command will be used to set the number of OAD images to be downloaded. In the earlier version of the OAD profile, ‘OAD Image Count’ characteristic; was used to serve this purpose. This command is not valid for on-chip OAD and will be ignored if received. Because of flash size limitation, on-chip OAD only supports one image download per session. The default value of the image count is ‘1’.

Start OAD CMD/RSP

After receiving the successful ‘Image Identify’ response from the target device, the OAD Distributor can start the OAD by issuing the ‘Start OAD’ command.

Enable OAD Image CMD/RSP

As mentioned earlier, off-chip upgrade can download multiple images. The distributor can select the image to that needs to be enabled using this control command. After successfully downloading the new image, the OAD Distributor can select one of the downloaded images to be enabled by issuing the ‘Enable OAD Image’ command at OAD control point. The command either have payload bytes, indicating the image ID,( and optionally image number and wireless tech type, if supported) it wants to enable or no payload at all. The format of the payload is shown in table 11. By default, the command will have no payload, and the target device will enable the last downloaded image. The control point will send the two-byte(command ID + return status) response notification indicating success or fail reason.

Cancel OAD CMD/RSP

The OAD Distributor can cancel the image download any point during the download process by issuing the ‘Cancel OAD’ command. The control point will send the two-byte(command ID + return status) response notification indicating success or reason of the failure.

Disable OAD Image Block Write CMD/RSP

By the default, OAD target application sends notifications for each ‘Block write’ message by sending notification via ‘OAD control point’ characteristic. This can be overhead for the OAD process overall and can impact the battery life. The distributor application can disable the notifications via this command.

Get Software Version CMD/RSP

Used to return the command ID + 4-byte long software version of the active image.

Get OAD Image Status CMD/RSP

Reports various failures that may occur during the OAD process in one byte long response. Error codes can be see in OAD Return Values

Get Profile Version CMD/RSP

The command will return two-byte(command ID + profile) long OAD profile version supported by the application.

Get Device Type CMD/RSP

The command will return the command ID + 4-byte device ID register.

Image Block Write Char RSP

The OAD target will respond with notification with status and block number of the next requested payload block from the Control Point characteristic. The return status codes are listed in OAD Return Values. If the download of the entire image is complete, the OAD target device will respond with status code OAD_DL_COMPLETE and Block number set to 0xFFFFFFFF to indicate the download completion.

Erase All Bonds REQ/RSP

Target device will erase all bond records from non-volatile memory.

OAD Reset Service (0xFFD0)

The OAD reset service is only used by on-chip OAD solutions. It implements a method for switching/invalidating the currently running image and resetting the device. This must occur because in on-chip solutions the currently running image cannot update itself. More information about the on-chip OAD process will be covered in the on-chip OAD chapter. Figure 92. shows an overview of the OAD reset service and its characteristics. Like the OAD service, the reset service uses the 128 bit TI base UUID with a 16 bit short UUID of 0xFFD0.

../_images/btool_oad_reset_service.png

Figure 92. OAD Reset Service

OAD Start/Reset Characteristic (0xFFD1)

The OAD Start/Reset Characteristic is responsible for starting the OAD process or resetting the target device. The size of the characteristic payload is 1 byte. The OAD Process can be initiated by writing ‘1’ to this characteristic. The target device can be reset by writing ‘0’ to this characteristic.

OAD Return Values

OAD Status Code Value Description
OAD_SUCCESS 0 OAD succeeded
OAD_CRC_ERR 1 The downloaded image’s CRC doesn’t match the one expected from the image header
OAD_FLASH_ERR 2 Flash function failure such as flashOpen/flashRead/flash write/flash erase
OAD_BUFFER_OFL 3 The block number of the received packet doesn’t match the one requested, an overflow has occurred.
OAD_ALREADY_STARTED 4 OAD start command received, while OAD is already is progress
OAD_NOT_STARTED 5 OAD data block received with OAD start process
OAD_DL_NOT_COMPLETE 6 OAD enable command received without complete OAD image download
OAD_NO_RESOURCES 7 Memory allocation fails/ used only for backward compatibility
OAD_IMAGE_TOO_BIG 8 Image is too big
OAD_INCOMPATIBLE_IMAGE 9 Stack and flash boundary mismatch, program entry mismatch
OAD_INVALID_FILE 10 Invalid image ID received
OAD_INCOMPATIBLE_FILE 11 BIM/image header/firmware version mismatch
OAD_AUTH_FAIL 12 Start OAD process / Image Identify message/image payload authentication/validation fail
OAD_EXT_NOT_SUPPORTED 13 Data length extension or OAD control point characteristic not supported
OAD_DL_COMPLETE 14 OAD image payload download complete
OAD_CCCD_NOT_ENABLED 15 Internal (target side) error code used to halt the process if a CCCD has not been enabled
OAD_IMG_ID_TIMEOUT 16 OAD Image ID has been tried too many times and has timed out. Device will disconnect.

OAD Block Size Rules

The distributor device must use the block size returned by ‘Get OAD Block Size RSP’ throughout the OAD process. Once the OAD process starts, the block size must not change. The OAD target device will select the block size as the largest multiple of 4B that fits into the negotiated MTU size. The acceptable range of OAD block sizes is [20, 244].