Introduction

This workshop demonstrates how to use the SimpleLink™ Wi-Fi® Over-The-Air (OTA) library. The library can be used to wirelessly load and install software updates from a cloud server. A software update may contain any combination of application code, firmware, and user files.

This workshop will start with an overview of the OTA mechanism and then walk through the bring up of two OTA examples:

1. Using the Cloud OTA example to load and update a pre-built image
2. Preparing an OTA update, uploading it to the cloud, and loading it with the Cloud OTA example.

At the end of this training, the audience should be able to:

• Understand the OTA process and the SimpleLink Wi-Fi solution
• Configure, build, and execute the SimpleLink cloud_ota application and OTA library (ota) on the CC32xx LaunchPad
• Create an OTA update image and upload it to a CDN (Content Delivery Network) Server

Prerequisites

Software

• Code Composer Studio v10.3 or newer
  • SimpleLink Wi-Fi CC32xx Wireless MCUs support installed
  • Make sure that CCS is using the latest updates: Help → Check for Updates
• CC32xx SDK v5.10 or newer
• Terminal emulator program such as TeraTerm or PuTTY

Hardware

• 1x CC32xx LaunchPad
  • CC3235S LaunchPad (LAUNCHXL-CC3235S)
  • CC3235SF LaunchPad (LAUNCHXL-CC3235SF)
  • CC3220S LaunchPad (CC3220S-LAUNCHXL)
  • CC3220SF LaunchPad (CC3220SF-LAUNCHXL)
• 1x Micro-USB cable (included with LaunchPad)
• 802.11b/g/n Wireless Access Point (AP)
• Smartphone with Wi-Fi Starter Pro Mobile Application

OTA Overview

OTA Concept

• OTA (Over-The-Air) update is an efficient way of wirelessly distributing firmware updates or application upgrades.
• An OTA Update mechanism enables users to easily and securely update the software on their device using Wi-Fi. This involves two simple procedures:
  • A vendor stores an OTA update on a CDN (Content Delivery Network) server.
  • The endpoint devices with an OTA-enabled application load and install the new update.
• An OTA-enabled application must support all of the following actions:
  • Polling the CDN (Content Delivery Network) server for new updates
  • Downloading the new image
  • Installing the image on the flash file system in a secured and fail-safe manner (the new image becomes a "candidate")
  • Committing the image after it is validated (making it "operational")
• The SimpleLink OTA library offloads the above OTA actions and provides a simple API for the application.

OTA System Diagram

• CDN (Content Delivery Network): Globally distributed network of proxy servers deployed in multiple data centers. The goal of a CDN is to serve content to end-users with high availability and high performance. Examples would be Dropbox or GitHub.
• OTA library: Offloads the OTA actions (such as polling the server, downloading the updates and installing them in the local flash) while exposing a simple API.
• OTA-enabled Application: Triggers the OTA library and respond to OTA events. The application will take decisions whether to accept or decline an update (usually based on timestamp) and whether to commit or rollback the already installed image (based on a sanity check).
  

SimpleLink OTA Library (ota)

• The OTA library implements a simple HTTP client that connects to a CDN server (through CdnVendor and OtaHttpClient modules).
• The HTTP client can be configured as:
  • Non Secured (connects to CDN running HTTP Server)
  • Secured (HTTPS server) using server authentication (by default)
  • Domain Name verification (default) or without server authentication.
• The OTA library supports the following cloud CDN vendors:
  • Github (demonstrated in the first demo)
  • Dropbox (demonstrated in the second demo)
  • Custom
• The library defines a structure for the OTA image in a TAR file. The ImageCreator tool can be used to create an OTA TAR file so that the OTA library will be able to parse the loaded content and install it on the local flash file system in a secure and fail-safe manner (through the OtaArchive and OtaJson modules)
• The OTA library is provided as a static library project with full source code to enable user customizations.
  

OTA Library API

The OTA library exposes very simple API set:

