Introduction

This module is an advanced study of the Over the Air Download (OAD) feature of the TI BLE5-Stack. The estimated time to complete this lab is between 1-2.5 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 additional material for users who are already familiar with the OAD concepts presented in the OAD Chapter of the BLE5-Stack User's Guide.

OAD refers to the ability for an image to download a new executable image, 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.

This lab will be based on the OAD Fundamentals lab. The OAD distributor (host_test and btool) will be re-used and basic OAD knowledge is being expected.

The first task is to add OAD to an existing project, using multi_role as an example. After learning how to debug OAD code, the lab will explain how to create an OAD production image.

Prerequisites

Hardware

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

• SimpleLink™ CC26x2R LaunchPad™
• SimpleLink™ CC2652RSIP LaunchPad™
• SimpleLink™ CC2652RB LaunchPad™
• SimpleLink™ CC1352R LaunchPad™
• SimpleLink™ CC1352P LaunchPad™
• SimpleLink™ CC2652R7 LaunchPad™
• SimpleLink™ CC1352P7 LaunchPad™

These devices are interchangeable in the lab.

Software for desktop development

• CCS 12.0 or IAR 8.50.9 installed with support for CC13xx/CC26xx devices
• SimpleLink™ CC13XX and CC26XX 6.20 SDK
• BTool (located in the \tools\ble5stack directory of the SimpleLink™ Device SDK)
• UNIFLASH
• SRecord (for creating a production image)

Required reading

• SimpleLink Academy: Bluetooth Low Energy Enhanced Over the Air Download (OAD) Fundamentals

Recommended reading

• SimpleLink Academy: Bluetooth Low Energy Fundamentals
• SimpleLink Academy: Making a Custom Profile

Getting started – Desktop

Install the Software

The same software will be used as described in OAD Fundamentals (Install the Software).

Import Software Projects

Multi_Role

In addition to the projects used in OAD Fundamentals, we need to import multi_role from the following directory:

<SDK_INSTALL_DIR>\examples\rtos\<BOARD_NAME>\ble5stack\multi_role\tirtos7

Task 1 – Add OAD to Multi Role

This section will detail how to add BLE Off-Chip OAD to an existing project. The intention is to start with an unmodified example app from the SDK that does not currently use OAD, and add OAD to it.

Customers can use this section to add OAD to their existing projects. The example project used to demonstrate these steps will be multi_role.

Project Changes

In order to add OAD, certain files and include paths should be added to the project, these are detailed in the list below.

Code Changes

The following changes need to be performed in the source code of the application

