Over the Air Download (OAD)¶

Document Updates/Errata¶

This document is constantly being improved. For the best user experience, please ensure that you are using the latest version. Newer revisions will be posted online on the OAD User’s Guide wiki page.

OAD Types¶

There are two methods of implementing an over the air download update: On-chip and Off-chip. The key difference between the two methods is where the downloaded image is to be stored during the OAD process. During on-chip OAD, the downloaded image is written to internal flash, allowing for a single chip OAD solution. Off-Chip OAD stores the downloaded image in an external flash part, requiring a two chip OAD solution. Figure 74. shows a comparison of different OAD methods. Each type of OAD has associated trade offs and benefits which will be discussed in their respective sections. Despite their differences, both OAD methods share the same over the air profile and metadata vector described in this section

Figure 74. OAD Types Overview

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:

• OAD Target
• OAD Downloader

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 behavior of the BIM is dependent upon the selected OAD type and further described in the respective off-chip and on-chip sections below

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 75. 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).

Figure 75. OAD Downloader and Target

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. The following sections will describe how each field is used specifically for On-chip and Off-chip OAD.

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 18. below shows a description of the metadata vector.

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:

Figure 76. OAD Service Overview

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

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

For a message sequence chart describing the OAD process in terms OAD service messages exchanged between the target and OAD Downloader please see Figure 81..

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

The conditions under which an OAD is accepted vary slightly between the on and off-chip methods. Please see OADTarget_validateNewImage() in oad_target_external_flash.c for off-chip OAD and oad_target_internal_flash.c for on-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.

Figure 77. Reject Notification in Sniffer Capture

Alternatively, a successful OAD initiation is shown in below:

Figure 78. Successful OAD Initiation Sniffer Capture

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

Figure 79. Block Request/Response Sniffer Capture

In Figure 79. 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 Reset Service (0xFFD0)¶

The OAD reset service is only used by on-chip OAD solutions. It implements a method for 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 80. shows an overview of the OAD reset service and it’s characteristic. Like the OAD service, the reset service uses the 128 bit TI base UUID with a 16 bit short UUID of 0xFFD0.

Figure 80. OAD Reset Service

OAD Process¶

This Profile has been designed to provide a simple and customizable OAD Profile for the customer. In its most rudimentary 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 Downloader and OAD Target perform Client role and Server role respectively.

Boot Image Manager (BIM)¶

Since a running image cannot update itself, both On-chip and Off-chip 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’s implementation varies slightly for On-chip and Off-chip OAD solutions, thus there is a separate BIM project for each.

• bim_oad_onchip See BIM for On-chip OAD
• 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.

Supported Stack Image Types¶

Off-chip OAD supports the split image and stack library build configurations. This means that the user can update both the application and stack during the same OAD session. Stack and stack_library image types are supported by off-chip OAD, see the following sections for an explanation of the merits of each.

For more information about the stack image types (stack, stack_library) please. see Protocol Stack Build Configurations.

Constraints and Requirements for Off-chip OAD¶

In order to perform off-chip OAD the target system must contain have:

• An external storage device such as serial flash memory with at least 128kB of space. Support of multiple OAD images requires n * 128kB + (n * EXT_FL_PAGE_SIZE ) of external memory storage. Where n is the number of images to be stored in external flash. n must be >= 1.
• Free GPIO pins to interface to the external memory (i.e. 4 wires for SPI)
• Enough free code space to reserve the entire contents of pg 31 (4kB) for BIM

Off-chip OAD Memory layout¶

The memory maps for both internal and external flash are detailed below.

Figure 82. Off-Chip OAD Memory Layout

Off-chip OAD applications use the both internal flash memory and an off-chip flash memory device. The internal flash memory contains the Interrupt Vectors, the Application where OAD Profile is embedded, the BLE stack image, the NV Storage Area, the BIM and the CCFG.

The off-chip flash memory on the CC2640R2 Launchpad contains up to 3 OAD Images and up to 3 metadata vectors corresponding to the OAD Images. The memory map layout of the external flash part is defined in ext_flash_layout.h. The size of each OAD Image placeholder is 128kB. The memory partition of the application for Off-chip OAD is depicted in Figure 82.. Each OAD image, either App only or App+Stack, must support OAD Profile so that further OAD is enabled after it is downloaded to the off-chip memory, copied to the on-chip memory, and executed.

