1 Read this Section First Document Updates 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. Legacy OAD Versions Prior to the BLE-Stack v2.2.0 release, there were three versions of OAD supported by the SDK: 1.
5 Purpose This document describes the process by which a developer can enable a SimpleLink™ Bluetooth® low energy CC2640 wireless MCU project and application to successfully implement the TI OAD Profile to remotely upgrade the image on a CC2640 BLE device, a process further referred to as an Over-the-Air Download (OAD).
7 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 on 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 Downloader: The device responsible for accepting an OAD enabled image from the compiler and transferring it over the air to the OAD target. OAD roles are independent of the GAP role; they are dependent on which device exposes the OAD service.
Field Size (in bytes) Description Cyclic Redundancy Check CRC Shadow Place holder for CRC Version Version Length Length of the image in words* User Identification Start Address The destination address of the image in words* Image Type The type of image to be downloaded State The status of this image Figure 3.
7.3.4 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. For on chip OAD, the convention is that Image A will embed ‘A’, ‘A’, ‘A’, ‘A’ and Image B will embed ‘B’, ‘B’, ‘B’, ‘B’.
7.3.7 Image State The image state is a one byte metadata field that is used only by Off-chip OAD solutions. The state informs the bootloader whether or not the image is ready to run or currently running. This prevents the bootloader from copying the same image from external to internal flash on every boot.
0xFFC4 Image Status Status of current OAD download Figure 6. OAD Service Description 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 data from the target to the downloader.
Figure 7. Reject Notification in Sniffer Capture Alternatively, a successful OAD initiation is shown in Figure 8. Figure 8. Successful OAD Initiation Sniffer Capture 7.4.2 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.
7.4.4 OAD Image Status (0xFFC4) The OAD image status characteristic is used to report various failures that may occur during the OAD process. The downloader may use this information to determine why an OAD failed, so that it may correct for the errors and try again. “01:00” shall be written to the CCCD of this characteristic so that notification for status update is enabled.
Downloader OAD Target Connection Establishment Service Discovery of OAD Service Configure Image Notify Char Configure Image Block Char Write to Image Count Char (optional [1]) Generate metadata Write Metadata to Image Notify Char Validate Metadata Notification with the metadata of the current running image from Image Notify Char (in case verification failed) Notification with the next block index from Image Block Char (the 1...
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 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.
Bootloader Since a running image cannot update itself, both On-chip and Off-chip OAD methods must employ a bootloader. A bootloader 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.
is inserted into the beginning of the Off-chip OAD Image when transferred and is also stored separately in the off-chip flash. Out of box demo (Off-chip OAD) This section will go over the basic steps in building and running the Off-chip OAD simple_peripheral project that comes with the SDK with IAR IDE.
Page 21
device. 4. Press Reset button on the CC2650 LaunchPad and verify device is advertising, default device name should be “SimpleBLEPeripheral” 5. OAD new version of simple_peripheral App image a. Modify cc2650lp_app – FlashOnly_OAD_ExtFlash (for example, change fields in scan response data (scanRspData[])) and build app and generate output hex file from IAR IDE b.
e. Device should reset and run the new image, verify link is terminated in event log as shown in the Event Log pane below: OAD Target 8.3.1 Overview of OAD Target for Off-chip OAD 0x1FFFF 0x7FFFF CCFG Unused 0x7B000 Metadata 3 0x1F000 0x7A000 Metadata 2...
The Off-chip OAD Target has both on-chip flash memory and off-chip flash memory device. The on-chip flash memory contains the Interrupt Vectors, the BLE Stack, 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 contains up to 3 OAD Images and up to 3 Metadatas corresponding to the OAD Images.
Figure 14. Functional Overview of Off-chip BIM Building Off-chip OAD 8.4.1 Building BIM The boot code is separately built, debugged, and programmed via the IAR or CCS IDE. The projects are located at: $BLE_INSTALL$\examples\util\bim_extflash\cc2640\ Choose “FlashOnly_LP” configuration and build. “FlashOnly_ST” configuration is out of scope in this document.
CC2650 LaunchPad platform is the Debugger setting. With IAR, select “TI XDS110 Emulator” in Project→Options→Runtime Checking→Debugger→TI XDS→Setup→Emulator. With CCS, select “Texas Instruments XDS110 USB Debug Probe” in Properties→General→Main→Device→Connection. 8.4.3 Building the Application Image The simple_peripheral project contains a configuration of ‘FlashOnly_OAD_ExtFlash’...
Page 26
III. Under Tools, include cc26xx_app_oad.icf and exclude cc26xx_app.icf. Also exclude ccfg_app_ble.c. Add the OAD profile modules to the PROFILES folder of the workspace. These files are located here: $BLE_INSTALL$/src/profiles/oad/cc26xx 8.4.3.2 Building the Application Image using CCS Using CCS, the Application Image can be built through the following procedure. Select Project→Properties→Build→ARM Compiler→Advanced Options→Predefined Symbols and add the following to Pre-define NAME: FEATURE_OAD...
Page 27
Define “NO_ROM=1,OAD_IMG_E=1" in Project→Properties→Build→XDCtools→Advanced Options as shown below: III. Add the OAD profile modules to the PROFILES folder of the workspace. Use cc26xx_ble_app_oad.cmd as a linker command file instead of cc26xx_ble_app.cmd (Right-click on the file →Exclude from Build). These files are located here: $BLE_INSTALL$/src/profiles/oad/cc26xx...
Considerations for Off-chip OAD 8.5.1 Adjusting Off-chip Flash Memory Layout The Off-chip OAD described in this document is based on the assumption that it is running on CC2650 LaunchPad hardware where 1MB off-chip flash memory is equipped. If the size of the off-chip flash is different, there may be a need of changing the layout of the off-chip flash.
Out of box demo This section will go over the basic steps in building and running the On-chip OAD simple_peripheral project that comes with the SDK. Software requirements BLE-Stack SDK v2.2+ Python 2.7.x (v2.7.10 or higher) Flash Programmer 2 ...
Page 30
c. Go to Options -> GAP settings and click on Apply to enable fast connection interval 4. Build Image B a. Open up simple_peripheral project in IAR found in $BLE_INSTALL$\examples\cc2650lp\simple_peripheral\iar and choose the FlashOnly_OAD_ImgB configuration and build the project b. In BLE Device Monitor, open up OAD Programming tab (File -> Program (OAD)). Add the hex image from previous step c.
OAD Target 9.3.1 Overview of OAD Target for On-chip OAD The flash memory of OAD Target for On-chip OAD contains the Interrupt Vectors, RCFG, the permanently resident OAD Target App which is also called Image A, the Image B which is initially empty and the place holder for the downloaded OAD Image, the BLE stack, the NV Storage Area, the BIM and the CCFG as shown in Figure 15...
during a power down would break the device. The advantage of a permanently resident Image A whose sole purpose is to implement the BLE Stack and OAD Profile is that it increases the amount of available flash for Image B. The developer of a custom Image B does not have to include the OAD Profile implementation.
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.
9.4.3 Building the OAD Target Application The OAD Target is the permanently resident application image designed to perform OAD of an image into the Image B area. The project is located at $BLE_INSTALL$\examples\cc2650lp\oad_target\iar”. For simplicity, the OAD Target starts in the first flash page following its RCFG. In the BIM functional design ), the OAD Target app is Image A so that by default the downloaded Image B always runs, if a Figure 16 valid instance exists.
Page 35
unusable. The example project for building an Image B included in simple_peripheral workspace as ‘FlashOnly_OAD_ImgB’ configuration can be reproduced through following procedures. The procedures can be applied to convert any existing application to downloadable On-chip OAD Image in IAR. Select Project→Options→C/C++ Compiler→Preprocessor→Defined symbols and add the following new definitions: FEATURE_OAD FEATURE_OAD_ONCHIP...
Page 36
Verify in Linker -> Extra Options, the correct iar_boundary.xcl file is included: Select Project→Options→Linker→Config. Paste the following line to ‘Linker configuration file’: $SRC_EX$/common/cc26xx/iar/cc26xx_app_oad.icf And add the following symbol to ‘Configuration file symbol definitions’: FLASH_ONLY_BUILD=1 III. Setup the Linker for an image’s flash and RAM usage. By default the linker guarantees 10 flash pages, or 40KB, to the OAD image starting at 0x9000 to Image B.
Page 37
Select Project→Options→Linker→Checksum to configure a CRC16 calculation over the application image. Make sure that the start address does not include the CRC and CRC Shadow locations and that the checksum ends at the last address of the specified image region of the OAD Target.
Considerations for On-chip OAD 9.5.1 Adjusting Stack and Application Sizes By default, 40kB is available for Image B because the BIM, the flash interrupt vectors and the OAD Target App occupy 40kB, the BLE protocol stack takes 48kB in the 128kB on-chip flash as shown in Figure .
NOTE: To build the hex file, make sure Python is installed and added to your system path environment variables. 10.2 TI OAD Image Tool (Python) In order to accelerate the process of converting the compiler’s hex file output to an OAD ready binary file with embedded metadata, TI has created a Python based OAD image tool.
Argument Acceptable input Description None Display the help menu --help {onchip, offchip} Whether the generated image is --oadtype for on chip or off chip OAD {app, stack, np, production} The type of image to be --imtype generated. This argument is used to set the metadata and also enforce some imgType based rules...
Figure 19. OAD Image Tool Output 10.2.4 Building a Production Image The tool supports two types of production images depending on how your application will be supporting OAD; On-Chip or Off-Chip. As previously described, On-Chip will require metadata of the image that will be initially flashed onto the device.
Figure 20. OnChip OAD Production Image Example invocation. 10.2.4.2 Off-Chip OAD Production Image Example Usage Off-Chip OAD’s Production image is simply a hex merge of BIM for External Flash + Initial Application Image + Initial Stack Image. Once all the hex files are correctly generated – invoke the TI OAD Image Tool with: <python>...
10.2.5 Automating the script Once the script is installed, it is possible to automate the OAD file generation for rapid testing. This can be accomplished by hooking the script into the post build steps of your tool chain. Instructions for IAR/CCS can be found below.
Figure 23. CCS Post-build step 10.3 RTOS RCFG Section In order to save space, the CC26xx contains portions of the TI-RTOS kernel in its ROM image. These ROM functions have dependencies on a data structure called the RCFG within flash page 0 of internal flash. The RCFG section is essentially a table of function pointers (and some other kernel data) that allows the kernel ROM functions to access certain data structures in the internal flash memory.
Solutions – Verify that the OAD Downloader supports the TI OAD Profile as a GATT Client Verify that the OAD Downloader is sending the correct image with updated meta data Verify that the OAD Target supports the TI OAD Profile as a GATT Server ...
11.7 OAD_TARGET’s Merge.bat Reports Data Overlapped Utilize the TI OAD Image Tool with the hex files. Verify Linker configurations are correct. 11.8 Individually Flashing Hex Files for On-Chip OAD - App doesn’t work! This is known issue with the flash tools – the issue is due to the tools being designed to work on pages instead of on words.