Bluetooth Low Energy - Over the Air Download (OAD) Fundamentals#

Introduction#

This module covers the basics of the Over the Air Download (OAD) feature of the TI BLE5-Stack. The estimated time to complete this lab is 3 hours. It is assumed that the reader has a basic knowledge of embedded C tool chains and general C programming concepts. This lab is intended as a starting point for users who want to get familiar with OAD concepts and running a basic update demo.

OAD refers to the ability to perform a device firmware update over-the-air using the BLE5 protocol stack. A number of software components are involved in this process and TI uses OAD to refer to all of them as a software system.

During this lab, the following topics will be covered:

  1. Understanding the OAD fundamental components.

  2. Setting up the environment to enable OAD.

  3. Running the OAD demo using BTool and SimpleLink™ Connect Mobile Application.

  4. Debugging an OAD project.

Moreover, the guide will split some tasks between On-Chip, Off-Chip and Dual-Image OAD. These sections will be accessible following an interface as the one presented below. Please select the desired application by clicking on one of the tabs.

This content will be related to On-Chip OAD use case.

This content will be related to Off-Chip OAD use case.

This content will be related to Dual-Image OAD use case.

Warning

Do not mix the information and files given for each of the OAD projects (On-Chip, Off-Chip and Dual-Image OAD) as this will lead to incorrect and unknown behavior.

Prerequisites#

Hardware#

For this lab, you need two Bluetooth-enabled development boards. Supported devices are:

Software for Development#

Software#

Readings#

Getting Started#

The following installation steps can be started in the background while reading the next chapter: Anatomy of an OAD.

Installing the Software#

  1. Install the desired Integrated Development Environment: CCS

  2. Run the SimpleLink™ SDK installer. This gives you the SDK with F included at the default location: C:\ti\simplelink_lowpower_f3_sdk_x_xx_xx_xx.

  3. UNIFLASH is required for flashing hex files and OAD enabled binaries.

Import Software Projects#

The following software projects will be used in this lab. They can be imported and compiled now.

Basic BLE OAD On-Chip

The basic_ble_oad_onchip example project contains what would be the user application functionality and implements the OAD reset service. The project can be found inside the ble5stack examples folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\basic_ble_oad_onchip\

Persistent App

The basic_persistent example project is required for on-chip OAD as well. This is a lightweight application that implements the OAD profile and is responsible of storing the new image. The project can be found inside the ble5stack example folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\basic_persistent\

MCUboot Secure Bootloader

The MCUboot is a secured open source bootloader that verifies and boots into the new image once downloaded. There is a pre-compiled binary available within the examples folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\hexfiles\mcuboot_onchip_<BOARD_NAME>_nortos_ticlang.hex

Basic BLE OAD Off-Chip

The basic_ble_oad_offchip example project contains what would be the user application functionality and implements the OAD reset service. The project can be found in the ble5stack examples folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\basic_ble_oad_offchip\

MCUboot Secure Bootloader

The MCUboot is a secured open source bootloader that verifies and boots into the new image once downloaded. There is a pre-compiled binary available within the examples folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\hexfiles\mcuboot_offchip_<BOARD_NAME>_nortos_ticlang.hex

Basic BLE Dual-Image

The basic_dual_image example project contains what would be the user application functionality and implements the OAD reset service. The project can be found in the ble5stack examples folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\basic_dual_image\

MCUboot Secure Bootloader

The MCUboot is a secured open source bootloader that verifies and boots into the new image once downloaded. There is a pre-compiled binary available within the examples folder:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\hexfiles\mcuboot_dual_image_<BOARD_NAME>_nortos_ticlang.hex

Note

The device’s MCUboot project included in the workspace must also be flashed to the device when using on-chip/off-chip OAD or the device will not function correctly.

As detailed in the introduction, the following sections will cover some of the primary topics related to OAD using the BLE5-Stack.

Anatomy of an OAD#

This section explains various components involved in an OAD image from a high-level perspective. Each software component is treated as a building block that is added to an unmodified BLE5-Stack application without OAD (for instance, basic_ble). These BLE5-Stack images are used to build an OAD image.

Default Non OAD Image#

