Table of Contents
Introduction
The Over-the-Air Download (OAD) code example is a powerful code example that shows users how to update the firmware on the SNP/SAP over-the-air from a BLE client device. This allows users a flexible method of updating all aspects of the system’s firmware without the need of preloading the device or connecting an external programmer. A CRC check contingency exists within the firmware update flow to minimize the possibility of firmware image corruption during transfer. A custom and open source TI OAD Programmer tool has also been provided with this plugin release to enable users to initiate a firmware update from any Linux/PC/Mac platform.
Hardware Prerequisites
The Over-the-Air Download example requires the standard configuration of an MSP-EXP432P401R LaunchPad (or a MSP-EXP432P4111 LaunchPad) with an attached BOOSTXL-CC2650 BoosterPack or LAUNCHXL-CC2640R2 Launchpad. This hardware configuration is shown in the below image:
Alternatively, the CC2640R2 LaunchPad can be used in lieu of the CC2650 BoosterPack. In this case the CC2640R2 LaunchPad should be stacked on the MSP432 LaunchPad as seen below:
In order to use the TI OAD Programmer tool, a LAUNCHXL-CC2650 is required to act as a BLE client on the PC side. No special hardware modifications need to be made for the CC2650 LaunchPad to communicate with the MSP432/CC2650 setup.
Software Prerequisites
This code example has been tested with the tool and compiler versions listed in the Release Notes. For more information on how to import this project into your IDE workspace and build/run, please refer to the main user’s guide.
Service/Profile Table
Purpose | UUID | Format | Properties | Profile Source |
---|---|---|---|---|
Image Identify | F000FFC1-0451-4000-B000-000000000000 | Buffer | Read/Write/Notify | oad_profile_extended.c |
Image Block Request | F000FFC2-0451-4000-B000-000000000000 | Buffer | Read/Write Without Response | oad_profile_extended.c |
Image Count | F000FFC3-0451-4000-B000-000000000000 | Buffer | Read/Write/Notify | oad_profile_extended.c |
OAD Status | F000FFC4-0451-4000-B000-000000000000 | Buffer | Notify | oad_profile_extended.c |
Control Characteristic | F000FFC5-0451-4000-B000-000000000000 | Buffer | Write Without Response/Notify | oad_profile_extended.c |
Limitations
- Currently no IAR support for example projects
- No secure firmware update supported currently (scoped out for follow-on release)
- TI OAD Programmer requires SNP image must be in Intel hex and SAP image to be in TI-TXT
Usage
This code example contains no functional characteristics with the exception of the services to enable OAD download. Pressing S1 will start advertisement and make the device visible to OAD clients.
TI OAD Programmer Tool
Introduction
The TI OAD Programmer tool is a lightweight application written in Python (and compiled into binaries for Linux/OSX/Windows) that allows the users to wirelessly update BLE applications for the SimpleLink SDK BLE Plugin. This BSD-licensed program is provided under the tools/ti_oad_programmer folder of the plugin release and is fully compatible across Mac/Linux/Windows.
LAUNCHXL-CC2650 Preparation
As stated in the prerequisites, a LAUNCHXL-CC2650 device is required for the TI OAD Programmer. This LaunchPad will act as a proxy between the PC that contains the firmware update and the CC2650/MSP432 device that you want to update. Communication to and from the PC host and CC2650 LaunchPad is performed by sending commands through the back channel serial port on the CC2650 LaunchPad through the “Host Controller Interface” (HCI). HCI is documented in detail in the BLE-STACK for the CC2650 device and is not repeated here. A small block diagram of the OAD programming flow under the TI OAD Programmer tool can be seen below:
To start using the OAD tool the appropriate firmware first needs to be downloaded to the CC2650 LaunchPad. This firmware is responsible for handling host commands from the PC and connecting to the OAD target over BLE. An optimized HEX image of this firmware can be found under the tools/host_test_cc2650lp folder of the plugin installation and is named host_test_cc2650lp.hex.
This application is an optimized derivative of the host_test application that is provided as a part of the BLE-STACK release for CC2650. This hex file needs to be flashed to the CC2650 LaunchPad via the TI SmartRF Flash Programmer 2. How to flash a hex file using the TI SmartRF Flash Programmer 2 is documented in detail in the main user’s guide.
MSP432 Memory Organization
When using the OAD firmware scheme special attention must be given to the memory organization of your application. A breakdown of the typical OAD application running on the MSP432 can be seen below:
Note that on MSP432P4111 devices (that have a 2MB flash memory footprint) all of the memory addresses in the diagram above will be scaled to match the 2MB footprint.
This memory scheme is followed in this code example and enforced via the linker command file. When firmware images are downloaded on the device, they are stored in the OAD Image storage area (in the example above this starts at 0x20000 and is 128KB in size). Meta-data for each firmware image (CRC32, version, length, etc.) is stored at address 0x1F000 and has 4K reserved. At address 0x0 a special bootloader that processes/programs SAP images resides. This special bootloader is described in the SAP section below.
Using this scheme it is important to understand that the underlying memory organization of your application will change. The user application (starting with the interrupt vectors) must start at 0x2000. At boot time, the customized BSL will load and check for a flag to determine if it needs to update the MSP432’s firmware or execute the application as normal. If this flag does not exist it will jump to reset vector located at 0x2004. When compiling your application it is important to use a TI-RTOS kernel configuration and linker file that relocates your application to start at 0x2000. A sample configuration is automatically imported in the tirtos_oad_builds_MSP_EXP432P401R_release_ccs project when you import the OAD code example. Specifically, in the TI-RTOS configuration file, the following lines must be added:
/* ================ Reset configuration ================ */
var Reset = xdc.useModule("xdc.runtime.Reset");
/*
* This function is used when a boot loader is used
*/
Reset.fxns[Reset.fxns.length++] = "&myReset";
/* ================ Vector Table re-location ================ */
var m3Hwi = xdc.useModule('ti.sysbios.family.arm.m3.Hwi');
m3Hwi.resetVectorAddress = 0x2000; /* App base */
After these settings are added in the .cfg file for the TI-RTOS build, the reset ISR must be updated in your application code to update the new vector table address. In the case of our code example, the updated reset routine is located in main_tirtos.c:
#if defined(__TI_COMPILER_VERSION__)
extern uint32_t ti_sysbios_family_arm_m3_Hwi_resetVectors;
int myReset(void)
#endif
{
/* Use Application the interrupt vector */
#if defined(__TI_COMPILER_VERSION__)
SCB->VTOR = (uint32_t) &ti_sysbios_family_arm_m3_Hwi_resetVectors;
#endif
return 1;
}
Usage/Program Arguments
The tool is distributed in two iterations: a compiled binary for your operating system and the Python source. The Python version used for testing/compilation is Python 3.5. The binary is provided under the tools/ti_oad_programmer/(your_os)/ folder while the source code is provided under the tools/ti_oad_programmer/source/ folder.
When the program is run, the following argument list is printed:
-h, --help show this help message and exit
-a ADDR, --bleaddr=ADDR
BLE Address for device to perform OAD firmware update
-f FIRMIMAGE, --firmware=FIRMIMAGE
File of the firmware to send to the BLE device for OAD
firmware update
-n DEVNAME, --blename=DEVNAME
Name of device to perform OAD firmware update
-c COMPORT, --comport=COMPORT
Path of serial port of CC2650 device running host_test
application.
-s, --scan_only Performs a scan of BLE devices within range and quits
program.
-t IMG_TYPE, --imagetype=IMG_TYPE
Type of image to download to device (0: SNP Hex Image
(Intel Hex Supported), 1: SAP Firmware (TI-TXT
Supported)
-v HEX_VERSION, --version=HEX_VERSION
Explicitly specifies the version to be used in the
meta-data download.Defaults to 0xFFFF (forces update).
Must be in 16-bit hex string format (ie 0xBEEF)
-d, --debug_mode Displays verbose logging/debug messages
The -c COMPORT, –comport=COMPORT parameter specified the COM port that the CC2650 LaunchPad is connected to. For Mac/Linux this generally looks like /dev/ttyX and for Windows this generally looks like COMX. It is important to make sure that the “User/Application” COM port is used and not the “Auxiliary” com port. In the screenshot from Device Manager below, you can see that the correct com port is COM49.
The -s, –scan_only option is a tool to scan BLE devices in the area and print out the address/name/RSSI information. When this option is used the program quits after scanning and no firmware update is performed. An invocation such as the following:
ti_oad_programmer.exe -c COM49 -s
Would produce output similar to:
Where MSP432 OAD is the device name and a0:e6:f8:b7:e1:3 is the device address. When performing an actual firmware update, either one of these parameters can be provided for the -n DEVNAME, –blename=DEVNAME or -a ADDR, –bleaddr=ADDR parameters respectively.
The -t IMG_TYPE, –imagetype=IMG_TYPE parameter specifies the image type that you want to update. A value of 1 would update the the SAP (MSP432) firmware and a value of 2 would update the firmware on the SNP (CC2650). Examples can be seen in the following two sections.
Updating the SNP (CC2650)
The first type of firmware update is updating the SNP (CC2650) device connected to the MSP432. The input firmware image for this option should be provided as a standard Intel hex file such as the ones provided in the source/ti/snp/ folder of the plugin. The following invocation:
ti_oad_programmer.exe -c COM49 -n "MSP432 OAD" -f ../../../source/ti/snp/simple_np_cc2650bp_uart_pm_sbl_59c69c3_merge.hex -t 2
Produces the following output:
In this example the arguments break down as follows:
- The CC2650 LaunchPad that we are using as a BLE client is connected to COM49
- We are connecting to the device with the name MSP432 OAD
- We are programming the ../../../source/ti/snp simple_np_cc2650bp_uart_pm_sbl_59c69c3_merge.hex firmware image
- The firmware type is an SNP image (2)
Note that SNP firmware images are usually about 128KB in size and can take around two minutes to fully download. Once downloaded, the LED on LED1 should turn solid white to signify the firmware update. Once finished, the device will reboot and the software will reset to default operation.
Updating the SAP (MSP432)
In addition to updating the SNP code the OAD profile can also update the firmware running on the MSP432 itself. The SAP firmware image must be provided in TI-TXT format. A TI-TXT image can easily be generated by enabling the HEX utility in the CCS property options as follows:
Once the TI-TXT file of the firmware is generated, the TI OAD Programmer can be invoked as follows:
ti_oad_programmer.exe -c COM49 -n "MSP432 OAD" -f project_zero_MSP_EXP432P401R_tirtos_ccs.txt -t 1
… This would produce an output similar to:
Breaking down the parameters:
- The CC2650 LaunchPad that we are using as a BLE client is connected to COM49
- We are connecting to the device with the name MSP432 OAD
- We are programming the project_zero_MSP_EXP432P401R_tirtos_ccs.txt firmware image
- The firmware type is an SAP image (1)
Note that the TI OAD Downloader takes the TI-TXT file of the SAP image and generates a special optimized firmware download image with extended meta-data. Once this image is downloaded to the MSP432, a custom bootloader takes control of execution and processes the image and extended meta-data. A compiled binary bootloader is included in this code example (and placed into a special memory location) within the oad_bootloader.c file. The source code for this bootloader can be found in the examples/nortos/MSP_EXP432P401R/oad_bootloader_source directory.
Modifying your Application for OAD Compatibility
To ensure that your application is compatible with the OAD scheme provided in this code example a few guidelines must be followed.
- Application code must start at correct offset (0x2000 by default)
As the top of flash memory contains the custom bootloader for processing/programming OAD images, the actual application must be set to start at the correct offset (by default 0x2000). This includes making it so that the interrupt vector table starts at 0x2000. This involves ensuring that your IDE’s linker command file is setup to compile at a base address of 0x2000. As a part of this example the following linker command files are provided:
- MSP_EXP432P4111_FREERTOS.cmd (MSP432P4111 FreeRTOS CCS)
- MSP_EXP432P4111_FREERTOS.lds (MSP432P4111 FreeRTOS GCC)
- MSP_EXP432P4111_TIRTOS.cmd (MSP432P4111 TI-RTOS CCS)
- MSP_EXP432P4111_TIRTOS.lds (MSP432P4111 TI-RTOS GCC)
- MSP_EXP432P401R_FREERTOS.cmd (MSP432P401R FreeRTOS CCS)
- MSP_EXP432P401R_FREERTOS.lds (MSP432P401R FreeRTOS GCC)
- MSP_EXP432P401R_TIRTOS.cmd (MSP432P401R TI-RTOS CCS)
- MSP_EXP432P401R_TIRTOS.lds (MSP432P401R TI-RTOS GCC)
These linker files serve the following functions:
- Reserve the top area of memory (0x00000000 to 0x00002000 by default) for the OAD bootloader
- Reserve relevant areas of memory for OAD image storage and metadata image storage (where necessary)
- Relocate the interrupt vector table to 0x2000
- Note that the OAD project, for simplicity provides a compiled bootloader in C-Array form (oad_bootloader.c). This must be removed prior to generating your OAD image.
When importing the oad_firmware_update application to your workspace you will notice a file in the workspace named oad_bootloader.c. This file is the C file representation of the bootloader that is meant to reside from 0x00000000 to 0x00002000.
\#if defined(__TI_COMPILER_VERSION__)
\#pragma DATA_SECTION(oad_bootloader, "OAD_BSL")
\#pragma RETAIN (oad_bootloader)
const unsigned char oad_bootloader[] =
\#elif defined(__GNUC__)
const unsigned char __attribute__((section (".oad_bsl"))) oad_bootloader[] =
\#elif defined(__IAR_SYSTEMS_ICC__)
\#pragma location="OTA_BSL"
__root const unsigned char oad_bootloader[] =
\#endif
{
0x00, 0x00, 0x04, 0x20, 0x51, 0x05, 0x00, 0x00, 0x61, 0x05, 0x00, 0x00,
0x61, 0x05, 0x00, 0x00, 0x61, 0x05, 0x00, 0x00, 0x61, 0x05, 0x00, 0x00,
0x61, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x61, 0x05, 0x00, 0x00,
This is the bootloader that takes the OAD image and updates the application image. It is provided in this project for convenience purposes so that the programmer does not have to worry about import two different projects and configuring the device for “differential download”. As such, when generating a firmware TXT file to use for OAD updates this file must be removed. Otherwise a TXT file will be generated that has the bootloader included. The bootloader will try to program a memory area where it is executing from and the firmware update will fail.
- TI-TXT files can be generated directly from Code Composer Studio using the HEX utility
Code Composer Studio has the ability to generate TI-TXT files (and other types of hex files) directly from the IDE itself. This can be useful for generating OAD images in the correct TI-TXT format. Right click any CCS project and click on Properties:
Under Build->ARM Hex Utility make sure that Enable ARM Hex Utility is checked. From here select the Output Formate Options on the left:
From here select your desired HEX format to be outputted (for example TI Hex). After this tool is enabled relevant HEX files will be generated post-build in the Debug output folder.