• OTA_init(): Initializes the OTA library. The host application should define a global buffer for the use of the OTA library and provide this buffer while it initiates the OTA.
• OTA_set(): Sets an OTA library parameter. Used to set CDN Server information and to update the status of the loaded image (DECLINE, ACCEPT, COMMIT or ROLLBACK).
• OTA_get(): Retrieves OTA library parameters, e.g. IS_ACTIVE or VERSIONS info (current image version and new update version).
• OTA_run(): Trigger the OTA library state machine. This will trigger OTA polling, download, etc. It should be called repeatedly until it gets the DOWNLOAD_DONE return code.

This API set is compatible with both non-OS and OS-based platforms.

OTA Sample Application

• The first role of an OTA-enabled application is to verify and commit a "candidate" image that was previously installed to the local flash.
  • Once the device is connected to the network and can successfully PING to the local gateway, the application assumes the image is okay.
  • If the OTA state is PENDING_COMMIT, the application will commit the image.
• The second role of the application is to look for a new update.
  • Server info is defined in compile time (in otauser.h).
  • App repeatedly calls OtaRun() until OTA process is completed.
  • App decides to accept or decline a new update based on its timestamp.
  • An accepted update will be written to flash as a "candidate" which will be verified after the MCU gets reset.
    

Loading A Pre-Built OTA Image

The following section will walk you through the steps needed to run the cloud_ota sample application using the CC32xx LaunchPad. This example is run using the cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs source code example found within the CC32xx SDK. These instructions should work for the FreeRTOS example as well. This demonstration uses the OTA sample application to load and install a pre-built image that is located on a Github CDN server. It focuses on the configuration of the OTA application.

Task 1: Configure the OTA library

1. In CCS, import the ota library project found in simplelink_cc32xx_sdk_x_xx_xx_xx/source/ti/net/ota/ccs. This is the supporting OTA library that works for all device types and RTOS. Be sure you UNCHECK the box Copy projects into workspace.

   

2. In otauser.h of the ota project, update the CDN server parameters:

   • Use the following parameters for accessing the pre-defined image on the Github server:
     • #define OTA_SERVER_TYPE   OTA_SERVER_GITHUB
     • Choose the folder with your device variant for #define OTA_VENDOR_DIR
       • "SEC_OTA_CC3220S"
       • "SEC_OTA_CC3220SF"
       • "SEC_OTA_CC3235S"
       • "SEC_OTA_CC3235SF"
   • The following definitions are under GITHUB section:
     • #define OTA_VENDOR_ROOT_DIR   "/repos/SimpleLink/CC3X20"
     • #define OTA_VENDOR_TOKEN   "SimpleLink"
   • For this demo, define OTA_SERVER_ROOT_CA_CERT as "RootCACerts_GitHub.pem". We will discuss this certificate in the next task.

   • Optionally, you may uncomment the following definition to enable the OTA library traces:

     • #define SL_ENABLE_OTA_DEBUG_TRACES
     

3. Update the JSON buffer size for storing the long GitHub URL. In the ota project, open the OtaJson.c file and update the MAX_METADATA_FILENAME definition to reserve room for the long Github URL name.

   

4. Build the ota project.

   Warning icons for CdnVendors files

   If you do not uncheck Copy projects into workspace when you import the ota library, you will see yellow warning icons in the OTA/CdnVendors/ folder of your ota project. Delete this local project and re-import with the Copy Projects into Workspace option unchecked, as shown in step 1.

   Rebuilding the OTA library

   Both the ota library and the cloud_ota example need to be rebuilt after every change to otauser.h.

   In your cloud_ota project, you can add a dependency on the ota project. This will automatically rebuild the ota library for you every time you rebuild cloud_ota.

   

Task 2: Configure the Cloud OTA example

1. Import the Cloud OTA example for your device and desired RTOS. This lab will demonstrate using the cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs example from the simplelink_cc32xx_sdk_x_xx_xx_xx/examples/rtos/CC3220SF_LAUNCHXL/demos/cloud_ota/tirtos/ccs folder.

2. Add the server's root CA certificate to the userFiles folder in your CCS project. This certificate will be a user file. For this demo, we will use RootCACerts_GitHub.pem.

   To get this certificate file, and to learn more about why this file is needed for GitHub, see the Important Notice for Customers Using GitHub for OTA Updates.