We will begin with the template for a standard BLE5-stack image that does not have OAD enabled.

../_images/stock_cc23xx_image.png

Image without OAD#

There are three main components of this image:

  • The instructions/constants that implement the compiled form of the program (application code)

  • The reset vectors in the ARM Cortex M format: ARM Cortex M0+ Vector Table

  • The CCFG, which contains chip configuration parameters, see the Technical Reference Manual Section 8.2.1 CCFG.

OAD’s goal is to update a device’s software image wirelessly. In order to achieve this goal, a few software components must be (used/included).

Image Fragmentation and Image Header#

An entire image cannot be sent over in a single BLE packet due to the largest payload size supported by the Bluetooth Low Energy Specification. Therefore, the image to be sent over-the-air must be fragmented into a size that will fit into Bluetooth LE GATT payloads. The figure below pictures fragmentation of the new image into GATT payloads.

../_images/stock_cc23xx_image_frag.png

Image fragmentation#

As seen in the figure above, it will take many GATT packets to send a complete image over-the-air using the Bluetooth LE protocol. Each packet containing OAD image data is referred to as an OAD block.

However, there is no way for the receiving device to know information about the incoming image. This problem is solved by using the OAD Image Header. The OAD Image Header contains metadata describing the image and is used by the application and MCUboot secure bootloader to determine the suitability of an image for downloading or loading. Other benefits of the OAD Image Header are:

  • Image metadata is bundled as part of the image.

  • A running image can query knowledge about itself by reading the header.

  • Bootloader software can read the header to determine which image(s) are present and active.

  • Information about the incoming image is available to the target early in the OAD process.

Now, that we are sold on the benefits of an image header in an OAD system, here is an updated version of the previous drawing with an image header added.

../_images/cc23xx_image_with_header.png

Image with Header#

Warning

When comparing images with a header and images without the header one must keep in mind that the header itself takes up space. The space available to the code section of the image is shrunk to accommodate the header, and the reset vectors are pushed back to accommodate the header. These changes are specified in the linker script (shrinking app space) and the RTOS .cfg file (relocating reset vectors).

### Quiz **Why is an image header needed for OAD? (Select all that apply)** - [ ] The BLE5-Stack Link layer requires it > TI's OAD solution is built at the application/profile layer - [x] Provide the OAD profile information about the incoming image > The target can discern most of the info about the incoming image from this - [ ] It is defined by the Bluetooth Specification > OAD is not adopted at the Bluetooth SIG level. - [x] Tell the Bootloader how to validate the image > The Bootloader will perform checks based on the status fields in the image - [x] Tell the Bootloader how to launch the image > The Bootloader will jump to the location dictated in the image header

MCUboot Secure Bootloader#

A running image cannot update itself. This means that an incoming OAD image must be stored in a temporary location while it is being received. This temporarily location can be a reserved location in internal flash outside of the executable area covered in the first image (On-chip OAD and Dual-Image OAD applications). Alternatively, the temporary location can be in an external flash chip (Off-chip OAD applications).

In addition, after the download is complete, someone has to execute the logic to evaluate the new image and assess if the current image should be overwritten, and later executing the new image.

MCUboot is an open source project that supports hardware-independent secure bootloader for 32-bit MCUs. In the context of OAD, MCUboot serves the same purpose as the Boot Image Manager (BIM), which is to verify and boot into the new image once downloaded. Implementation details can be found in the public MCUboot Documentation. The code is maintained on the MCUboot GitHub Repository.

  • MCUboot is intended to permanently remain on the device, meaning it persists through many OADs and cannot be updated.

  • MCUboot will run every time the device boots and determine if a new image should be loaded and run (based on image header).

Furthermore, the MCUboot and CCFG structure are tied together, because both are required for a successful device boot.

The CCFG is needed by the boot ROM and startup firmware for device trim and to determine where the program execution is to start from. By default, the boot ROM will jump to address 0x00000000 and look for a vector table, but this region is now occupied by the image header. A custom CCFG must be used to instruct the device to jump directly to the MCUboot.

From there the MCUboot will perform device trim based on the CCFG settings, and determine and load the optimal image based on the OAD image header.