The sectors in Figure 82. in red are designed to be permanently resident on the device. The BIM and CCFG are not intended to be upgraded via OAD. The OAD design was selected this way so that a failure during the OAD process does not yield a bricked device.

BIM for Off-chip OAD¶

The OAD solution requires that permanently resident boot code, the BIM, exists in order to provide a fail-safe mechanism for determining whether to run the existing application image or to copy a new image or images from off-chip flash to internal flash (code) memory. It is assumed that a valid image exists either in off-chip flash ready to be copied or already placed in on-chip flash at any given time. Given this assumption, the initial image placed in internal flash which does not exist in external flash will have invalid external image metadata, and so the BIM will choose to jump to the existing image’s entry point.

At startup, BIM checks if the application image metadata in off-chip flash has a status indicating that the image is to be copied to the on-chip flash. If the status is 0xFF, copies the image to internal flash and performs CRC validations. If any other status value is found the image will not be verified or copied to internal flash.

If the status field indicates that the image is ready for copying then the CRC validation will be performed as described below:

If a 2 byte value is found that is neither 0x0000 nor 0xFFFF, but a 0xFFFF shadow checksum is found, the BIM computes the CRC over the image. Image length is determined by the metadata that is also stored contiguous with the CRC in on-chip flash that was copied over during the original write of the image from the off-chip flash.

If off-chip flash contains an image to be copied to internal flash, but this image is undesirable, the BIM can be programmed with symbol NO_COPY to skip image checking and jump directly into the image already placed in internal flash; at which point the on-chip flash image could invalidate the bad image’s metadata or OAD a new image in its place. BIM will not be able to load any new images while NO_COPY is defined in the build.

BIM is only responsible for making an application image failsafe upon entry. BIM has exactly one entrance to the application image.

The BIM occupies the last flash page with CCFG and uses the interrupt vectors at the start of flash where the Reset Interrupt Vector calls the BIM startup routine to ensure its control of the system upon a device reset.

Figure 83. Functional Overview of Off-chip BIM

Out of the Box Demo (Off-Chip App Only OAD)¶

The SimpleLink CC2640R2 SDK includes demo projects that are setup to use OAD in advance. These build configurations may be flashed onto the device out of the box. All out of the box demos use BTool as the OAD Downloader. Please see OAD Topology Overview for more information. Ensure that BTool is setup correctly first. See BTool Setup for steps on how to do so. The steps listed below assume that a CC2640R2 Launchpad is being used. Additional steps may be required for custom hardware.

Furthermore, the steps in this section are referring to the OAD Target device, the images referenced below should be flashed onto that device.

Add Off-chip OAD to an existing project¶

1. Use bim_oad_offchip project, as is. No change is required.

2. Add OAD profile code to the application project:

   • The required files can be found in \source\ti\blestack\profiles\oad\cc26xx
     • oad.c
     • oad.h
     • oad_target.h
     • oad_target_external_flash.c

3. Add External Flash middleware to application project

   • oad_target_external_flash.c relies on the ExtFlash module from the middleware folder \source\ti\mw\extflash. Add these files to the application project.
     • ExtFlash.c
     • ExtFlash.h

4. Add the necessary include paths to the project:

   • The OAD profile code can be found at \source\ti\blestack\profiles\oad\cc26xx

5. Use the proper off-chip OAD linker file and configure it properly.

   • IAR projects should use:

     cc26xx_app_oad.icf for App Only, App + Stack

   • CCS projects should use:

     cc26xx_app_oad.cmd for App Only, App + Stack, Library

   For information on how to modify an existing linker command file for OAD see Generating Linker Command File for OAD Off-chip.

6. Add the following preprocessor defines to your application:

   • FEATURE_OAD
   • HAL_IMAGE_E

7. Add necessary code to your high level application file to include OAD.

   • Add the following defines to your application file (i.e. simple_peripheral)

     #include "oad_target.h"
     #include "oad.h"
     // ...
     #define OAD_PACKET_SIZE                       ((OAD_BLOCK_SIZE) + 2)
     // ...
     #define SBP_QUEUE_PING_EVT                    Event_Id_02
     
     #define SBP_ALL_EVENTS                        (SBP_ICALL_EVT        | \
                                                    SBP_QUEUE_EVT        | \
                                                    SBP_PERIODIC_EVT     | \
                                                    SBP_CONN_EVT_END_EVT | \
                                                    SBP_QUEUE_PING_EVT)
     

   • Add the following TI-RTOS Queue structures in your application:

     // Event data from OAD profile.
     static Queue_Struct oadQ;
     static Queue_Handle hOadQ;
     

   • Add a callback to your application

     void SimpleBLEPeripheral_processOadWriteCB(uint8_t event, uint16_t connHandle,
                                                uint8_t *pData);\
     // ...
     static oadTargetCBs_t simpleBLEPeripheral_oadCBs =
     {
       SimpleBLEPeripheral_processOadWriteCB // Write Callback.
     };
     

   • Register the OAD service, initialize Queues.

     VOID OAD_addService();                 // OAD Profile
     OAD_register((oadTargetCBs_t *)&simpleBLEPeripheral_oadCBs);
     hOadQ = Util_constructQueue(&oadQ);
     

   • Add the OAD Queue processing code to your application

     if (events & SBP_QUEUE_PING_EVT)
     {
       while (!Queue_empty(hOadQ))
       {
         oadTargetWrite_t *oadWriteEvt = Queue_get(hOadQ);
     
         // Identify new image.
         if (oadWriteEvt->event == OAD_WRITE_IDENTIFY_REQ)
         {
           OAD_imgIdentifyWrite(oadWriteEvt->connHandle, oadWriteEvt->pData);
         }
         // Write a next block request.
         else if (oadWriteEvt->event == OAD_WRITE_BLOCK_REQ)
         {
           OAD_imgBlockWrite(oadWriteEvt->connHandle, oadWriteEvt->pData);
         }
     
         // Free buffer.
         ICall_free(oadWriteEvt);
       }
     }
     

   • Add an application layer OAD callback

     void SimpleBLEPeripheral_processOadWriteCB(uint8_t event, uint16_t connHandle,
                                                uint8_t *pData)
     {
       oadTargetWrite_t *oadWriteEvt = ICall_malloc( sizeof(oadTargetWrite_t) + \
                                                  sizeof(uint8_t) * OAD_PACKET_SIZE);
     
       if ( oadWriteEvt != NULL )
       {
         oadWriteEvt->event = event;
         oadWriteEvt->connHandle = connHandle;
     
         oadWriteEvt->pData = (uint8_t *)(&oadWriteEvt->pData + 1);
         memcpy(oadWriteEvt->pData, pData, OAD_PACKET_SIZE);
     
         Queue_put(hOadQ, (Queue_Elem *)oadWriteEvt);
     
         // Post the application's event.  For OAD, no event flag is used.
         Event_post(syncEvent, SBP_QUEUE_PING_EVT);
       }
     }
     

8. Add the necessary arguments to your configuro script to relocate your app’s reset vector address.

   • Add OAD_IMG_E=1 to your –cfgArgs. See Using a custom reset vector address for your application for more information.

9. [Optional] On custom hardware, you may need to change the pinout of the external flash part. This can be done in two steps:

   • First, change the application layer code.

     • The application interfaces to the external SPI flash via ExtFlash.c

     • By default, the ExtFlash module uses Board_SPI0, this can be changed to Board_SPI0

       Listing 84. ExtFlash.c interface to SPI¶

       /* Attempt to open SPI. */
       spiHandle = SPI_open(Board_SPI0, &spiParams);
       

     • The pins used by the Board_SPIX group can be set in the board file, i.e. CC2640R2_LAUNCHXL.c

       Listing 85. CC2640R2_LAUNCHXL.c SPI1 Pins¶

       .mosiPin            = CC2640R2_LAUNCHXL_SPI1_MOSI,
       .misoPin            = CC2640R2_LAUNCHXL_SPI1_MISO,
       .clkPin             = CC2640R2_LAUNCHXL_SPI1_CLK,
       .csnPin             = CC2640R2_LAUNCHXL_SPI1_CSN
       

     • The defines above can be set in CC2640R2_LAUNCHXL.h

   • Second, change the pins that the BIM uses to access the SPI flash. This can be done in the bim_oad_offchip project. Since BIM is a bare metal program (no-RTOS). It doesn’t use the TI-RTOS SPI driver like the application does. BIM SPI pins are set in \examples\rtos\CC2640R2_LAUNCHXL\blestack\bim_oad_offchip\src\bsp.h

     Listing 86. Off-chip OAD BIM interface to SPI¶

     // Board external flash defines
     #define BSP_IOID_FLASH_CS       IOID_20
     #define BSP_SPI_MOSI            IOID_9
     #define BSP_SPI_MISO            IOID_8
     #define BSP_SPI_CLK_FLASH       IOID_10
     

