Over The Air Update Guide

Table of Contents

Abstract

Over-The-Air (OTA) update is a wireless delivery of new software updates or configurations to an embedded device. Using the concept of an identity key (IRK) within the Internet-of-Things (IoT) world, OTA proves to be an efficient way of distributing firmware updates or upgrades.

This document describes the OTA library for the SimpleLink™ Wi-Fi® CC3x20 family of devices from Texas Instruments™ and explains how to prepare a new cloud-ready update to be loaded by the OTA library.

The SimpleLink MCU portfolio offers a single development environment that delivers flexible hardware, software and tool options for customers developing wired and wireless applications. With 100 percent code reuse across host MCUs, Wi-Fi® , Bluetooth® low energy, Sub-1 GHz devices and more, choose the MCU or connectivity standard that fits your design. A one-time investment with the SimpleLink software development kit (SDK) allows you to reuse often, opening the door to create unlimited applications. For more information, visit: www.ti.com/simplelink.

1 Introduction

The OTA library for the SimpleLink CC3x20 family of solutions simplifies the effort of MCU applications to access the cloud and download new upgrades (such as new firmware applications, service packs, and user files) in a secured and fail-safe manner, while ensuring the integrity of the process.

The OTA library exposes a simple API set:

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

1.1 System Block Diagram

Figure 1 shows the block diagram of the OTA system:


Figure 1

Fig. 1: OTA System Diagram

The OTA library supports the following cloud CDN vendors:

The OTA library implements a simple HTTP client (TCP) to connect to the CDN server. This client can be configured by the host application as follows:

The software upgrade application and user files should be put in an archive tar file. By default, all files are non-secured and fail-safe. The vendor can change the attributes of a file (such as secured, signature, certificate file name, and so forth) by adding entry to a command file (ota.cmd), which is in JSON format and included in the tar archive.

1.2 OTA Software Block diagram

Figure 2 shows the block diagram of the OTA software:


Figure 2

Fig. 2: OTA Software Block Diagram

1.3 Terminology and Abbreviations

Table 1 lists terminology and abbreviations used in this documentation.


Table 1: Terminology

Term Description
OTA Over-the-Air
CDN Content delivery network. In the relation to the OTA lib, CDN relates to the servers that contain the new package.
ACM Account manager
CSP Cloud storage provider
HTTP Hypertext transfer protocol
URL Uniform resource locator
URI Uniform resource identifier
REST Representational state transfer
JSON JavaScript object notation

2 High-Level Description for Adding OTA Capability

Existing host applications can be expanded to have OTA capability by using the OTA library and the OTA sample application as a reference. The OTA sample application works on the CC3220 and CC3120 devices with an MSP432™ microcontroller (MCU) as the host.

2.1 Software Installations and Downloads

Follow the SDK Getting Started Guide (CC3120 or CC3220) to prepare development environment as follows:

  1. Download the newest version of Code Composer Studio™ (CCS).
  2. Download the latest CC3220SDK or CC3120SDK.
  3. Download the latest UniFlash tool, select CC3220 device, and start the Image Creator tool inside.
  4. Install the SimpleLink Starter Pro on your mobile phone.

2.2 OTA Process Briefly

The following steps explain, at a high level, the steps to prepare and run the OTA application:

  1. Create a developer account in the selected CDN server (Dropbox, Github, or custom).
  2. Open the OTA sample application and change the selected CDN server info.
  3. Compile the OTA sample application.
  4. Create a TAR file with the host application and all other required files.
  5. Upload the TAR file into the CDN server.
  6. Open the UART terminal to view the application logs.
  7. Using the Image Creator, prepare an image containing the OTA application, and program the device.
  8. When the host application starts the OTA process, download and run the new host application.

NOTE: Replacing the TAR file in the CDN server with a newer one should re-invoke the OTA download.

3 Running the Default OTA Sample Application

The OTA sample application provides a basic application with Cloud OTA and provisioning capabilities. This application is described in more detail in Section 5 and can be used as a basis for developing a target application.
The Cloud OTA sample application supports:

The following sections are for specific a CC3220 variant and OS; change the names for a different OS or CC3200 variant. For the CC3220R, use the name CC3200S.

NOTE: The OTA library produces compilation errors. Open a developer account on Dropbox or Github, and get a token to be used in <cc3220_sdk_install_dir>\source\ti\net\ota\otauser.h. For Dropbox cloud, see Section 8.1 and Section 4.1.

3.1 Building the Cloud OTA CCS Project for CC3220SF

Install the CC3220 SDK and import two CCS projects:

  1. Import the OTA library project using CCS IDE from the following location:  <cc3220_sdk_install_dir>\source\ti\net\ota\ccs

    NOTE: This project should not be copied to the CCS workspace.

  2. Import the Cloud OTA project using CCS IDE from the following location, according to the connected CC3220 flavor and the desired OS (CC3220S or CC3220SF):
    • For FreeRTOS and CC3220SF devices: <cc3220_sdk_install_dir>\examples\rtos\CC3220SF_LAUNCHXL\demos\cloud_ota\freertos\ccs
    • For TI-RTOS and CC3220SF devices: <cc3220_sdk_install_dir>\examples\rtos\CC3220SF_LAUNCHXL\demos\cloud_ota\tirtos\ccs
  3. Configure the cloud server:
    • Open a developer account on Dropbox or Github. For instructions, see Section 8.1 and Section 4.1.
    • Copy the given cloud server token into the OTA lib user configuration file in: <cc3220_sdk_install_dir>\source\ti\net\ota\otauser.h


  4. Configure OTA special compilation flags:

    • OTA lib : Define SL_ENABLE_OTA_DEBUG_TRACES in otauser.h for detailed OTA library debug prints.
    • OTA project:
      • Define DISABLE_OTA_SWITCH_TRIGGER in cloud_ota.c to start the OTA process after 5 pings,
        and not to wait for an external trigger (CC3220LP button).
      • Define OTA_LOOP_TESTING to continue running OTA attempts when the return value is NO_UPDATE, OLDER_VERSION.
  5. Compile the project and produce a cloud_ota.bin file to be programmed by the UniFlash.
    1. Build OTA library project – ota
    2. Build OTA sample application project – cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs
    3. Output bin file is located in the projects workspace directory <cc3220_sdk_workspace_dir>\cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs\Debug\cloud_ota_CC3220SF_LAUNCHXL_tirtos_ccs.bin

    NOTE: This section demonstrates building the project with CCS. Building the OTA lib and application using a different tool chain is similar. For more information, please advise the Quick start guide.

3.2 Program by UniFlash Tool With Image Creator Inside

The following instructions describe how to program the device.

  1. Open UniFlash and select CC3220 device, as shown in Figure 5:


    Figure 5

    Fig. 5: Choose Your Device

  2. Start Uniflash tool and select New Project, fill the project name, and click create project (for debug mode, the device must be opened first in development mode).

  3. Go to: Files → Trusted Root-Certificate Catalog, and select <cc3220_sdk_install_dir>\tools\cc32xx_tools\certificateplayground\certcatalogPlayGroung20160911.lst, as shown in Figure 6 (do not use the default).


    Figure 6

    Fig. 6: Trusted Root-Certificate Catalog

  4. Now, go to: Files → Service Pack, and select the latest service pack (the bin file is located at: <cc3220_sdk_install_dir>\tools\cc32xx_tools\servicepack-cc3x20), as shown in Figure 7:


    Figure 7

    Fig. 7: Service Pack File Name

  5. Go to: Files → User Files, and select the following, as shown in Figure 8:


    Figure 8

    Fig. 8: User Files