The MCUboot code will require more space to be reserved in our system. See below for the memory map after MCUboot has been added to the last image.

../_images/cc23xx_image_with_header_and_mcuboot1.png

Image with Header and MCUboot#

Warning

MCUboot is responsible for linking and defining the CCFG structure, instead of the application as in the non OAD case. Therefore, the CCFG section cannot be modified by OAD and will be removed by the toolchain if it is defined.

### Quiz **Should the file `ccfg_app_ble.c` be included and linked as part of the application?** 1. [ ] Yes, the application needs this to boot and trim properly > The CCFG can be linked external to the app 1. [x] No, the Bootloader links the CCFG > As a failsafe mechanism the CCFG is part of the Bootloader.

OAD Memory Layout#

The final memory structure depends on the type of OAD in use.

This section will describe the method for placing images in internal flash when using on-chip OAD.

Requirements and Constraints for On-chip OAD

In order to perform an On-chip OAD, the target system must have:

  • The user application must be sufficiently small in order to fit into the flash layout system described below.

  • User app functionality is lost while performing OAD (Persistent app is running).

Only one user application image may be stored in flash at any time.

Internal Flash Memory Layout

The internal flash of the device contains the active user application, the user application’s stack, the persistent application, the persistent application’s stack, and the MCUboot. Each application’s role is defined below.

As we have assumed the stack-library approach, the stack images referenced below are a part of each application image (i.e. the user and persistent apps have their own dedicated stack).

MCUboot Secure Bootloader

  • Search for the proper image in FLASH.

  • Copy new user image.

  • Ensure validity and optionally security of image before running.

Persistent Application

  • Providing lightweight application that implements the OAD profile.

Stack

  • BLE5-Stack protocol implementation.

User Application

  • User defined application code.

  • Must implement OAD reset service.

../_images/image_onchip_int1.png

On-Chip OAD Image#

The user application (referred to as Primary Slot) pictured above is responsible for the following:

  • Implementing the protocol stack definition of the OAD reset service

  • Implementing customer defined behavior

The persistent application (referred to as Secondary Slot) pictured above is responsible for the following:

  • Implementing the protocol stack definition of the OAD service This image is permanently resident on the device

The location of the persistent application varies depending on the flash size available for the selected device variant. This is done to maximize the user’s application space. Refer to the linker cmd file define IMG_A_FLASH_START to further determine where precisely the persistent application is located.

### Quiz **On-Chip OAD has the advantage of not requiring an external FLASH. What are drawbacks of On-Chip OAD that the system design needs to consider?** - [x] Reduced memory available for the application > MCUboot secure bootloader and persistent app take up memory that is not available for user application - [ ] Reduced speed of application > The OAD code does not affect the execution speed of a running application - [x] Application not available during update > Correct, during the update the persistent app is running which does not contain user code

This section will describe the method for placing images in internal and external flash when using off-chip OAD.

Requirements and Constraints for Off-chip OAD

Internal flash refers to the flash memory inside the device and external flash refers to an external SPI flash memory connected to the device.

In order to perform an Off-chip OAD the target system must have:

  • An off-chip flash storage as large as the application size + one external flash page to store the external flash image header. (default example will use 1MB of external flash)

  • A serial connection (SPI) is used to communicate with the off-chip flash component.

  • Free GPIO pins to interface to the external memory (i.e. 4 wires for SPI)

  • Enough free code space to reserve the entire contents of the last 1-2 flash page(s) for MCUboot.

The following software limitations exist on the external flash:

  • The maximum number of simultaneously stored OAD images is 256.

  • The OAD images’ headers shall be stored in the first 1 MBytes of the external flash addressable space.

  • The total size of the stored images should not exceed 4 GBytes.

Note

Off-chip OAD using the BLE5-Stack has only be tested using a 1 MBytes external flash. The out-of-the-box software do not allow larger external flash size.

Internal Flash Memory Layout

The internal flash of the device contains the active user application and the MCUboot. Off-chip OAD maximizes the available flash space to the user application because of its ability to store the incoming image in external flash during the download process.

../_images/image_offchip_internal.png

Off-Chip OAD Image Internal#