1. Performing the following changes in the high level application task file.

   • Add the required include directives in multi_role.c near the other include directives:

     Select text

     #include <profiles/oad/cc26xx/oad.h>
     #include <ti/common/cc26xx/oad/oad_image_header.h>
     #include <ti/devices/DeviceFamily.h>
     #include DeviceFamily_constructPath(driverlib/sys_ctrl.h)
     

   • Add the OAD events to the app's *_ALL_EVENTS macro (be sure to add line breaks as necessary) in multi_role.c:

     Select text

      OAD_QUEUE_EVT | \
      OAD_DL_COMPLETE_EVT)
     

   • After the above step the MR_ALL_EVENTS should look like this

     Select text

       #define MR_ALL_EVENTS                (MR_ICALL_EVT           | \
                                             MR_QUEUE_EVT           | \
                                             OAD_QUEUE_EVT          | \
                                             OAD_DL_COMPLETE_EVT)
     

   • Add the following declarations under the LOCAL VARIABLES section in multi_role.c:

     Select text

       static uint8_t numPendingMsgs = 0;
       static bool oadWaitReboot = false;
     

   • Add the following forward declarations under the LOCAL FUNCTIONS section in multi_role.c

     Select text

       static void multi_role_processOadWriteCB(uint8_t event, uint16_t arg);
       static void multi_role_processL2CAPMsg(l2capSignalEvent_t *pMsg);
       static void multi_role_processConnEvt(Gap_ConnEventRpt_t *pReport);
     

   • Add the following callback initializers under the PROFILE CALLBACKS section in multi_role.c

     Select text

       static oadTargetCBs_t multi_role_oadCBs =
       {
         .pfnOadWrite = multi_role_processOadWriteCB // Write Callback.
       };
     

   • Inside the multi_role.c::multi_role_init(), add the following:

     Select text

      // Open the OAD module and add the OAD service to the application
      if(OAD_SUCCESS != OAD_open(OAD_DEFAULT_INACTIVITY_TIME))
      {
          /*
           *  OAD cannot be opened, steps must be taken in the application to
           *  handle this gracefully, this can mean an error, assert,
           *  or print statement.
           */
      }
      else
      {
          // Register the OAD callback with the application
          OAD_register(&multi_role_oadCBs);
      }
     

   • Add the OAD event processing in multi_role.c::multi_role_taskFxn() do this after ICall event processing:

     Select text

      // OAD events
      if(events & OAD_QUEUE_EVT)
      {
          // Process the OAD Message Queue
          uint8_t status = OAD_processQueue();
     
          // If the OAD state machine encountered an error, print it
          // Return codes can be found in oad_constants.h
          if(status == OAD_DL_COMPLETE)
          {
              // Report status
          }
          else if(status == OAD_IMG_ID_TIMEOUT)
          {
              // This may be an attack, terminate the link
              GAP_TerminateLinkReq(OAD_getactiveCxnHandle(),
                                   HCI_DISCONNECT_REMOTE_USER_TERM);
          }
          else if(status != OAD_SUCCESS)
          {
              // Report Error
          }
      }
     
      if(events & OAD_DL_COMPLETE_EVT)
      {
          // Register for L2CAP Flow Control Events
          L2CAP_RegisterFlowCtrlTask(selfEntity);
      }
     

   • Process L2CAP messages from the stack. This will replace the existing L2CAP_SIGNAL_EVENT case statement inside of multi_role.c::multi_role_processStackMsg().

     Select text

     case L2CAP_SIGNAL_EVENT:
     {
        // Process L2CAP free buffer notification
        multi_role_processL2CAPMsg((l2capSignalEvent_t *)pMsg);
        break;
     }
     

   • Make an application level L2CAP handler function as below. Add this function at the end of multi_role.c

     Select text

     static void multi_role_processL2CAPMsg(l2capSignalEvent_t *pMsg)
     {
       static bool firstRun = TRUE;
     
       switch (pMsg->opcode)
       {
       case L2CAP_NUM_CTRL_DATA_PKT_EVT:
       {
           /*
            * We cannot reboot the device immediately after receiving
            * the enable command, we must allow the stack enough time
            * to process and respond to the OAD_EXT_CTRL_ENABLE_IMG
            * command. This command will determine the number of
            * packets currently queued up by the LE controller.
            */
           if (firstRun)
           {
               firstRun = false;
     
               // We only want to set the numPendingMsgs once
               numPendingMsgs = MAX_NUM_PDU
                       - pMsg->cmd.numCtrlDataPktEvt.numDataPkt;
     
               // Wait until all PDU have been sent on cxn events
               Gap_RegisterConnEventCb(multi_role_processConnEvt, GAP_CB_REGISTER,
                                       OAD_getactiveCxnHandle());
     
               /* Set the flag so that the connection event callback will
                * be processed in the context of a pending OAD reboot
                */
               oadWaitReboot = true;
           }
           break;
       }
       default:
           break;
       }
     }
     

   • Add a connection event processing function, do this at the bottom of multi_role.c

     Select text

     static void multi_role_processConnEvt(Gap_ConnEventRpt_t *pReport)
     {
       /* If we are waiting for an OAD Reboot, process connection events to ensure
        * that we are not waiting to send data before restarting
        */
       if(oadWaitReboot)
       {
           // Wait until all pending messages are sent
           if(numPendingMsgs == 0)
           {
               // Reset the system
               SysCtrlSystemReset();
           }
           else
           {
             numPendingMsgs--;
           }
       }
       else
       {
         // Process connection events normally
       }
     }
     

   • Add an event handler function to process OAD events, do this at the bottom of multi_role.c

     Select text

     static void multi_role_processOadWriteCB(uint8_t event, uint16_t arg)
     {
       Event_post(syncEvent, event);
     }
     

   • Add the following code to the ATT_MTU_UPDATED_EVENT handler. This should be processed by the application when it receives a messages of gattMsgEvent_t from the stack. You can find this in multi_role.c::multi_role_processGATTMsg()

     Select text

      OAD_setBlockSize(pMsg->msg.mtuEvt.MTU);
     