IMPORTANT !: OTA certificate MUST be a standard x509 valid certificate. The certificate structure is not validated before installation, and must be checked by the user beforehand.

  1. Configure the device to STA role.

  2. Click Create OTA to produce a tar file to be put in the cloud server. Once you click Create OTA, a message window would pop, as shown in Figure 10. Here, a vendor provides a key (secp256r1 elliptic curve private key) with which the OTA meta-data files would be signed. Provided with the SDK, is a dummy private key, for demonstration purposes, here: <cc3220_sdk_install_dir>\tools\cc32xx_tools\certificate-playground\ota-example-cert\dummy_ota_vendor_key. For security reasons it is very recommended not to skip this option. The output file 2016091917_CC3220SF_CC3220SF_OTA.tar should be put in the cloud directory, as shown in the image below:


    Figure 10

    Fig. 10: OTA cmd signing
  3. Configure in otauser.h:

  4. Click on Program Image (Create and Program), as shown in Figure 11. The image is now programmed to the device.


    Figure 11

    Fig. 11: Generate Image

3.3 Running a Sample Application

After programming the OTA sample application in the device and putting the OTA tar file in the cloud, press reset to start the OTA process. The major steps that the sample application executes are as follows:

  1. Connect to AP through an existing profile, or by the provisioning process.
  2. Send pings and wait for the CC3220LP button click to start the OTA.
  3. Configure the OTA library with the CDN server details.
  4. Run the OTA process, initiated from external trigger (button on the CC3220LP board):
    1. Connect to the CDN HTTPS server.
    2. Request for directory content, and download the TAR archive file.
    3. Extract TAR archive files, including the file mcuflashimg.bin, into the serial flash.
  5. After the download is finished, set IMAGE_TESTING mode and reset the MCU.

  6. On successful system tests, set IMAGE_COMMIT and continue running the new MCU image.

    NOTE: A new OTA process can be initiated again by the user. The download process is only re-invoked if a new TAR file is uploaded to the CDN or when the user configures it to ignore the newer version check by #define OTA_LOOP_TESTING in cloud_ota.c file.

4 Adding OTA Capability Into an Embedded Software Application

This application note focuses on showcasing the ability of the CC3220 device to receive firmware updates and any related files over an Internet-enabled Wi-Fi interface.

4.1 Updating OTA Definitions

The OTA library has support for the following CDN vendors:

This section describes how to use one of these CDN vendors. To add support for another CDN vendor, refer to Section 10. To run the OTA lib, a vendor must have an account in one of the supported CDNs to distribute the software updates.
For more information how to open an account, refer to Section 8. The CDN setting, including the credentials, are updated in the otauser.h file with the selected directory and token.

4.1.1 otauser.h

This file is found here: <cc3220_sdk_workspace_dir>\source\ti\net\ota. This file allows the user to configure the following options for the OTA process:

<picture does here

The host application can set the server IP address in OTA_SERVER_IP_ADDRESS instead of server name.
By default, the lib requires server authentication and domain name verification. From a security perspective, the previous requirements are essential, and TI recommends using this mode. If the custom server is not secured, or server authentication and domain name verification are not required, OTA_SERVER_ROOT_CA_CERT can be undefined.

4.2 Using OTA lib in the Main Application

Figure 14 shows a basic possible flow of a host application running the OTA.


Figure 14

Fig. 12: Basic OTA Application Flow Chart

4.2.1 Initiate the OTA Library

The host application must define a global buffer for the use of the OTA lib, and provide this buffer while it initiates the OTA:

4.2.2 Running the OTA Process

The OTA process runs in steps side-by-side with the main application. The user should continue to call the OTA process as long as the return value is OTA_RUN_STATUS_CONTINUE. The following example shows a simple main loop of a non-OS application:

The possible OTA process return values are:

4.2.2 OTA Commit Process

Upon a successful completion of the OTA process (Status RUN_STAT_DOWNLOAD_DONE), all software upgrade package files are stored in the serial flash in bundle mode, but are still not in use. The host application should move the bundle into IMAGE_TESTING mode by calling sl_Stop() with a timeout different than 0, and then resetting the MCU.

After the reset, the bundle files are used and the application should check if the new image works correctly (for example, connect to a network, run some network tests, and so forth). On a successful system test, the application should check if the image is in WAIT_FOR_COMMIT mode, and call the OTA lib to perform the commit. After the commit, the files are used and a rollback is not allowed.
On system test failure, the application must reset the MCU to perform a rollback of all files to the previous image:

