Over-the-Air Download Code Example

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. This hardware configuration is shown in the below image:

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 Code Composer Studio v7.1. 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 mobile application (planned for 1Q2017)
• 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.

Mobile Application

Both an iOS and Android application are currently in the works that will allow wireless firmware updates from a mobile device. These applications are slated for a follow-on release and are estimated to be available 2Q2017.