The user application pictured above is responsible for the following:

  • Implementing the protocol stack specific implementation of the OAD transport

  • Finding a suitable location in external flash for the image and storing its image header in the table.

External Flash Memory Layout

The off-chip flash memory on the SimpleLink™ device LaunchPad contains the image header vector table and the user applications. The memory map layout of the external flash part is defined in ext_flash_layout.h. The amount of space reserved for each application is dynamically sized by the user application’s implementation of the OAD protocol. The size of the image in external flash can be determined once the image header vector is sent over-the-air.

The application will round up as necessary according to the equation below:

../_images/num_extflashpages.svg

Off-Chip OAD Image External Formula#

The memory partition of the application for Off-chip OAD is depicted in below.

../_images/image_offchip_external.png

Off-Chip OAD Image External#

The size of the image header table is scalable and can be changed in the user application implementation of the OAD protocol.

This section will describe the method for placing images in internal flash when using dual image OAD.

Requirements and Constraints for Dual-Image OAD

In order to perform an On-chip OAD the target system must have:

  • The user application must be sufficiently small in order to fit into the flash layout system described below.

  • Only one operational user application image may be stored in flash at any time.

Internal Flash Memory Layout

The internal flash of the device contains the following:

  • MCUboot: search for the proper image in flash and ensure validity and security of image before running.

  • Download application: memory area equivalent to the active application flash which is available for storage once the over-the-air download begins.

  • Active application: implements customer defined behavior in addition to the OAD reset service.

../_images/image_dualimage.png

Dual-Image OAD Internal Flash Memory Layout#

OAD Protocol/ Bluetooth LE Profile#

Currently we have covered all the necessary building blocks for updating an image local to the target device. The only missing piece is a vehicle for sending the OAD blocks over-the-air and storing them on the target device.

This functionality is implemented by the BLE5-Stack OAD profile. The GATT profile is the vehicle for sending data over Bluetooth LE. At a high level, the BLE5-Stack OAD profile is responsible for receiving the following:

  • Determining if the candidate image should be accepted for download.

  • Receiving and unpacking image blocks and storing them.

  • Writing the received blocks to non-volatile storage.

  • Verifying the received image post download.

OAD Service#

The OAD service is responsible for receiving and storing an OAD image. This service is implemented in the basic_ble_oad_offchip, basic_dual_image and basic_persistent projects. See OAD service description in the BLE5-Stack User’s Guide for more information on the OAD service.

Name

UUID

Description

OAD Service

0xFFC0

OAD service declaration

Image Identify

0xFFC1

Used to send image header over-the-air

Image Block Request/Response

0xFFC2

Actual block of image data along with offset into the image

Extended Control

0xFFC5

Controls various aspects of OAD process

OAD Reset Service#

The OAD reset service is only used by basic_ble_oad_onchip project. It implements a method for switching/invalidating the currently running image and resetting the device. This must occur because in on-chip solutions the currently running image cannot update itself. See OAD reset service description in the BLE5-Stack User’s Guide for more information on the OAD reset service.

Name

UUID

Description

OAD Reset Service

0xFFD0

OAD reset service declaration

OAD Start/Reset Characteristic

0xFFD1

Responsible for starting the OAD process or resetting the target device
### Quiz **Does the image updated via OAD need to contain OAD related services in order for subsequent OADs to work?** 1. [x] Yes, something must receive and store OAD image blocks > Without an OAD profile, OAD is not possible. 1. [ ] No, the OAD code is embedded in the Bootloader > OAD is implemented at the app and profile layer

Task 1 – Setting up the OAD Environment#

The OAD environment requires a two-step setup:

  1. Flash the OAD Distributor with host_test and connecting it with BTool.

  2. Flash the OAD Target with the bootloader image and the application image. This example will use the basic_ble_oad_offchip and basic_ble_oad_onchip projects. For On-Chip OAD projects, the persistent app will also need to be flashed onto the OAD Target.

../_images/oad_dist_target_con.jpg

OAD Environment: Distributor and Target.#

Note

The OAD Distributor: refers to the device responsible for accepting an OAD enabled image from the compiler and transferring it over-the-air to the OAD Target device for a firmware update.

OAD Distributor Setup#

The OAD Distributor is the device responsible for fragmenting an OAD enabled image into chunks of OAD blocks and sending each block over to the OAD Target device as they are requested.

During this training we will use two different OAD Distributors: 1) SimpleLink™ Connect mobile application, and 2) another SimpleLink™ device LaunchPad running host_test in combination with BTool. BTool is a PC tool that is capable of interfacing to host_test and performing various Bluetooth LE operations through HCI functions in addition to OAD. For more information, refer to the host_test README file or the BTool User’s Guide. In addition, in this session we will also use

Flashing the host_test Image#

See below for the steps to setup the host_test image on a CC23xx.

  1. Navigate to hexfiles folder within the BLE5-Stack and select the file host_test_app.hex

    <SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\hexfiles\host_test_app.hex

  2. Flash the above hexfile using UNIFLASH.

../_images/uniflash_hosttest.png

Flashing host_test with UNIFLASH#

Warning

Please power-cycle the SimpleLink™ device after flashing it before you open the COM port in BTool.

Connecting BTool to host_test#

BTool and host_test communicate via USB through the XDS110 UART back channel. See below for a diagram:

../_images/oad_toolchain_ct.jpg

OAD Toolchain#

  1. Find the port used by the UART backchannel of the SimpleLink™ LaunchPad running host_test. This is the one with the name XDS110 Class Application/User UART.

  2. Open BTool (see the BTool executable in the tools folder of the BLE5-Stack).

  3. Use the following serial port settings, select OK.

    • Port: <PORT_FROM_ABOVE_STEP>

    • Baud Rate: 115200

    • Data length: 8 bits

    • Parity: None

    • Stop bits: 1 bit

    • Flow Control: None

  4. This will open and initialize the host_test device.

  5. Press the scan button and a list of discovered devices will populated in the BTOOL log.

  • A screen shot of a properly initialized BTool session is shown below

../_images/btool_init_success.png

BTool Init Success#

### Quiz **In the OAD ecosystem, `BTool` and `host_test` image combined together fulfill which role?** 1. [x] OAD Distributor > The key here is that BTool acts as a client to the OAD service 1. [ ] OAD Target > The OAD target is the device receiving the upgrade

OAD Target Setup#

As we learned in the section Anatomy of an OAD, the target device requires three images (On-Chip) or two images (Off-Chip and Dual-Image) to be flashed.

Note

Use a second LaunchPad for the following steps and do not flash the host_test board again.

The first image is the MCUboot. In this lab we will be using the secure release version that is available as a precompiled .hex file:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\hexfiles\mcuboot_onchip_<BOARD_NAME>_nortos_ticlang.hex

Both persistent and user applications cannot be directly flashed as a .hex file as image header data is required by the MCUboot to accept the image after startup. Instead we will be using the generated image *_oad.bin. This is automatically generated in CCS as a pre-build step that runs the OAD Image Tool. This applies to OAD enabled projects that have SECURITY defined, which is the default setting for OAD projects in the SDK.

The application image for on-chip OAD is split into two parts: Persistent app and user app. Exact project and file names may differ depending on the hardware and IDE used.

  1. Compile the Persistent App project. The Release folder should now contain the OAD binary basic_persistent_<BOARD_NAME>_freertos_ticlang.bin

  2. Compile the Basic BLE OAD On-Chip project. The Release folder should now contain the OAD binary basic_ble_oad_onchip_<BOARD_NAME>_freertos_ticlang_v1.bin

  3. Flash all three images using UNIFLASH. You can flash them in one run, see below screenshot. Note the start address of 0x0006000 for the persistent app and 0x00032000 for the OAD image application. To understand the reason behind the addresses values please refer to the OAD Memory Layout section.

../_images/uniflash_onchip.png

Flashing On-Chip MCUboot and application images.#

The first image is the MCUboot. In this lab we will be using the secure release version that is available as a precompiled .hex file (or use the compiled .hex file from your MCUboot project):

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\hexfiles\mcuboot_offchip_<BOARD_NAME>_nortos_ticlang.hex

The application cannot be directly flashed as a .hex file as image header data is required for the MCUboot to accept the image after startup. Instead we will be using the generated image *_oad.bin. This is automatically generated in CCS as a pre-build step that runs the OAD Image Tool.

