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:

Using the Cloud OTA example to load and update a pre-built image
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

Completed material

Software

Code Composer Studio v8.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 v2.40.00.05 or newer
UniFlash v4.6.0 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

API: Application Program Interface
CDN: Content Delivery Network
MCU: Microcontroller Unit
NWP: Network Processor
OTA: Over The Air
PCB: Printed Circuit Board

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 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 UniFlash 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 local flash file system in 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 an 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 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: Preparing the OTA application

In CCS, import the Cloud OTA example for your device and desired RTOS. This lab will demonstrate using the cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs example (simplelink_cc32xx_sdk_x_xx_xx_xx/examples/rtos/CC3220SF_LAUNCHXL/demos/cloud_ota/tirtos/ccs).
You also must import the ota 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 to uncheck Copy projects into workspace.
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. Update the file paths and link to the location of your ota library binary.
How do I update file paths and link to libraries?
Update the path for each of the CdnVendors files.

In your ota project, open the properties (Left click → Properties) and navigate under Resource to Linked Resources and the Linked Resources tab.

For each file with an invalid location, select the file and press the Edit button to replace the PROJECT_LOC project variable with ORIGINAL_PROJECT_ROOT.

Be sure to press OK to save your changes. The warning symbol next to each file should disappear and you will be able to compile the library.

Link your cloud_ota application to the location where your ota library binary will be built (instead of it residing in the SDK). In the cloud_ota project, go to Properties → Build → ARM Linker → File Search Path → Include library file... and change the ota.a reference to ${WORKSPACE_LOC}/ota/Release/ota.a. This will link to the OTA library built in your CCS workspace.
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
  - #define OTA_VENDOR_DIR "SEC_OTA_CC3220SF"
- The following definitions are under GITHUB section:
  - #define OTA_VENDOR_ROOT_DIR "/repos/SimpleLink/CC3X20"
  - #define OTA_VENDOR_TOKEN "SimpleLink"
- We will find the correct value for OTA_SERVER_ROOT_CA_CERT in the next task. For now, just set it to one of the root CA certificates that is programed on your flash (e.g. dummy-root-ca-cert).
- Optionally, you may uncomment the following definition to enable the OTA library traces:
  - #define SL_ENABLE_OTA_DEBUG_TRACES
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.
Rebuild the ota project then rebuild the cloud_ota project.

Rebuilding the OTA library

You will need to rebuild the ota library and cloud_ota example after every change to otauser.h.

Task 2: Finding a Root Certificate

In this step, we will find the Certificate Common Name necessary to pass GitHub's SSL authentication. We will install this certificate (in DER format) as a user file in the device flash. To find the most up-to-date Root CA certificate, add the following code in the else-if statement of SimpleLinkSockEventHandler in cloud_ota.c.
```
 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:

Error code -688

In the case you do not have the correct 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.
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
Rebuild the ota project then rebuild the cloud_ota project. Run the cloud_ota application using the CCS Debugger. The example begins by starting the device in station mode and looks for an available network.

The screen capture demonstrates the case that a device cannot find a known access-point and enters the provisioning mode. For more information on provisioning, see the Wi-Fi Provisioning training.

Issues with CCS Debugger

Your device will need to be in development mode to use the CCS debugger. If you are unfamiliar with the UniFlash ImageCreator tool or how to put the LaunchPad in development mode, please see the UniFlash ImageCreator Basics lecture.
The screenshot below shows a successful AP connection, followed by successful PING sessions. Now you can press button 2 (SW2) on the board to trigger the OTA process.

Note that the following log was taken after SL_ENABLE_OTA_DEBUG_TRACES was enabled (in ota/ota_user.h) so it includes extra OTA messages.
When the LaunchPad attempts the OTA process, you will see an error message similar to the following screenshot. Make note of the complete name printed after Please install the following Root CA Certificate:.
You can search this certificate name online and download it, or you can find it using your browser's settings. For example in Chrome, go to Settings → Advanced → Privacy and security → Manage Certificates → Trusted Root Certification Authorities. If your browser has navigated to github.com before, search in the list for the certificate name we printed to the terminal earlier. Export it in DER format.
Update the OTA_SERVER_ROOT_CA_CERT definition in ota/otauser.h. This is similar to the step we completed in task 1.

Task 3: Complete an OTA Update

Create a new UniFlash ImageCreator project and set the CC32xx to development mode. Add the entire "dummy" certificate chain (i.e. dummy-trusted-cert, dummy-trusted-ca-cert and dummy-root-ca-cert), playground Trusted Root-Certificate Catalog, and latest service pack.
Add the Root CA certificate (in DER format) that we found earlier as a user file.
Add the demo OTA public key certificate dummy_ota_vendor_cert.der as a user file. This is available in simplelink_cc32xx_sdk_x_xx_xx_xx/tools/cc32xx_tools/ota-example-cert/. This certificate will be used to authenticate a pre-built secure OTA image signed by the corresponding private key for this lab.

The default certificate name is defined by OTA_CERTIFICATE_NAME in OtaArchive.c. (If a different certificate is used, the OTA_CERTIFICATE_NAME definition should be updated

We will learn how to generate a key pair and use UniFlash to sign the OTA image with the private key in the next section of this lab: Preparing an OTA Image.
Connect the LaunchPad and Generate and Program the image.
Rebuild the ota project then rebuild the cloud_ota project. Open a terminal emulation program as before. Run the cloud_ota application using the CCS Debugger.
The capture below shows the successful completion of OTA process. Note that the screenshot below skipped most of the OTA messages (dealing with CDN server connection, downloading content, parsing and installing it). This log below shows the flash programming messages, the platform reset, and the activation of the newly programmed image (this example pre-built image contains a version of the OTA_NONOS application). After the first successful ping session, the temporary image gets committed.
Results
- The OTA tar file name contains the timestamp (date and hour) of its creation. Only an update with a newer timestamp than the one currently stored in flash will be loaded and installed.
- The first OTA update after using UniFlash ImageCreator will always work since it does not program any timestamp.

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 is focused on creation of an OTA image.

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

Task 4: Compiling and 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.

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).
Create a new UniFlash ImageCreator project and set the CC32xx to development mode. Add the entire "dummy" certificate chain (i.e. dummy-trusted-cert, dummy-trusted-ca-cert and dummy-root-ca-cert), playground Trusted Root-Certificate Catalog, and latest service pack.
Add any additional user files. You will need to add the dummy_root_ca_cert_key which is used during provisioning. You will also need a certificate for the CDN server following the steps in task 2 and 3. For this demo, we are using DropBox.
Add your newly compiled binary (cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs.bin) as an MCU image. You can find this binary in your workspace (<workspace>/cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs/Debug/)
Go to Generate Image and select Create OTA.

You will need to select a OTA Private Key File Name. The private key will be used to sign the image.

You may use the demo-only private key which is available in the SDK: simplelink_cc32xx_sdk_x_xx_xx_xx\tools\cc32xx_tools\ota-example-cert\dummy_ota_vendor_key.der.

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

The tool will sign the binary image and will generate a tar file in a format defined by the OTA library. The timestamp for the image will be automatically generated as well.

Task 5: Creating and Configuring the CDN server

You will need a CDN account to store the new OTA file, and we will be using DropBox for this demo. Open the DropBox Developers tab from the main page or go to dropbox.com/developers and select Create your app.
Choose a Dropbox API with App folder access. You can choose any app name.
Generate an access token and save it.
Navigate to your Dropbox files home → Apps → your newly created apps folder. In this folder, create a directory OTA_R2_MCU_FLASH. Locate the OTA image you created in Task 4 and place it into the OTA_R2_MCU_FLASH directory.
In ota/otauser.h, update the CDN server parameter.
- 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. (See task 2. You may have to run the same debug session to find the new root CA certificate for Dropbox.)
  
  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.

Task 6: Running the OTA Application

Before rebuilding the application, change the OTA version (APPLICATION_NAME in cloud_ota.h) back to OTA APP (see task 4, step 1).
Rebuild the cloud_ota project, and add your new binary as an MCU image and program it to the LaunchPad.
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
Reset the LaunchPad and verify the successful execution on the terminal.

Note that after a successful OTA sequence the new image should be triggered. It can be monitored through the application name.

Introduction

Prerequisites

Completed material

Software

Hardware

OTA Overview

OTA Concept

OTA System Diagram

SimpleLink OTA Library (`ota`)

OTA Library API

OTA Sample Application

Loading A Pre-Built OTA Image

Task 1: Preparing the OTA application

Warning icons for CdnVendors files

How do I update file paths and link to libraries?

Rebuilding the OTA library

Task 2: Finding a Root Certificate

Error code -688

Issues with CCS Debugger

Task 3: Complete an OTA Update

Results

Preparing An OTA Image

Task 4: Compiling and Creating the OTA Image

Generate the private key

Generate the public certifcate

Task 5: Creating and Configuring the CDN server

Using a custom CDN Server

Task 6: Running the OTA Application

Further Reading

Technical support

Introduction

Prerequisites

Completed material

Software

Hardware

OTA Overview

OTA Concept

OTA System Diagram

SimpleLink OTA Library (ota)

OTA Library API

OTA Sample Application

Loading A Pre-Built OTA Image

Task 1: Preparing the OTA application

Warning icons for CdnVendors files

How do I update file paths and link to libraries?

Rebuilding the OTA library

Task 2: Finding a Root Certificate

Error code -688

Issues with CCS Debugger

Task 3: Complete an OTA Update

Results

Preparing An OTA Image

Task 4: Compiling and Creating the OTA Image

Generate the private key

Generate the public certifcate

Task 5: Creating and Configuring the CDN server

Using a custom CDN Server

Task 6: Running the OTA Application

Further Reading

Technical support

SimpleLink OTA Library (`ota`)