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

Figure 185. Sequence diagram for OAD process

Note

If OAD_BLE_SECURITY is defined in the user / persistent (for onchip OAD) application project, The OAD distributor will be forced to be paired with the OAD target in order for the OAD to happen. (See ‘Pairing’ in GAP Bond Manager and LE Secure Connections)

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:

Figure 186. 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 186.

Table 34. 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 because 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
• (Optional) Security Header + Security payload

The Security Header and payload are defined as:

• Security Version
• Timestamp
• Signer information
• Signature

The fields of the security header are described in more detail in Security Information Segment. If using a non secure application/BIM configuration the security header/segment will not be sent.

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:

Figure 187. 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 188. shows a block request/response sniffer capture.

Figure 188. Block Request/Response Sniffer Capture

In Figure 188. 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 35. 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 189. 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.

Figure 189. 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 can vary between 1 byte and many depending on if security is enabled.

The reset command contains at minimum a 1 byte command as described below:

• 0x01: Start OAD process, reset device, and boot into persistent app
• 0x00: Reset device, and boot into user application

The command is followed by a security payload as described below in secure configurations. In non secure configurations, the security payload is absent.

The security payload is identical to the payload that is described in OAD Image Identify (0xFFC1). If the security payload is present the device will only reset if the command is from a known peer. Secure versions of the application/BIM require that the security is present.

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].