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 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 to perform the firmware update, an iOS device running iOS 10.0 or later is required.

Software Prerequisites

This code example has been tested with Code Composer Studio v7.4. For more information on how to import this project into your IDE workspace and build/run, please refer to the main user’s guide. IAR support for this code example is in the works and will be released on a follow-on release.

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
• SNP/SAP images limited to bank size of MSP432P401R (128KB)

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:

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.

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 devices and has full functionality to download and update user firmware to both the MSP432 SAP and the CC26xx SNP. Currently Android based phones are not supported.

The app can also be found at the link below:

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

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 MSP432 SDK Bluetooth 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. Currently the SimpleLink SDK Explorer supports the following cloud services to download from:

• Google Drive
• Box.com

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

First we will use Google Drive to download an SAP image that we will download to the flash storage of the MSP432. Select “Google Drive” from the source view to be taken to the Google Drive download view:

This view will prompt you for authorization through Google and prompt you to grant access to SimpleLink SDK Explorer for downloading files from Google Drive. In order for the download view to pick up the SAP image it must first be uploaded to your Google Drive in the root directory as seen below:

Once uploaded to the root of Google Drive type in the filename into the filename text field and touch “Download”. If found, 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. This time we will use Box.com to download the SNP image. First select the firmware selection view to get to the firmware source view and then select the Box item. This will take you to the Box.com firmware downloaded (where you will be prompted to authenticate):

In order for the download view to pick up the SNP image it must first be uploaded to your Box Drive in the root directory as seen below:

Once uploaded to the root of Box Drive type in the filename into the filename text field and touch “Download”. If found, 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.