10. [Optional] For App+Stack or Library OAD Images, trim SNV/Unused Space

    Library and App+Stack can generate large OAD images especially if the end application utilizes SNV. (App + Stack will always be large)

    SNV can be preserved on the OAD Target device by applying the ‘-r’ command to the OAD Image Tool. The ‘-r’ command will limit the output image to within the range specified. Page alignment must still be preserved, so some 0xFFs may be kept in the image.

    For example, to preserve page 31, or a 1 page SNV: the -r :1e000 command can be appended to the post build step:

    Listing 87. Modified IAR post-build step to remove SNV from an App+Stack OAD image¶

    "$TOOLS_BLE$\oad\oad_image_tool.exe" "$PROJ_DIR$\FlashROM_OAD_Offchip\Exe\simple_peripheral_cc2640r2lp_app.hex" "$PROJ_DIR$\..\stack\FlashROM\Exe\simple_peripheral_cc2640r2lp_stack.hex" -t offchip -i app --imgVer 0 -ob "$PROJ_DIR$\FlashROM_OAD_Offchip\Exe\simple_peripheral_cc2640r2lp_app_oad.bin" -m 0x0000 -r :0x1e000
    

    The result will be am OAD image file that will not overwrite a target’s 31st page (if used for SNV, adjust as necessary for 2 SNV pages)

    Lastly, for Library builds, there will be 0xFFs between the end of the Application + Stack merged section and the SNV. If SNV is being preserved then it is safe to also trim the OAD image to the nearest page.

    For example, if a Library OAD image is produced, only takes up the first 15 pages and the SNV does not need to preserved, then append -r :0x0F000 to the post-build step:

    Listing 88. Modified IAR post-build step to remove SNV and 0xFFs from a Library OAD image.¶

    "$TOOLS_BLE$\oad\oad_image_tool.exe" "$PROJ_DIR$\FlashROM_StackLibrary_OAD_Offchip\Exe\hid_adv_remote_cc2640r2rc_app.hex" -t offchip -i app --imgVer 0 -ob "$PROJ_DIR$\FlashROM_StackLibrary_OAD_Offchip\Exe\hid_adv_remote_cc2640r2rc_app.bin" -m 0x0000 -r :0xF000
    

Constraints and Requirements for On-chip OAD¶

In order to perform on-chip OAD the target system meet the following requirements:

• Enough free flash space to fit the user application within the 16 pages of internal flash allocated to it.
• The application and stack must use the split image ICall (FlashROM) architecture to ensure that the OAD Target App, customer Image B application and BLE protocol stack do not contain overlapping flash pages

The OAD Image to be downloaded is, by default, allocated 16 flash pages. Because page 1 cannot be updated, an application must include its own TI-RTOS instance in flash without dependence on the TI-RTOS ROM implementation. This image also shares the CCFG referenced in the above paragraph. For reliability reasons, it is not possible to update the CCFG parameters via an OAD.

The OAD Target App and the OAD image B share the same RAM range as only one image is executed. The OAD Image B must be a complete application image, capable of running independently of the permanently resident OAD Target App.

The BLE protocol stack defaults to a range of 8 flash pages, ranging from address 0x17000 to 0x1EFFF and one SNV page is used by default. If the OAD Image is too large to fit in its allocated space, consider removing some features of the BLE stack to reduce its size.

The OAD Target App, or the Image A, and the Image B shall share the same BLE stack image. It is not possible to perform an on-chip OAD of the BLE Stack image.

On-chip OAD deals with four images. The table below shows the corresponding project associated with each image. Furthermore the terms OAD Target Image and Image A are synonymous, they will be used interchangeably in this document.

Image Name	IAR Project	CCS Project
Image A (Target Image)	oad_target/cc2640r2lp_app	oad_target_cc2640r2lp_app
Image B (User Image)	simple_peripheral_oad_onchip/cc2640r2lp_app	simple_peripheral_cc2640r2lp_app_oad_onchip
BLE Protocol Stack image (shared between Image A and B)	oad_target/cc2640r2lp_stack	oad_target_cc2640r2lp_stack
BIM for on-chip OAD	bim_oad_onchip/cc2640r2lp_app	bim_oad_onchip_cc2640r2lp_app

On-Chip OAD Memory layout¶

The memory map for CC2640R2F internal flash in an on-chip OAD configuration is shown below.

Figure 85. On-Chip OAD Memory Layout

BIM for On-chip OAD¶

The OAD solution requires that permanently resident boot code, the BIM, exists in order to provide a fail-safe mechanism for determining (in preferential order) the image which is ready to run. When a valid image is found, the BIM jumps to that image at which point the image takes over execution. Either Image A or Image B must implement the proprietary TI OAD Profile. By default, this is Image A’s role. When an image with the OAD Profile downloads a new image, a system reset can be executed to return to BIM to verify the correctness of the download and begin execution.

Figure 86. Functional Overview of On-chip BIM

As the permanent owner of the flash interrupt vectors, BIM provides a fail-safe mechanism for intercepting the reset vector, putting the hardware into a safe state, and taking the most appropriate action by reading the headers of Image A and Image B.

By default, BIM gives precedence to Image B, as Image A is only expected to be run when a newer instance of Image B is ready to OAD or no valid Image B exists in the internal flash memory. If the preferred image is not ready to run, then the other image is checked. If neither image is ready to run – an unlikely scenario because Image A, the OAD Target App, need not ever be erased – then BIM puts the device into a low power Standby mode. Also by default, a CRC check is not performed on Image A because it is expected that the OAD Target App will be used as a fixed image. The check on Image A will only read the checksum placed by IAR to see if an image exists, it will not calculate the CRC shadow.

In order to verify that an image is valid, a fixed 4-byte area known as the CRC and CRC-shadow will be queried. If the 2-byte CRC16 output calculated at build time matches the 2-byte CRC16 shadow calculated by BIM, then the image is commissioned to run immediately. If the CRC is not zero and not the erased-flash value of 0xFFFF and the CRC-shadow is the erased-flash value of 0xFFFF, then the CRC can be calculated over the entire image (not including this 4-byte area) and the result can be compared to the valid CRC to determine whether the image should be commissioned as ready to run.

Out of the Box Demo (On-Chip OAD)¶

The SimpleLink CC2640R2 SDK includes demo projects that are setup to use OAD in advance. These build configurations may be flashed onto the device out of the box. All out of the box demos use BTool as the OAD Downloader. Please see OAD Topology Overview for more information. Ensure that BTool is setup correctly first. See BTool Setup for steps on how to do so. The steps listed below assume that a CC2640R2 Launchpad is being used. Additional steps may be required for custom hardware.

Furthermore, the steps in this section are referring to the OAD Target device, the images referenced below should be flashed onto that device.

Add On-Chip OAD to an existing project¶

1. Use OAD Target/ ImageA Project, as is. No change is required. This includes:

   • bim_oad_onchip
   • oad_target_cc2640r2lp_stack
   • oad_target_cc2640r2lp_app

2. Add OAD profile code to the application project:

   • The required files can be found in \source\ti\blestack\profiles\oad\cc26xx
     • oad.c
     • oad.h
     • oad_target.h
     • oad_target_internal_flash.c
     • oad_reset_service.c

3. Add the necessary include paths to the project:

   • The OAD profile code can be found at \source\ti\blestack\profiles\oad\cc26xx

4. Add the following defines to your application:

   • IMAGE_INVALIDATE
   • HAL_IMAGE_B

5. Add the OAD Target Stack’s boundary definition See screen shots below.

   • IAR

     

   • CCS

     