5 Sample OTA Application

The sample OTA application is implemented by a state machine (SM). The SM is started on response to sl_Start(), and driven by NWP events and application events, as shown in Table 2 and Table 3.

Table 2: OTA App States

OTA App States Description
APP_STATE_STARTING Waiting for INIT_COMPLETE event from the NWP (after calling sl_Start()).
APP_STATE_WAIT_FOR_CONNECTION Waiting for WLAN_CONNECTED event from the NWP - Connection runs if a profile is saved on the device.
APP_STATE_WAIT_FOR_IP Waiting for IPV4_ACQUIRED event from the NWP.
APP_STATE_PROVISIONING_IN_PROGRESS Waiting for PROVISIONING_SUCCESS event. Provisioning starts if no profile, or if connection failed.
APP_STATE_PROVISIONING_WAIT_COMPLETE Waiting for PROVISIONING_STOP event, provisioning stop indicate complete loop close of provisioning connection
APP_STATE_PINGING_GW This is the main application state. In this state, the application sends ping requests to the gateway. Waiting for PING_COMPLETE event from the NWP and initiate another ping request (sl_NetAppPing())
APP_STATE_OTA_RUN Keep Calling OtaRunStep() and check return status. On download completion, reset the MCU to test the new image.
APP_STATE_ERROR Fatal error state – halt.

Table 3: NWP Events

NWP Event OTA APP event and action
GeneralEvent SL_ERROR_LOADING_CERTIFICATE_STORE*
Otherwise: SignalEvent(APP_EVENT_ERROR)
WlanEvent SL_WLAN_EVENT_CONNECT: SignalEvent(APP_EVENT_CONNECTED)
SL_WLAN_EVENT_DISCONNECT: SignalEvent(APP_EVENT_DISCONNECTED)
Otherwise: SignalEvent(APP_EVENT_ERROR)
SL_WLAN_EVENT_PROVISIONING_STATUS: According to status :
    SignalEvent(APP_EVENT_PROVISIONING_STARTED)
    SignalEvent(APP_EVENT_PROVISIONING_SUCCESS)
    SignalEvent(APP_EVENT_PROVISIONING_STOPPED)
    SignalEvent(APP_EVENT_ERROR)
FatalErrorEvent Waiting for IPV4_ACQUIRED event from the NWP
NetAppEvent SL_NETAPP_EVENT_IPV4_ACQUIRED: SignalEvent(APP_EVENT_IP_ACQUIRED)
SL_NETAPP_EVENT_IPV4_LOST: SignalEvent(APP_EVENT_DISCONNECT)
SL_NETAPP_EVENT_DHCP_IPV4_ACQUIRE_TIMEOUT: SignalEvent(APP_EVENT_DISCONNECT)
Otherwise: SignalEvent(APP_EVENT_ERROR)
HttpServerEvent SignalEvent(APP_EVENT_ERROR)
SockEvent SL_SOCKET_TX_FAILED_EVENT: SignalEvent(APP_EVENT_RESTART)
Otherwise: SignalEvent(APP_EVENT_ERROR)

  1. *Ignored. ↩

5.1 Application State Machine

Figure 13 shows the block diagram of the OTA system:


Figure 13
Fig. 13: Sample Application State Machine

5.2 Provisioning Connection

The host application uses an existing profile to connect to an AP. If no profile exists, or it is unable to connect to any of the existing profile, the host application has the option to add a new profile using the TI provisioning process.

The provisioning process automatically starts if no connection is available. The user should use the Mobile Provisioning application to add a new profile.

More about provisioning can be found in the Provisioning Application Report.
More about the mobile application can be found in the Provisioning User Guide.

5.3 OTA External Trigger

After establishing a connection, the host application continues to check the connection to the AP endlessly (PING).

To start the OTA process, initiate an external trigger. The external trigger is defined according to the different platform used:

After the external trigger is initiated, the host application starts the OTA process.