3. Add the demo OTA public key certificate (dummy_ota_vendor_cert.der) to the userFiles folder. This is available in simplelink_cc32xx_sdk_x_xx_xx_xx/tools/cc32xx_tools/ota-example-cert/. This certificate will be used to authenticate the pre-built secure OTA image for this exercise.

   We will learn more about this key pair and signing the OTA image in the next section of this lab.

   

4. Plug in your LaunchPad and build the cloud_ota project. Flash the LaunchPad to load the image that includes the application, user files, and servicepack to the device. In CCS, you can do this from the icon in the top menu.

Task 3: Complete an OTA Update

1. Open a terminal emulation program and select the XDS110 Class Application/User UART port.

   UART Configuration
   Baud rate: 115200
   Data: 8 bit
   Parity: None
   Stop: 1 bit
   Flow control: None

2. Reset the LaunchPad to run the application. The example begins by starting the device in station mode and looks for an available network. If the device cannot find a known Access Point, it enters provisioning mode. For complete steps on provisioning, see the Wi-Fi Provisioning training.

   

   After the device is successfully provisioned, it will ping the gateway until it receives the OTA command.

3. Once the application can successfully ping the gateway, press button 2 (SW2) on the LaunchPad to trigger the OTA process.

4. You should see OTA messages handling the CDN server connection, downloading content, parsing and installing it. The log below shows the flash programming messages, the platform reset, and the activation of the newly programmed image. The application commits the temporary image after a successful sanity check (pinging the gateway).

Error code -688

In the case you do not have the correct root CA certificate (or use a different CDN server), the HTTPS connection setup will fail. If the HTTPS connection to the CDN server fails due to an incorrect root certificate, the return value will be -688. You will need to find and install the right certificate.

How do I find the right certificate?

To print the name of the certificate requested by the server, replace the else-if statement of SimpleLinkSockEventHandler in cloud_ota.c with the following code:

Select text

    switch (pSock->SocketAsyncEvent.SockAsyncData.Type)
    {
        case SL_SSL_NOTIFICATION_WRONG_ROOT_CA:
            /* on socket error Restart OTA */
            UART_PRINT("SL_SOCKET_ASYNC_EVENT: ERROR - WRONG ROOT CA\n\r"); 
            UART_PRINT("Please install the following Root Certificate:\n\r");
            UART_PRINT("  %s\n\r", pSock->SocketAsyncEvent.SockAsyncData.pExtraInfo);
            SignalEvent(APP_EVENT_RESTART);
            break;

        default:
            /* on socket error Restart OTA */
            UART_PRINT("SL_SOCKET_ASYNC_EVENT socket event %d, do restart\n\r", pSock->Event);
            SignalEvent(APP_EVENT_RESTART);
            break;
    }

cloud_ota.c :: SimpleLinkSockEventHandler() - Else-if statement

It should now look like this:

Preparing An OTA Image

The following section will discuss the steps needed to run the Cloud OTA sample application using the CC32xx LaunchPad. This example is run using the cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs source code example. This demonstration focuses on how to create an OTA image.

• Compiling an MCU image and packaging it within an OTA update (TAR file)
• Uploading OTA content to a user account on a CDN server (DropBox)
• Configuring the cloud_ota with the user account parameters

Task 4: Configuring the CDN Server

1. You will need a CDN account to store the OTA image file, and we will be using DropBox for this demo. Go to the App Center and Build an app.

2. Choose a Dropbox API with App folder access. You can choose any app name.

   

3. Configure permissions and generate an access token to use in the next task.

   • In the Permissions tab, enable "file.metadata.read" and "file.content.read"
   • Before generating the token, make sure the Access Token Expiration is set "No Expiration"

   • Generate the access token and save it.

     

4. Navigate to your Dropbox files Home → Apps → your newly created apps folder. In this folder, create a directory OTA_R2_MCU_FLASH. This is the directory where we will put the OTA image file (in the next task).

Task 5: Creating the OTA Image

This task focuses on the generation of an OTA image. The image will contain an updated MCU application which will be based on the cloud_ota application.