6. Use the proper on-chip OAD linker file and configure it properly.

   • IAR projects should use cc26xx_app_oad.icf

     • Pass in the following defines to the linker:

       • CC2650=2
       • FLASH_ONLY_BUILD=2

     • Add the OAD Target Stack’s boundary definition See screen shot below.

       

   • CCS projects should use cc26xx_app_oad_onchip.cmd

     • Pass in the following defines to the linker:
       • R2=1

   • Add the OAD Target Stack’s boundary definition See screenshot below.

     

7. Add necessary code to your high level application file to include the OAD reset service. This service is used to invalidate Image B and jump back to Image A for further upgrades to Image B.

   • Add the following defines to your application file (i.e. simple_peripheral)

     #include "oad_target.h"
     #include "oad.h"
     ...
     

   • Within the application’s init routine, add the OAD reset service.

     Reset_addService();
     

8. Add the necessary arguments to your configuro script to relocate your app’s reset vector address.

   • Add OAD_IMG_B=1 to your –cfgArgs. See Using a custom reset vector address for your application for more information.

General Troubleshooting Guide Prior to BIM¶

There are various places where OAD can fail; use the following steps to determine where the issue is occurring during the interaction:

• Use a BLE Packet Sniffer and Record the OAD Transaction

  This will verify that the profile is implemented correctly and a valid image was transferred over the air.

  • Look for a OAD Initiation

    Notifications from OAD Image Notify should be requested – and the appropriate response from the OAD Target after a GATT Write of the Candidate metadata.

  • Look for OAD Image Status Characteristic

    This will contain the status of the image prior to BIM launching the image.

• Read external/internal flash to ensure CRC Shadow is valid and matches CRC field

  • This will verify that the image was received fully without errors by the OAD Target

    • For Internal, various tools can be used. SmartRF Programmer 2 or using a jtag debugger and connecting to running target and utilizing a memory viewer are possible options.
    • For External, interface another MCU or another serial device to dump out the Flash.

Downloaded OAD Image Isn’t Starting¶

If the application doesn’t start running the downloaded firmware after a successful download, it’s a BIM issue.

Depending on OAD type, on-chip or off-chip, refer to sections BIM for On-chip OAD or BIM for Off-chip OAD respectively. Utilize how BIM operates and a debugger to find where the issue is occurring.

Should External Flash be Used During OAD?¶

No, External flash should not be utilized while OAD Profile is active; the Profile is designed to have uninterrupted exclusive access to Flash, in Off-Chip configurations.

Building Super Hex Files¶

To build merged hexfiles, there are various methods to do this. One option is to utilize the TI OAD Image Tool (Python). See Generating a Production Image for OAD for more information. Hex files can be converted to binary using any tool that supports the Intel extended hex format.

Mobile Application Can’t Perform OAD¶

Ensure the latest version of the Application is downloaded from your Phone’s Application Store and try again.

If problem persists, please post your Phone’s Model and OS Version number along with details to reproduce your setup on our Support Forums. Utilize BTool and verify that the OAD works correctly.

OAD Target device doesn’t reset after successful OAD¶

IThis usually occurs when the JTAG debugger (e.g., XDS110) is connected. Disconnect and remove the debugger prior to performing OAD.

This issue should not be appearing in field devices, or devices that are powered through a battery or other means.

Can’t connect via BTool After successful OAD¶

• Try resetting the host_test device attached to BTool.
• Close and re-open BTool.
• Verify target is advertising using a mobile app.

OAD Target App Doesn’t Advertise out of the Box¶

Likely the image metadata is not embedded in the image, or there is a corrupted image that is causing problems.

• Perform a forced mass erase using Smart RF Flash Programmer 2
• Follow the steps at Out of the Box Demo (On-Chip OAD), particularly Generating a Production Image for OAD

Generating Linker Command File for OAD Off-chip¶

Understanding of OAD Concept Overview, particularly what are the Linker Responsibilities is recommended.

This section describes how to convert a standard SDK linker command file to be compatible with the TI OAD Ecosystem for both CCS and IAR linkers.

Stack Side Changes for OAD Project¶

Generally, no stack side changes to enable OAD are required. However, if desired, depending on the OAD configuration type, stack side changes may be done in the project.