6 Creating OTA Software Upgrade Package

The software upgrade package is an archive tar file (not compressed) that contains all relevant files. The files should be placed in hierarchy directories, as shown in Figure 14.


Figure 14

Fig. 14: Directory Hierarchy

The name of the root directory should contain the package version number. This name should be constructed of numerical digits that can be compared to the existing package version number, and based on that to determine if an upgrade is required. The example above uses the date/time numeric number with the format: YYYYMMDDHH.

The directories 0, 1, and 2 are used to set the package files download order:

The files and directory names should have the same name as in the serial flash. For files in the root directory, the leading slash is removed (certificate filename limitation). The base tar file should be produced using the UniFlash tool and clicking Create OTA, as shown in Figure 15. This base tar file only has the MCU image and the service pack.


Figure 15

Fig. 15: Create OTA

The user can add user files to the existing tar file by un-archiving the files into local directory, adding the user files,
and archiving the directory into the tar file.

Limitations:

7 Preparing ota.cmd Metadata File

The ota.cmd file is the first file in the OTA archive files, and it is in JSON array format. Each JSON object represents one file in the archive. All files must have a JSON object in the ota.cmd.

The metadata supports the following JSON tokens:

The following code example contains object for a secured file, FileId03.txt, with a signature and certificate. The second object is a service pack file with a signature. The third object is an mcu image, with a signature and certificate. The last object is a certificate with which ota.cmd was signed.

[
    {
        "digest":"34941765501d16a4ab776c3a74d89945f1a2575c5893069f62ffbe803f344549",
        "certificate": "dummy-trusted-ca-cert",
        "signature_base64": "kc8XfFOfMfr4HBJiPxTRHyb99d2uOoICme0AYU94+...",
        "secured": 1,
        "bundle": 0,
        "filename": "/local/FileId03.txt"
    },
    {
        "digest":"251b5394428e5b82a02c598199055f19ea945d9803f73a850588cc12f6eec684",
        "certificate":"",
        "signature_base64": "EEC6GZG1Oq6Agigmb2f9ny9rNK2Mg9hFClpgMhd4jCW/...",                            
        "secured": 1,
        "bundle": 1,
        "filename": "/sys/servicepack.ucf"
    },
    {
        "digest":"d89cdff2f5c7784fa2551f265f0ebe16a7179f51fc6cd36e78ecee7285ec3075",
        "certificate": "dummy-root-ca-cert",
        "signature_base64": "dRTARlzLFKAog34ZUareCmo9j2lrHnvc+v3qqW9C/...",
        "secured": 1,
        "bundle": 1,
        "filename": "/sys/mcuflashimg.bin"
    },
    {
        "digest":"a160b855d7a00a6002922181377249a80ecd6a738d23e1dd8976c8bb7fad1bcb",
        "certificate":"",
        "signature_base64":"",
        "certificate": "dummy-root-ca-cert",
        "secured":0,
        "bundle": 0,
        "filename":"dummy_ota_vendor_cert.der"
    }  
]

8 Distributing Software Upgrades Through a Cloud Service

8.1 Getting Started With the e Dropbox™ Cloud Delivery Network (CDN)

The purpose of the following steps is to describe working with the Dropbox server to run the cloud OTA application. Before following the next instructions, you must create a Dropbox account.

  1. On the main page, open the Developers tab, as shown in Figure 16.


    Figure 16

    Fig. 16: Developers Tab

  2. Choose Create your app, as shown in Figure 17:


    Figure 17

    Fig. 17: Create Your App

  3. Choose Dropbox API. For access type, choose App folder, as shown in Figure 18, and name the application (for example, “OTA_R2”), then press Create app.


    Figure 18

    Fig. 18: Create App

  4. Select the App key and App secret, as shown in Figure 19.


    Figure 19

    Fig. 19: App Key

  5. Generate the access token, as shown in Figure 20.


    Figure 20

    Fig. 20: Generate Access Token
  6. Authorize the app with the previously generated token, app key, and secret.
  7. After the app is authorized, save the authorization bearer Token Key. This is the OTA Vendor Token which should be placed in the otauser.h file.

  8. An Apps folder appears at the main page, as shown in Figure 21.


    Figure 21

    Fig. 21: Apps Folder

  9. Open Apps. The previously created folder should appear. Open the folder, as shown in Figure 22.


    Figure 22

    Fig. 22: OTA Vendor Directory

  10. Create new folder and name it with the same name which appears in the otauser.h file under the define OTA_VENDOR_DIR. Put the TAR file here. For information on how to create a TAR file, refer to Section 6.


    Figure 23

    Fig. 23: Edit Marked Fields

  11. Build the cloud OTA project, and run it.