2. Reset OAD if connection drops

   • Add the following code to the GAP_LINK_TERMINATED_EVENT handler. This can be found in multi_role.c::multi_role_processGapMsg()

     Select text

      // Cancel the OAD if one is going on
      // A disconnect forces the peer to re-identify
      OAD_cancel();
     

3. (Optional) Add revert to factory image feature to application:

   • Add the following code to main.c

     Select text

     #include <profiles/oad/cc26xx/mark_switch_factory_img.h>
     #include <ti/drivers/GPIO.h>
     

     Place this code inside main( ) before ICall_init()

     Select text

     if(!GPIO_read(CONFIG_GPIO_BTN1))
     {
       markSwitchFactoryImg();
     }
     

4. (Optional) Changing external flash pins:

   Custom Hardware

   This steps is only required for customers wishing to add OAD to their custom boards. The LaunchPad board files will work out of the box.

   • The examples will work on the LaunchPad out of the box, but for custom hardware the following is recommended.

   • Change the pins for the BIM. See bsp.h, change the defines below.

     Select text

      // Board external flash defines
      #define BSP_IOID_FLASH_CS       IOID_20
      #define BSP_SPI_MOSI            IOID_9
      #define BSP_SPI_MISO            IOID_8
      #define BSP_SPI_CLK_FLASH       IOID_10
     

Now that we successfully added OAD to the multi_role project, perform an OAD to update simple_peripheral_oad_offchip to multi_role.

Task 2 – Advanced OAD Debugging

This task divided into a number of subtasks that aim to highlight a debugging technique specific to OAD enabled projects. For each subtask, we will force an issue to occur in order to show a novel way to debug it.

Debugging from the BIM to the application

1. Start debugging OAD enabled application by pressing the debug icon in the IDE
2. Verify that the program runs correctly while debugging, but do not disconnect the debugger.
3. Add the BIM's symbols to the debug session, these should be located in <CCS_WORKSPACE_DIR>\cc26x2r1lp_bim_offchip\Debug\cc26x2r1lp_bim_offchip.out
   
4. Load the same symbols from the BIM to the debug session.
   
5. Reset the device using the debugger.
   

6. Set a breakpoint in bim_offchip_main.c::Bim_checkImages() from the BIM project

   

At this point you should be able to single step through the BIM code.

Debugging Slow OAD Download Speeds

One of the major improvements of the enhanced OAD profile are its utilization of MTU exchange and scalability of over the air block sizes. There are two major factors that determine the speed of an OAD download:

• The connection interval
• The OAD block size

The connection interval is set by the Central in the connection, but an update can be requested by the Peripheral device. Ultimately, it is up to the Central to set the connection parameters. To configure this request, open the SysConfig file and navigate to BLE → Peripheral Configuration → Connection Update Request Parameters. Here you can set the time for how long the Peripheral will wait from connection is formed until it sends the request, and the parameters to request.

In the case of the OAD sample applications, both project_zero and simple_peripheral_oad_offchip will request a connection parameter update about PZ_SEND_PARAM_UPDATE_DELAY or SP_PERIODIC_EVT_PERIOD after a link is established based on a RTOS clock timeout.

One way to force a slow OAD is to prevent BTool from sending a connection parameter update at the start of OAD. In this case, the OAD Target device will send the parameter update that will slow the connection interval. This is normally a good practice for power savings reasons, but if an OAD is occurring this can be detrimental to speed.

1. Connect to the OAD Target device via BTool.
2. Navigate to the Over the Air Download tab
3. Select the options pane and disable the check box near Use These Connection Settings During OAD. This will prevent BTool from sending a new connection parameter update at the beginning of an OAD.
   
4. Wait for the application to send its parameter update, this will appear as an event in the logs.
   
5. Start the OAD, observe slow speeds
6. Cancel the OAD, re-check the box from step 3, and re-start the OAD.
7. Repeat step 4
8. After the parameter update is received, start the OAD via BTool. Observe that the speed will be much quicker.