The configurations that may a stack side change are configurations where the stack image is separate from the application image. In other words, App only and Stack only for Off-chip, and (Img_B) App only for On-chip. No changes on stack project in Library OAD configurations should be done.

One possible change is to page align the stack, such that the entry point is always the same address at the beginning of a page. To force the linker to be page aligned, simply add PAGE_ALIGN=1 to the linker defines on the stack project.

In the case of a Stack only OAD configuration, the stack OAD project can be page aligned to allow for the additional features (up to the boundary). As long as the entry point is the same, the application will function normally.

Generating Metadata Vector for OAD Image¶

The OAD_Image_Tool is designed to generate a metadata vector and insert it into a given image, to produce an OAD ready image. An OAD ready image can be a hex file or a binary that contains metadata for the target to interpret.

The OAD_Image_Tool can be found as a Python script or as a binary inside SimpleLink CC2640R2 SDK installation. It is located in BLE Examples Support Files in the Tools folder.

To view usage instructions for the tool, run the Python script or the binary with the -h argument passed in.

For example, to generate an OAD ready application image, invoke the tool with:

1	./oad_image_tool.exe -t offchip -o out.hex -m 0x0000 -i app in.hex

The out.hex file will be an OAD ready image with the metadata to tell the OAD Target that it’s an Application image for Off-chip OAD.

Generating a Production Image for OAD¶

A production image is one that contains the app, stack, and BIM images combined into a single file. Production images are generally used when an OAD enabled device is initially programmed at the manufacturing facility. Production images can also be useful for debugging as all of the information is contained in a single file.

TI has included a Python based OAD_Image_Tool that can perform a variety of operations on OAD ready hex files in the SimpleLink CC2640R2 SDK. It will be used to generate a production OAD image.

Currently, the oad_image_tool is already being invoked as a post build step on oad_target_app, and simple_peripheral builds for on and off-chip OAD.

CCS Update OAD Image Tool Build Step¶

The image below shows how to edit the CCS post build step for the OAD image tool. This menu can be accessed by right clicking the project –> properties.

Figure 92. Update OAD Image Tool Post Build Step CCS

IAR Update OAD Image Tool Build Step¶

The image below shows how to edit the IAR post build step for the OAD image tool. This menu can be accessed by right clicking the project –> options.

Figure 93. Update OAD Image Tool Post Build Step IAR

Using a custom reset vector address for your application¶

The projects within the SimpleLink CC2640R2 SDK will build the TI-RTOS kernel as a pre-build step within the application. This prebuild step is called configuro. During the configuro stage it is possible to relocate your reset vectors. This is required for OAD applications to make room for the metadata vector at the beginning of the image space. For more information about configuro, please see RTSC Configuro Page.

Change Reset Vector Address in IAR¶

IAR treats configuro as a prebuild action. These actions can be found by right clicking the project –> Build Actions –> Pre-build command line. See the image below for more information.

Change Reset Vector Address in CCS¶

CCS has native RTSC/Configuro support built into the project. These actions can be found by right clicking the project –> Build –> XDCtools –> Advanced Options. See the image below for more information.

Changing Application Data to Verify an OAD¶

It can be difficult to verify OAD without making application changes. A quick and easy way to change your application image before sending over the air is to change it’s scan response data.

This way, a successful OAD can be observed via the change in scan response data. See below for steps on how to change this.

• A good test is to change the scan response data as below in simple_peripheral.c

Listing 89. Changing SBP advertisement data¶

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

// GAP - SCAN RSP data (max size = 31 bytes) static uint8_t scanRspData[] = { // complete name 0x14, // length of this data GAP_ADTYPE_LOCAL_NAME_COMPLETE, 'S', 'i', 'm', 'p', 'l', 'e', 'B', 'L', 'E', 'P', 'e', 'r', 'i', 'p', 'h', 'e', 'r', 'a', '2', //... }

Warning

If you change of scan response data you must also change it’s length. See line 5 of the code snippet above.

Using BTool and CC2640R2 Launchpad as an OAD Downloader¶

This section will describe how to use setup and use BTool, to perform an OAD. These steps are independent of OAD type and can be used to perform on-chip or off-chip OAD.