FreeRTOS Labs - OTA Example for AWS IoT Core

AWS IoT CoreOTA enables simple Over-The-Air (OTA) updates through an extensible and modular set of interfaces. When properly setup, the CoreOTA 'Orchestrator' (see CoreOTA concepts & architecture) will handle the standard OTA behaviors like downloading the OTA file, parsing update metadata, and updating OTA status remotely. These functions are performed through the different interfaces which allow for customization for new fields and extensibility to new services. Using this library will allow you to easily configure OTA updates from a variety of sources and keep OTA functionality separated from any on-device application.

This repository contains the following two example OTA orchestrators. Both orchestrators use FreeRTOS, coreMQTT and IoT Jobs library.

1. Simple OTA Orchestrator: It is a simple orchestrator which checks IoT Core for an existing OTA Job, download its associated file, output the file over the command line, and report success back to IoT Core.
2. OTA Agent Orchestrator: This orchestrator is designed to mimic the OTA agent found in the old OTA repository. The OTA agent orchestrator operates by managing a state machine that tracks the current status of the download process. The state machine is influenced by receiving events that are sourced by either internal calls or the main application. The OTA agent requires a loop to be running to receive and process these incoming events before it can start.

0. Concepts and Architecture

A detailed breakdown of important concepts and architectural decisions can be found here.

1. Demo Prerequisites

• A personal computer running a POSIX operating system (Linux, MacOS, or WSL)
  • (Optional) Use the Nix package manager to supply software dependencies
  • A C99 compiler (tested with Clang v11.1.0, GCC v9.4.0, and Apple clang v14.0.0)
  • CMake v3.16+ (tested with v3.24.3 and v3.26.1)
  • OpenSSL (tested with v1.1.1t and v1.1.1u)
• An AWS account with with administrative access to use for AWS IoT Core

2. Demo Setup

2.1 Setup AWS IoT Core

To setup AWS IoT Core, follow the AWS IoT Core Setup Guide. The guide shows you how to sign up for an AWS account, create a user, and register your device with AWS IoT Core. After you have followed the instructions in the AWS IoT Core Setup Guide, you will have acquired the following items:

• A device Endpoint
• an AWS IoT Thing (and associated ThingName)
• PEM-encoded device certificate
• PEM-encoded private key
• PEM-encoded root CA certificate

The root CA certificate can also be downloaded here. The simulator must be provided with these entities in order for it to connect with AWS IoT Core.

2.2 Perform one-time setup of OTA cloud resources

Before you create an OTA job, the following resources are required. This is a one time setup required for performing OTA firmware updates. Make a note of the names of the resources you create, as you will need to provide them during subsequent configuration steps.

• An Amazon S3 bucket to store your updated firmware. S3 is an AWS Service that enables you to store files in the cloud that can be accessed by you or other services. This is used by the OTA Update Manager Service to store the firmware image in an S3 "bucket" before sending it to the device. Create an Amazon S3 Bucket to Store Your Update.
• An OTA Update Service role. By default, the OTA Update Manager cloud service does not have permission to access the S3 bucket that will contain the firmware image. An OTA Service Role is required to allow the OTA Update Manager Service to read and write to the S3 bucket. Create an OTA Update Service role.
• An OTA user policy. An OTA User Policy is required to give your AWS account permissions to interact with the AWS services required for creating an OTA Update. Create an OTA User Policy.
• Create a code-signing certificate. The demos support a code-signing certificate with an ECDSA P-256 key and SHA-256 hash to perform OTA updates.
• Grant access to Code Signing for AWS IoT.

2.3 Build the coreOTA_Demo Binary

On your personal computer, open a terminal and issue the following commands:

# optional command - skip if you do not have Nix installed
nix develop --extra-experimental-features "nix-command flakes"

mkdir build
cd build
cmake ..

To build Simple OTA Orchestrator Demo

make coreOTA_Demo

To build OTA Agent Orchestrator Demo

make coreOTA_Agent_Demo

3. Run the OTA Demo

3.1 Create an OTA Update in AWS IoT Core

Follow the steps to Create an OTA Update with the AWS IoT Core Console. Apply the following options:

• When prompted, select the S3 bucket, OTA update service role, and code-signing profile you made in 2.2
• Under Sign and choose your file, select "Sign a new file for me".
• Under Select the protocol for the file transfer, select "MQTT"
• Under Pathname of code signing certificate on device, enter an arbitrary string (e.g. "test")

3.2 Run the simulator

After you've created your OTA update, start the simulator by using the following command in your build/ directory:

To run Simple OTA Orchestrator Demo

./coreOTA_Demo {certificateFilePath} {privateKeyFilePath} {rootCAFilePath} {endpoint} {thingName}

To run OTA Agent Orchestrator Demo

./coreOTA_Agent_Demo {certificateFilePath} {privateKeyFilePath} {rootCAFilePath} {endpoint} {thingName}

3.3 Verify successful OTA in the AWS IoT Core Console

After the simulator stops printing output, check the IoT Core Console to verify that the OTA Job you created is marked as "Successful".

4. Run the Unit Tests

4.1 Running the OTA Parser Unit tests

The unit tests are broken out by the 'module' they reside in (aka the /lib folder) and can be executed per module. To run the OTA parser unit tests you'll run the following commands

From here you can build the unit tests...

cd lib/iot-core-jobs-ota-parser
cmake -B build -S test
make -C build

Once built, the test executables can be found under the lib/iot-core-jobs-ota-parser/build/bin/tests/ directory

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT License.