1. In otauser.h of the ota project, update the CDN server parameters to the server type and directory name.

   • Use the following CDN server parameters:

     • #define OTA_SERVER_TYPE   OTA_SERVER_DROPBOX_V2
     • #define OTA_VENDOR_DIR   "OTA_R2_MCU_FLASH"

   • Add the access token we generated. The following is defined under the DROPBOX section:

     • #define OTA_VENDOR_TOKEN   "<Dropbox generated access token>"

   • Set OTA_SERVER_ROOT_CA_CERT as "RootCACerts.pem" for this demo.

     

     Using a custom CDN Server

     The cloud_ota demo supports Github and Dropbox. A custom vendor can also be used by defining OTA_SERVER_TYPE in ota/otauser.h as OTA_SERVER_CUSTOM.
     
     For more information, please see the OTA Application Report.

2. In cloud_ota.h, update the APPLICATION_NAME definition to "OTA APP (EX-2 Image)" as shown below and rebuild the project. We will only change the application name (the name will help us differentiate between the current app and the updated one).

   

3. Add the server's root CA certificate to the userFiles folder in your CCS project. This certificate will be a user file. For this demo, we will use RootCACerts.pem.

   To get this certificate file, and to learn more about why this file is needed for DropBox, see the Important Notice for Customers Using DropBox for OTA Updates.

4. Add the demo OTA public key certificate (dummy_ota_vendor_cert.der) to your userFiles folder. This is available in simplelink_cc32xx_sdk_x_xx_xx_xx/tools/cc32xx_tools/ota-example-cert/. This certificate will be used to authenticate the secure OTA image. This is the same certificate used in the first part of this lab.

5. Open image.syscfg and go to OTA Settings. Check Create OTA and Secured.

   You will need to select a OTA Private Key File Name. This private key will be used to sign the image. For this exercise, use the demo-only private key available in the SDK: simplelink_cc32xx_sdk_x_xx_xx_xx\tools\cc32xx_tools\ota-example-cert\dummy_ota_vendor_key.der.

   

   Alternatively, you can create your own private and public key that uses elliptic curve cryptography (ECDSA SECP256R1). This can be done using the following openssl commands:

   Generate the private key

   openssl ecparam -name prime256v1 -genkey -out ota_vendor_key.pem

   Generate the public certifcate

   openssl req -new -x509 -key ota_vendor_key.pem -out ota_vendor_cert.pem -days 730

   You may answer the Certificate Signing Request (CSR) questions or simply choose the defaults.

6. Plug in your LaunchPad. Rebuild the ota project, and then rebuild the cloud_ota project.

   Building the cloud_ota project will launch the ImageCreator tool that will generate the image containing your application, servicepack, user files, and device configurations, sign the image, and generate a TAR file in a format defined by the OTA library. The timestamp for the image will be automatically generated as the TAR file name. By default, the TAR file will be available in the MCU+Image/syscfg/sl_image/Output folder of your CCS project.

7. Locate the TAR file you created (inside MCU+Image/syscfg/sl_image/Output) and place it into the OTA_R2_MCU_FLASH directory in the CDN server (this is the DropBox directory from task 4, step 4).

   

Task 6: Running the OTA Application

1. Change the APPLICATION_NAME in cloud_ota.h back to OTA APP. This is so we can easily see in the terminal logs if the image updated successfully.

   

2. Rebuild the cloud_ota project and Flash using the icon in the menu.

3. Open a terminal emulation program such as TeraTerm and select the XDS110 Class Application/User UART port.

   UART Configuration
   Baud rate: 115200
   Data: 8 bit
   Parity: None
   Stop: 1 bit
   Flow control: None

4. Reset the LaunchPad and verify the successful execution on the terminal.

   
   

   Note that after a successful OTA sequence the new image should be triggered. You can verify this by looking at the application name.

   

Further Reading

After experiencing the OTA application, see the following resources for further assistance in development:

• CC3x20, CC3x3x Network Processor Programmer's Guide: This guide contains information on how to use the SimpleLink API for writing WLAN-enabled applications. Please refer to chapter 8 (File System) for important details on the OTA image bundle attributes.
• CC3x20, CC3x3x OTA Application Report: This document describes the OTA library for the SimpleLink Wireless MCUs, and explains how to prepare a new cloud-ready update to be downloaded by the OTA library.
• SimpleLink Wi-Fi Certificates Handling User's Guide: This guide provides an overview on generating, installing, and using certificates with the CC3x20 and CC3x3x devices.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.