8.2 GitHub CDN Getting Started

The following steps describe how to use GitHub CDN.

  1. Create an account at gitHub.

  2. Create new repository by pressing on “Create new…” (see Figure 24).


    Figure 24

    Fig. 24: Create New

  3. Choose New Repository (Figure 25).


    Figure 25

    Fig. 25: New Repository

  4. Name the repository, select public or private access types, and press Create repository, as shown in Figure 26.


    Figure 26

    Fig. 26: Create New Repository

  5. Save the repository URL, as shown in Figure 27. An example would be: https://github.com/<username>/<repository_name>


    Figure 27

    Fig. 27: Save Repository

    Following instructions shows how to activate a GitHub repository using Git GUI on the user’s PC. Download the Git GUI from here: https://git-for-windows.github.io/.
  6. Create a directory on your PC.

  7. Right-click to open Git options, and choose Git Bash Here, as shown in Figure 28:


    Figure 28

    Fig. 28: Save Repository

  8. Type the following at the Git bash window:

    git init
git clone https://github.com/<username>/<repository>
git add cd <user directory>
git add <user tar file> 
git commit -a -m 'add OTA …’
git remote
git push origin master
  9. Enter the username and password. Now the SP TAR file can be seen in github.

  10. After the GitHub CDN repository is activated, open a cloud OTA example application and edit the otauser.h file, as shown in: Figure 29. Uncomment OTA_SERVER_GITHUB:


    Figure 29

    Fig. 29: Set Server Name in otauser.h

    Edit the fields shown in Figure 30.

    Figure 30

    Fig. 30: Set Directory in otauser.h

  11. Build the relevant cloud OTA application, and run.

9 Local Link Support

OTA on a local link is done from a local mobile device, not from the cloud. Part of the OTA library can be used to support OTA on a local link network. The application gets the archive file chunks using a NetApp API from a local mobile device, and uses only the OtaArchive and OtaJson modules to handle the archive files chunks, processes them, and stores them on the requested files in the NWP file system.

10 Support New CDN Vendor

The OTA lib supports two CDN vendors: Dropbox and Github. A vendor can use another CDN server. This chapter describes how to define this custom CDN.

10.1 otauser.h

Add the CDN to the list and define it as the selected server:

Add custom vendors defines section:

The host application can skip the GetHostByName() and define the server IP address in OTA_SERVER_IP_ADDRESS. If the custom server does not support server authentication and domain name verification, OTA_SERVER_ROOT_CA_CERT should be undefined.

10.2 ota/source/CdnVendors/Custom.c

Add the file and implement the following functions (see the example in Dropbox.c and in Github.c):

  1. CdnCustom_SendReqDir: Send a directory tree request using the custom server name, the custom vendor directory, and the custom vendor token.
  2. CdnCustom_ParseReqDir: Parse the directory tree reply from the custom server, and find for each file two tokens:
    • custom_file_size - The file size
    • custom_file_name - The file name in the list.
  3. CdnCustom_SendReqFileUrl: Send a file URL request to the custom server using the server name, the requested file name, and the custom server token.
  4. CdnCustom_ParseRespFileUrl: Parse the file URL response from the custom server, and find the URL token:
    • custom_file_url - The file URL
  5. CdnCustom_SendReqFileContent: – Send a file content request from the custom file server.

10.3 ota/source/CdnVendors/CdnVendors.h

Add custom vendor macros: