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.

To use SimpleLink SDK Explorer for the firmware update the relevant application must be downloaded from the device app store. The app can be found at the links below:

Apple AppStore: https://itunes.apple.com/us/app/simplelink-sdk-explorer/id1237329921?ls=1&mt=8

Google Play: https://play.google.com/store/apps/details?id=com.ti.simplelinksdkexplorer&hl=en

Software Prerequisites

This code example has been tested with IAR Embeded Workbench 8.11, Code Composer Studio v7.4, and gcc-arm-none-eabi-6-2017-q1-update. 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 MSP432 SDK Bluetooth 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.

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

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

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

SimpleLink SDK Explorer

Perhaps the most intuitive way to perform firmware updates over BLE is to use a mobile device to send the firmware to the MSP432’s flash. SimpleLink SDK Explorer is a customized mobile application from Texas Instruments that is designed to compliment various aspects of the SimpleLink SDK mobile ecosystem. SimpleLink SDK Explorer currently is supported for iOS and Android devices and has full functionality to download and update user firmware to both the MSP432 SAP and the CC26xx SNP.

Apple AppStore: https://itunes.apple.com/us/app/simplelink-sdk-explorer/id1237329921?ls=1&mt=8

Google Play: https://play.google.com/store/apps/details?id=com.ti.simplelinksdkexplorer&hl=en

Additionally, the full BSD licensed source code for both applications can be found at the link below: https://www.ti.com/tool/download/SIMPLELINK-SDK-BLUETOOTH-PLUGIN

Open the mobile application once it has been downloaded:

From the main screen select the Profile Examples menu item. This will take you to a list of profile examples that correspond to each code example in the SimpleLink SDK BLE Plugin:

Select the Over the Air Download (OAD) menu item. On the next screen SimpleLink SDK Explorer will automatically scan for BLE devices in your vicinity. Make sure Bluetooth is enabled on your iOS device or else no devices will show up in this view. After pressing S1 on your MSP432 LaunchPad the OAD code example will start to advertise and show up as “MSP432 OAD”:

After pressing “MSP432 OAD” you will be taken to the over-the-air download view:

This screen will give a few different options as far as the far as the firmware download is concerned. First, a firmware image needs to be imported into the mobile application before it can be downloaded.

Touch the “Touch to Select Firmware” button to be taken to the firmware download source selection view:

Pressing “Browse for Images” will open up the iOS device’s native document picker view. This generic view will allow you to import your firmware from a variety of different cloud sources. These cloud sources are made available by installing the vendor specific cloud application directly on your device. By default the iCloud Drive service is installed. If you want to download firmware images from Google Drive, for example, you would download and install the Google Drive iOS Application.

First we will download a SAP image that we will upload to the flash storage of the MSP432. From the document picker navigate to the corresponding .txt file of the SAP application that you want to download. The application will download the firmware and return you to the main screen:

Making sure the “SAP” option is selected, touch “Download Firmware” to start the firmware update to the MSP432:

On a successful download the MSP432 will reset itself with the new firmware and SimpleLink SDK Explorer will disconnect from the device. The process for updating the SNP image is similar.

Open up the “Browse for Images” option from the firmware sources view and download your relevant .hex image of the SNP image. The application will download the firmware and return you to the main screen. *Make sure the SNP option is selected on the download view to signify that you want to update the CC26xx instead of the MSP432.

After pressing “Download Firmware” you will be able to download the firmware to the MSP432’s flash (where it will then reboot and initiate an SNP update after completion).

Note that any firmware file that has been previously downloaded will show up in the “Downloaded Images” firmware source view:

There are a couple of options available on the firmware download view. the first of which is the “Firmware Version”. This option is used to specify the firmware version that is specified in the OAD meta data that is sent ot the device prior to firmware image download. When set to “0xFFFF” the firmware will always update. If a value other that “0xFFFF” is given the OAD firmware running on the MSP432 will check to see if the firmware image to be downloaded is newer that the firmware image currently on the MSP432/CC26xx device. If it is newer the firmware will be downloaded while if it is older the OAD application will reject the metadata and the OAD firmware download will be canceled.

The next option is the “address” option. Currently this option is set to “0x20000” as this is the start of flash bank 1 on the MSP432P401R, however this field can be changed for future devices that have different memory maps than the MSP432P401R (such as MSP432P4111).