Another contributing factor to the overall OAD throughput is the MTU size. The OAD block size is set by the OAD target device based on the MTU exchange. MTU exchanges are initiated by the GATT client device. There are three ways that the OAD session may potentially suffer from low throughput due to MTU size.

1. The OAD Target device is not built to support large MTU.

   • This is controlled by the Maximum size of PDU (Found in SysConfig → BLE → General Configuration). This define can range up to 255.
   • The formula for supported MTU based on the PDU size is local supported MTU = PDU_SIZE - L2CAP_HDR_SIZE

2. The OAD Distributor device does not support a large MTU, or the GATT client has not initiated an MTU exchange

   • Just as locally the device must support large MTU, so must the peer, legacy or memory constrained peer devices may not support large MTU.

3. The OAD target is not reporting a negotiated MTU event to the OAD module.

   • This is achieved by the the call to OAD_setBlockSize()

The following steps will detail how to perform an OAD with smaller MTU size

1. Open the BTool OAD Options window, and set Preferred Block Size to 24.
2. Connect to the device and re-start the OAD.
3. Observe that the total download time has greatly increased as the total blocks have increased to ~8000.

Task 3 – Creating a Production Image

A production image is a single image that is made of all the images involved in an OAD system. In the case of off-chip OAD, the production image will consist of the app image and the BIM. Production images are desirable because they can be used to program devices in a test environment or production line using a single image. These images also must contain a valid image header.

Since the production image must contain a valid image header, the _oad.bin image output by the TI OAD Image Tool must be used. This bin file contains the app image. However, the app image cannot boot without a BIM included on the device, so for a production image the app image must be merged with the BIM image.

Change to Release BIM

By default, the projects in the SimpleLink CC13xx/CC26xx SDK will use a debug version of the BIM. This is helpful for evaluation of the TI OAD solution, but is not recommended for a production OAD build for the following reasons:

• The debug configuration of BIM will not check the CRC of the image before booting. This removes a layer of redundancy in the system in favor of allowing the develop to load an OAD image straight from the IDE
• The debug configuration has LED output that may not be desirable in production.

Additionally, it may be desirable to remove the secondary device trim in the application for production images. See Device trim within the BIM section of the User Guide for more information.

Secure OAD: Change default keys

If you are using the secure version of OAD, new OAD keys should be generated and stored on the device. It is a security risk to use the placeholder keys that are provided with TI as these are publically available. See Generating New Security Keys (Embedded) in the User Guide for more information on how to generate and install new keys on the device. If using unsecure OAD, this step is not necessary.

Loading a Production Image

Images loaded straight from the IDE will not have a valid CRC or signature. However, the oad_image_tool will add the CRC and signature automatically at the completion of each build.

Before loading the application, be sure to load the release BIM project. This can be flashed via the BIM’s hex file in UNIFLASH.

Combined Production Image

To combine the images, we will use the SRecord tool. The below steps assume that the Debug configuration of the BIM is used, and the FlashROM_Release configuration of multi_role is used. The steps can be easily modified or adapted to cover other configurations or sample applications. The CCS workspace location will be referred to as <CCS_WORKSPACE_LOC>

1. Download SRecord

2. Unzip the SRecord package into a location that will be referred to as <SREC_LOC>

3. Make sure your application and BIM have been built

4. Run the following command, you will need to replace <SREC_LOC> and <CCS_WORKSPACE_LOC> to match your environment. This will generate a production image titled mutli_role_oad_production.hex in <SREC_LOC>

   Select text

   <SREC_LOC>/srec_cat.exe <CCS_WORKSPACE_LOC>/bim_offchip_CC26X2R1_LAUNCHXL_nortos_ccs/Debug/bim_offchip_CC26X2R1_LAUNCHXL_nortos_ccs.hex -intel <CCS_WORKSPACE_LOC>/ble5_multi_role_cc26x2r1lp_app/FlashROM_Release/ble5_multi_role_cc26x2r1lp_app_FlashROM_Release_oad.bin -bin -o multi_role_oad_production.hex -intel
   

5. Use Uniflash to flash the multi_role_oad_production.hex on the device, verify that the device is working and runs through a reset.

References

BLE5-Stack User's Guide

SRecord

SRecord Examples