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.
mcuboot
: secured open source bootloader, supports multiple image areas (Primary+Secondary) with SWAP or Overwrite modes. In the context of OAD, MCUboot serves the purpose of verifying and booting into the new image once downloaded. Implementation details can be found in the public MCUboot documentation. The source code for MCUboot is maintained on the MCUboot GitHub page.basic_ble_oad_offchip
: this project contains what would be the user application functionality and implements the OAD reset service for images stored inside an external flash to the chip.basic_ble_oad_onchip
: this project contains what would be the user application functionality and implements the OAD reset service for images stored inside an internal flash.basic_persistent
: this project contains a lightweight application that implements the OAD profile and is responsible of storing the new image. It is required for on-chip OAD.basic_dual_image
: this project contains what would be the user application functionality and implements the OAD reset service for images stored inside an internal flash. Unlike the basic_ble_oad_onchip, there is no need for a persistent application running the OAD process and interrupting the main user application.
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:
- For all the OAD projects, go to ${SDK}/examples/rtos/LP_EM_CC2340R5/ble5stack.
- 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.
- Import and build the projects using Code Composer Studio.
- Look for the ".bin" files inside the Release folder for the following projects:
basic_ble_oad_onchip
,basic_ble_oad_offchip
,basic_persistent
, andbasic_dual_image
. - Look for the ".hex" file inside the Release folder for the MCUboot project.
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
- BLE OAD On Chip:
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.).
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".
- Build the
Enable the "Memory Browser" and "Registers" views.
- Click "View".
- Then select "Memory Browser".
- Click again "View" and select "Registers".
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 toBLEAppUtil_init()
in the functionappMain()
inapp_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.