After compiling the project. The folder Release will contain the file basic_ble_oad_offchip_<BOARD_NAME>_freertos_ticlang_v1.bin. You can flash them in one run, see below screenshot. Note the start address of 0x0006000 for the persistent app. To understand the reason behind the address value please refer to the OAD Memory Layout section.

../_images/uniflash_offchip.png

Flashing Off-Chip MCUboot and application image.#

The first image is the MCUboot. In this lab we will be using the secure release version that is available as a precompiled .hex file (or use the compiled .hex file from your MCUboot project):

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\hexfiles\mcuboot_dual_image_<BOARD_NAME>_nortos_ticlang.hex

The application cannot be directly flashed as a .hex file as image header data is required for the MCUboot to accept the image after startup. Instead we will be using the generated image *_oad.bin. This is automatically generated in CCS as a pre-build step that runs the OAD Image Tool.

After compiling the project. The folder Release will contain the file basic_dual_image_<BOARD_NAME>_freertos_ticlang_v1.bin. You can flash them in one run, see below screenshot. Note the start address of 0x0006000 for the persistent app. To understand the reason behind the address value please refer to the OAD Memory Layout section.

../_images/uniflash_dualimage.png

Flashing Dual-Image MCUboot and application image.#

Warning

Once the OAD Target is set up, please power-cycle the SimpleLink™ device after flashing. At this point, you should see the application menu on a serial terminal.

### Quiz **Select all of the following that are true about OAD Target devices.** - [ ] They can be peripheral role only > It is possible to update central devices via OAD - [x] Only one OAD session can be in progress at a time > This is true, there is no arbitration for blocks coming from multiple peers - [x] They must be GATT servers > In order to expose the OAD profile, the device must be a GATT server - [ ] They cannot be GATT clients > It is possible to both a server and a client - [x] They must be able to enter the connected state > You cannot access profiles and services without connecting

Task 2 – Running the OAD Demo#

Now that the OAD environment is ready, we will learn how to download a new image over BLE using BTool and the SimpleLink™ Connect Mobile Application.

Modifying the Image Version#

Modifying the image version is a quick and easy way to verify that the OAD has completed. Some sample apps, like our out-of-the-box examples, will display their image version in the terminal window.

  1. Open the project Properties by doing right click on the OAD project.

  2. Go to Build → Steps → Post-build steps.

  3. Modify the software version.

  4. Build the application project and generate a new binary *_vX.bin.

../_images/post_build_changeSWversion.png

Project Properties - Modifying the Image Version#

OAD using BTool#

  1. Read the OAD Target address. To do this, you can connect the OAD Distributor to a Serial Terminal. The program is prepared to display the device address when initializing.

  2. Now switch back to the OAD Distributor. Use BTool to scan for Bluetooth LE addresses and perform an OAD with the new version of our application. After scanning, look for the OAD Target address discovered in the previous step and connect to it as shown in the image below.

../_images/btool_connect_todevice.png

BTool Establish Connection#

  1. Once connected, switch to the OAD tab and load an OAD image (with .bin extension) into BTool by clicking at Read Image File.

Note

Make sure to use a new version of the image.

  • The Secure checkbox is read-only and indicates whether the currently loaded OAD image has security enabled in its header.

  • If using on-chip OAD, be sure to un-check the box OAD to external flash.

  • If using dual-image OAD, be sure to un-check the box OAD to external flash.

  • If using off-chip OAD, be sure to check the box OAD to external flash.

  • The OAD process begins once the image identify is accepted.

  • While intermittent blocks are being sent BTool will display: Write Block Number = x of y.

  • The OAD process will continue until BTool displays OAD Download Successful.

../_images/btool_execute_OAD.png

BTool OAD Process#

  • For secure OAD configurations, BTool uses the default public/private key pair. To change the security keys used by the embedded device, see Generating New Security Keys (Embedded) in the BLE5-Stack User’s Guide. To change the security keys used by BTool please see the next section of this chapter.

  • After some delay (verification process done by the MCUboot secure bootloader), the new image should boot up and will be active.

