OAD Concept Overview¶
This section aims to explain the major concepts involved in the OAD process from a high level. The concepts here will be expanded upon further in the following sections. Some concepts, such as the Boot Image Manager (BIM), may vary in their implementation details. Wherever possible, the concepts will be covered in this chapter with their implementation details covered in the following chapters.
OAD Types¶
BLE5-Stack only supports off-chip OAD. During off-chip OAD, the candidate image is stored in a low power external flash and loaded into the CC2640R2F internal flash by the BIM.
OAD Topology Overview¶
Two BLE capable devices are required for implementing the OAD custom GATT service. The terms for the devices involved in an OAD exchange are listed below:
The OAD Target is always the device that implements the OAD service GATT server. Typically this is the peripheral device that is being updated. The OAD Target uses a Boot Image Manager (BIM) to facilitate the application of a new firmware update image. The BIM executes on a device reset and determines if a firmware update is to be applied. If no update is being applied, then the BIM will transfer program execution to the main application image.
The OAD Downloader is always the device that implements the OAD service GATT client. Typically this is the central device that is supplying the firmware update image. Figure 79. shows a graphical relationship of the devices required for an OAD transfer. The OAD Downloader can be any compliant BLE device that meets the minimum requirements needed to implement the OAD service (e.g, a smartphone).
All provided TI example applications (BTool, mobile applications, etc.) are implemented such that the OAD Target is a peripheral device, and the OAD Downloader is a central device. Other configurations are outside of the scope of this document.
OAD Image Metadata¶
All firmware images delivered via OAD are in binary format and contain an image metadata header The information in the metadata header is used by the OAD service to determine whether or not an image is acceptable for download or by the BIM to determine which image should be loaded/executed in the main system flash. In order to prevent this information from being calculated multiple times all TI OAD images use a standard 16-byte metadata vector. This metadata vector is embedded at the beginning of the image, occupying the first 16 bytes before the application code firmware content.
This section explains the various fields within the metadata vector and what they mean.
Most metadata checking is done in OADTarget_validateNewImage()
.
TI provides a tool to generate an OAD ready image, which contains a metadata vector called the OAD Image Tool. See Generating Metadata Vector for OAD Image.
Table 16. below shows a description of the metadata vector.
Field | Size (in bytes) | Description |
---|---|---|
CRC | 2 | Cyclic Redundancy Check |
CRC Shadow | 2 | Place holder for CRC |
Version | 2 | Version |
Length | 2 | Length of the image in words* |
UID | 4 | User Identification |
Start Address | 2 | The destination address of the image in words* |
Image Type | 1 | The type of image to be downloaded |
State | 1 | The status of this image |
[*] | These fields are measured in 32-bit words. For example, an image length of 0x100
describes an image that is 1024 bytes in size. This OAD word size is
defined by |
CRC and CRC Shadow¶
The cyclic redundancy check (CRC) is a means to check the integrity of an image. This must be done in two steps. First the CRC must be calculated when the image is generated from the toolchain, this will be stored in the CRC field within the metadata vector.
This initial CRC will be sent over the air via the OAD service (see OAD Service (0xFFC0) section).
Later, once the target has received the OAD image, CRC shadow will be calculated to determine if the image has been corrupted during transfer. The target will re-calculate the CRC of the downloaded image and store the result in the CRC shadow field of the metadata vector.
If the CRC and CRC shadow are equivalent, the target can assume that the image was not corrupted while sending over the air.
The algorithm selected for CRC calculations is the CRC-16-CCITT, it is a 16 bit CRC calculation that has a 99.9984% error detection rate in the worst case. In addition to this CRC, all data transfers in BLE are protected by a CRC on the link layer so the risk of an undetected data corruption is even further reduced.
Version¶
The image version field is used to track revisions of images and ensure
upgrade compatibility. Customers may implement their own versioning
scheme; however, there are additional checks imposed by the TI OAD profile.
See the function OADTarget_validateNewImage()
within
oad_target_external_flash.c
to see
how these version checks are done in Off-chip OAD.
Length¶
The length field is the length of the image in words, where the word
size is defined by EFL_OAD_ADDR_RESOLUTION
for Off-chip OAD. Off-chip OAD customers who
are using different external flash parts may need to modify
EFL_OAD_ADDR_RESOLUTION
to match the word size of their part.
User Identification (UID)¶
This field is un-used by the TI OAD profile, but the hooks are in place for a customer to add their own implementation of verifying images based on UID.
Off-chip images use ‘E’, ‘E’, ‘E’, ‘E’ by default.
Start Address¶
The start address is the first address where the proposed image is to be stored in internal flash. Similar to the length field, this is calculated in words. Off-chip OAD solutions put restrictions on the start address based on image type (more on this in the next section).
Image Type¶
In Off-chip OAD systems with external flash, there are multiple types of images that can be uploaded. These image types include:
- App + Stack
- App only
- Network Processor
- Stack only
Warning
While stack only upgrades are possible with off-chip OAD, the user must be sure that the App/Stack boundary RAM and flash addresses have not changed between the current firmware image and the proposed OAD image. Since there are no runtime checks on the App/Stack boundary, a stack only OAD will overwrite the resident application if the boundary has grown. Users should exercise care when using this option. TI recommends performing a app + stack upgrade when using the off-chip OAD method.
If a boundary address change is required (i.e. stack is growing or shrinking), it is required that a user perform a merged update (App+Stack) to ensure that the OAD image is ready to run.
The supported image types are listed below:
Image Type | Value | Description |
---|---|---|
EFL_OAD_IMG_TYPE_APP | 1 | An application or application + stack merged update |
EFL_OAD_IMG_TYPE_STACK | 2 | A stack only update |
EFL_OAD_IMG_TYPE_NP | 3 |
|
EFL_OAD_IMG_TYPE_FACTORY | 4 | Describes the permanently resident production image that runs on the device before any OTA updates. |
OAD Service (0xFFC0)¶
The OAD service has been designed to provide a simple and customizable implementation for the customer. In its most rudimentary form, this 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 reset if the download is successful so that the downloaded application image is run by the BIM.
A screenshot of BTool displaying the OAD service is shown below:
The OAD service is a primary service with four characteristics. The characteristics of the OAD service, their UUIDs, and descriptions are listed in Figure 80.
Note
The characteristics use the 128-bit TI base UUID of the format F000XXXX-0451-4000-B000-000000000000 where XXXX is their shortened 16bit UUID. For brevity, this document will refer to the characteristics by their 16-bit short UUID.
UUID | Name | Description |
---|---|---|
0xFFC0 | OAD Service | OAD service declaration |
0xFFC1 | Image Identify | Used to send image metadata 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. |
0xFFC3 | Image Count | Number of complete images to be downloaded in the OAD session |
0xFFC4 | Image Status | Status of current OAD download |
The primary method for sending data from the OAD Downloader to the OAD target is the GATT writes with no response message. GATT notifications are the primary method used to send status data from the target to the downloader. This communication scheme was selected to prevent the target device from having to include the GATT client code required in order to receive notifications from the downloader. The OAD Downloader shall register for notifications from any characteristic with a CCCD (by writing 01:00 to the CCCD).
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.
For a message sequence chart describing the OAD process in terms OAD service messages exchanged between the target and OAD Downloader please see Figure 84..
OAD Image Identify (0xFFC1)¶
The Image Identify characteristic is used to exchange image metadata between OAD Downloader and target. The OAD process begins when the OAD Downloader sends the 16 byte metadata of the proposed OAD image to the target. Upon receiving the candidate metadata, the target will do some calculations to determine whether or not the proposed image should be downloaded. “01:00” shall be written to the CCCD of this characteristic so that notification for metadata rejection is enabled.
Note
Please see OADTarget_validateNewImage()
in
oad_target_external_flash.c
or off-chip OAD. These functions
implement the image reject conditions.
If the target accepts the image it will continue the OAD process by sending a notification on the Image Block characteristic requesting the first block. Otherwise the target will reject the image by sending back a portion the currently resident image’s metadata. The reject metadata contains the Image version, and User ID fields. For more information about these fields, please refer to OAD Image Metadata.
A sniffer capture of the image identify characteristic being used to reject a candidate OAD image is shown below. Note that only image version, length, and user ID are contained in the reject notification.
Alternatively, a successful OAD initiation is shown in below:
OAD Image Block Characteristic (0xFFC2)¶
The OAD Image Block characteristic is used to request and transfer a block of the OAD image. “01:00” shall be written to the CCCD of this characteristic so that notification for block request is enabled. The target requests the next block of the image by sending a GATT notification to the OAD Downloader with the requested block number. The OAD Downloader will respond (GATT write no response) with the block number and a 16 byte OAD image block. The image block contains the actual binary data from OAD image offset by the block number. Figure 83. shows a block request/response sniffer capture.
In Figure 83. above, the block number field is 2 bytes (little endian) and highlighted in red. The OAD image block is 16 bytes and highlighted in purple.
OAD Image Count Characteristic (0xFFC3)¶
The OAD Image Count characteristic is used to set the number of OAD images to be downloaded. This is used for only Off-chip OAD and the default value of the characteristic is 1.
OAD Image Status (0xFFC4)¶
The OAD image status characteristic is used to report various failures that may occur during the OAD process. The OAD Downloader may use this information to determine why an OAD failed, so that it may correct for the errors and try again. To enable notifications on this characteristic “01:00” shall be written to the CCCD of this characteristic. There are four OAD status messages that are defined by default. The OAD status codes are listed in the table below:
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 metadata |
OAD_FLASH_ERR | 2 | The external flash cannot be opened |
OAD_BUFFER_OFL | 3 | The block number of the received packet doesn’t match the one requested. An overflow has occurred. |
The customer may extend these values as needed, and use the
OAD_sendStatus()
function to send updates to the downloader.
OAD Process¶
This Profile has been designed to provide a simple and customizable OAD Profile for the customer. In its most rudimentary form, 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 Downloader and OAD Target perform Client role and Server role respectively.
Initiation of the OAD Process¶
After establishing a new connection, updating the connection interval for a faster OAD and enabling notifications of OAD Image Identify and OAD Image Block characteristics on the OAD Target, the OAD Downloader shall write to the Image Identify characteristic of the OAD Target. The message data will be the header retrieved from the OAD Image available for OAD.
Upon receiving the write request to the Image Identify characteristic,
the OAD Target will compare the image available for OAD to its own
running image. OADTarget_validateNewImage()
in the OAD profile is
responsible for determining the acceptance of the new image.
If the OAD Target determines that the image available for OAD is acceptable, the OAD Target will initiate the OAD process by notifying the Image Block Transfer characteristic to the OAD Downloader requesting the first block of the new image. Otherwise, if the OAD Target finds that the new image does not meet its criteria to begin the OAD process, it shall respond by notifying the Image Identify characteristic with its own Image Header data as sign of rejection. In that case, the OAD procedure will end immediately as depicted in Figure 84..
Image Block Transfers¶
The Image Block Transfer characteristic allows the two devices to
request and respond with the OAD image, one block at a time. The image
block size is defined to be 16 bytes – see OAD_BLOCK_SIZE
in
oad.h
. The OAD Target will request an image block from the
OAD Downloader by notifying the OAD Image Block characteristic with the
correct block index. The OAD Downloader shall then respond by writing to
the OAD Image Block characteristic. The message’s data will be the requested
block’s index followed by the corresponding 16-byte block of the image. Whenever
the OAD Target is ready to digest another block of the OAD image, it
will notify the Image Block Transfer characteristic with the index of
the desired image block. The OAD Downloader will then respond.
Completion of the OAD Process¶
After the OAD Target has received the final image block, it will verify that the image is correctly received and stored by calculating the CRC over the stored OAD image.
The OAD Target will then reset so that the bootloader (BIM) can verify and boot the new image downloaded.
The burden of verification is then on the Downloader, which will lose BLE connection to the OAD Target during this verification and instantiation process, to restart scanning and the to reestablish a connection and verify that the new image is indeed running.
Handling Errors During the OAD Process¶
To ensure reliability, any error or faults that occurs during an OAD transfer requires the OAD Downloader to restart the OAD transfer procedure from the beginning. Errors may be reported through the OAD Image Status characteristic if notifications have been enabled
Boot Image Manager (BIM)¶
Since a running image cannot update itself OAD methods must employ a boot image manager (BIM). The BIM is a lightweight section of code that is designed to run every time the device resets, check the validity of newly downloaded images, and if necessary, load the new image into internal flash.
bim_oad_offchip
See BIM for Off-chip OAD
Linker Responsibilities¶
In general, there are a few bare requirements that the linker command file must have to support the TI OAD Profile, TI Tools, and TI BIM (The TI OAD Ecosystem):
- Flash Space for OAD Image Metadata and App Start location
- Preservation of Page 31 (CCFGs + BIM) see Handling Errors During the OAD Process
- Alignment of Interrupt Vector Table see Using a custom reset vector address for your application
These requirements are critical; not just to be supported in the TI OAD Ecosystem but for stability of application as discussed in earlier sections.
The SimpleLink CC2640R2 SDK provides cc26xx_app_oad.cmd
(CCS) and cc26xx_app_oad.icf
(IAR)
linker command files to show these requirements for compatibility with TI OAD
Ecosystem. Example modifications to an existing linker command file to make an
Library OAD off-chip possible is shown in
:ref:sec-generating-library-oad-linker-file
.
Generally, the TI Image Tool will handle page alignment of OAD images, no linker intervention is required. However, if desired, some stack side changes can be done to make the stack entry point page aligned, see Stack Side Changes for OAD Project.