Basic BLE OAD Project

Table of Contents

Introduction

The Over the Air Download (OAD) series of projects are intended as a starting point for users who want to quickly implement an OAD application. OAD refers to the ability for an image to download a new executable image, over the air using a Bluetooth low energy connection (BLE5 protocol stack) while providing power loss protection.

To better understand the different concepts each project is implementing, please refer to the BLE5-Stack User's Guide.

Hardware Prerequisites

The default Basic BLE OAD projects' board configurations use the device's LaunchPad development kit.

Software Prerequisites

For information on what versions of Code Composer Studio and IAR Embedded Workbench to use, see the Release Notes file provided in the SDK. In addition, please refer to the User's Guide for information on importing this project into your IDE workspace and build/run.

To evaluate this example, the flash programming tool UniFlash is required. The Release Notes file provides information on the version to use.

OAD Projects

The following projects implement the OAD functionality using the basic_ble application as the starting point. The application behavior is the same as the basic_ble project, with the exception that OAD is added. For guidance on this out of the box demo for OAD refer to the on-chip OAD section of the BLE5-Stack User's Guide.

Note: The device's mcuboot project included in the workspace must also be flashed to the device when using on-chip/off-chip/dual_image OAD or the device will not function correctly.

GATT Services

The Basic BLE OAD On-Chip project contains the OAD Reset Service, and the Basic BLE OAD Off-Chip/Dual-Image projects contains the OAD Service.

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

Usage

UART

This application uses the UART peripheral to provide an interface for the application. The UART is only used for display messages.

We recommend using a terminal program that can parse ANSI/VT100 color codes, such as Tera Term, PuTTY, Code Composer Studio Terminal, etc., to monitor the LaunchPad UART output.

The following default parameters are used for the UART peripheral for display:

UART Param Default Values
Baud Rate 115200
Data length 8 bits
Parity None
Stop bits 1 bit
Flow Control None

Flash an OAD project

Note: the descriptions below presume the LP_EM_CC2340R5 board and Code Composer Studio IDE, but the paths, addresses and build processes may slightly vary.

To program the devices, flash the respective files as follows:

  1. For all the OAD projects, go to ${SDK}/examples/rtos/LP_EM_CC2340R5/ble5stack.
  2. For MCUboot, go to ${SDK}/examples/rtos/LP_EM_CC2340R5/ble5stack/hexfiles:mcuboot_dual_image_LP_EM_CC23xx, mcuboot_offchip_LP_EM_CC23xx, mcuboot_onchip_LP_EM_CC23xx.
  3. Import and build the projects using Code Composer Studio.
  4. Look for the ".bin" files inside the Release folder for the following projects:basic_ble_oad_onchip, basic_ble_oad_offchip, basic_persistent, and basic_dual_image.
  5. Look for the ".hex" file inside the Release folder for the MCUboot project.

  6. Open UniFlash and load the files through the Program window. Flash the files as explained below:

    • BLE OAD On Chip:
      • mcuboot_onchip_xxx_xxx.hex - Load Addr: AUTO
      • basic_persistent_xxx_xxx.bin - Load Addr: 0x00006000
      • basic_ble_oad_onchip_xxx_xxx.bin - Load Addr: 0x00032000
    • BLE OAD Off Chip:
      • mcuboot_offchip_xxx_xxx.hex - Load Addr: AUTO
      • basic_ble_oad_offchip_xxx_xxx.bin - Load Addr: 0x00006000
    • BLE OAD Dual Image:
      • mcuboot_dual_image_xxx_xxx.hex - Load Addr: AUTO
      • basic_dual_image_xxx_xxx.bin - Load Addr: 0x00006000

  7. Power cycle the device.

Note: If provided, you may also find prebuilt images in ${SDK}/examples/rtos/LP_EM_CC2340R5/ble5stack/hexfiles

Debug OAD Projects

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

  2. Enable the "Memory Browser" and "Registers" views.

    • Click "View".
    • Then select "Memory Browser".
    • Click again "View" and select "Registers".

  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
    • 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"

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 II- and III- should be applied.