On the OAD Target device, a new image version number should be observed on the terminal display. If the version displayed on the terminal matches the one that was send from the OAD Distributor device, then the download has completed successfully.

../_images/OAD_newversion_serial.jpg

OAD Distributor Serial Terminal - New image version displayed.#

BTool Image Header Dialog#

A good way to inspect and parse the fields in the OAD Image Header for a given image is to use BTool. In this view, BTool will parse the various fields in the image header and present them in a human readable format. This can also be used to manually change various fields of the image header and then resign/recalculate the CRC. The image header dialog can be used to modify the image version number in order to simulate upgrading to a new version of the firmware via OAD.

You can access the OAD Image Header dialog using the following steps:

  • Open BTool.

  • Navigate to the Over The Air Download panel.

  • Select read image file, point this to the candidate image ending with _oad.bin.

  • Load an OAD image (with .bin extension) by clicking at Read Image File.

../_images/btool_imageheader.png

BTool - OAD Image Header#

OAD Speed Optimization#

The time required to accomplish the OAD process through BTool can be reduced by turning off the following settings at the User Interface. To this end, do right-click on the output panel at the right and turn off (un-check) the following features:

  • Display RX Dumps

  • Display TX Dumps

  • Display RX Packets

  • Display TX Packets

  • Auto Scroll Lock

../_images/OAD_optimization_speed.jpg

BTool - OAD Speed Optimization#

Further steps to improve the OAD speed are:

  • Increase the baud-rate of BTool and host-test (requires modification and re-compiling of the host-test project)

  • Select the highest possible packet length.

  • Ensure the fastest possible connection interval of 7.5 ms. For on-chip OAD, the target connection interval may be changed by the persistent app.

../_images/change_conn_int_75ms.jpg

SysConfig - Reduce Connection Interval.#

Note

The overall OAD performance on BTool is depending on the available processing power of the computer executing BTool. Running other software in parallel can have a noticeable impact in the time required for the OAD process.

Debug an OAD Project#

The following are recommended steps to debug the basic_persistent application (similar steps can be applied for basic_ble_oad_on_chip, basic_ble_oad_off_chip, etc).

  1. Build the image, flash the device and connect the debugger.

    • Build the basic_persistent app.

    • Click the Debug button – This leads the debugger to erase the device’s flash then download the newly built image.

    • This is going to lead to a JTAG Communication Error: (Error -615 @ 0x0). This is due to MCUboot image not being programmed leading the code at address 0x0 to be invalid.

    • In the Debug window, right click on Texas Instruments XDS110 USB Debug Probe then Connect Target.

    ../_images/Debug_OAD_connecttarget.png

    Code Composer Studios - Connect to Target#

  2. Enable the Memory Browser and Registers views.

    • Click View.

    • Then select Memory Browser.

    • Click again View and select Registers.

    ../_images/Debug_OAD_memorybrowser.png

    Code Composer Studios - Inspect Memory Browser#

  3. Force the device to execute the image you want to debug.

    • In the memory browser, find the entry point of the image. You can leverage the map file (see the green square) if you are not sure of the address.

    • In all the cases, you should find the resetVectors symbol at the entry point of the image.

    • For the basic_ble_persistent app, the entry point is at 0x6100. It is worth mentioning that the section 0x6000-0x60FF contains the image header.

    • In the Registers view, update the value of the Core Registers → SP register with the first value of the resetVectors (0x20009000 in this example).

    • In the Registers view, update the value of the Core Registers → PC register with the second value of the resetVectors (0x2C66D in this example).

    • In the Registers view, update the value of the SCB → VTOR register with the address of the resetVectors (which is also the entry point of the app, i.e. 0x6100 in this example).

    • Setup a breakpoint in the basic_persistent application (e.g. on the call to BLEAppUtil_init() in the function appMain() in app_main.c) and click the Run button.

    ../_images/Debug_OAD_vectors.jpg

    Code Composer Studios - Inspect Memory vector values.#

Note

The steps provided here only leads to flash one app (which is the recommended approach for app debugging). In case multiple apps have to be flashed at the same time, Uniflash should be used. Then the step to connect the Debugger to a Running Target described in the Debugger Guide should be followed. And, eventually, the steps in (1) and (2) should be applied.

References#