While this demo uses the AWS IoT OTA update service, FreeRTOS is generic MIT licensed open source software, and can
be used with any OTA mechanism that works for you. We do however recommend
you digitally sign your firmware whichever OTA method you choose. That way the devices that receive the new executable image can
verify it came from an authorized source and has not been been modified. You can use
Code Signing for AWS IoT
to sign your firmware or you can sign with your own code-signing tools.
Simple OTA Orchestrator: This demonstration orchestrator performs the minimal functionality for an OTA update - checking
IoT Core for an OTA Job, downloading the firmware file, and reporting back completion to IoT Core. The Simple OTA Orchestrator will print out
the OTA file contents to the command line.. This demo use FreeRTOS, coreMQTT, MQTT file streams and IoT Jobs library
Simple OTA orchestrator code is organized in ota_demo.h and ota_demo.c files. These files can be
In this demo there are two tasks, OTA task and MQTT task.
This task performs the following operations:
Check if there is any pending OTA job.
If there is any pending OTA job, then download the Job document. It also updates the job status on AWS IoT core.
Parse the downloaded job document and extract the parameters need to download the new firmware.
Pass the extracted parameters to the MQTT stream downloader to initialize it.
MQTT file stream downloader then starts downloading the new firmware by requesting data blocks.
Once the new firmware is successfully downloaded, then it updates the job status to SUCCESS on AWS IoT core.
This task runs the MQTT process loop, which process all the incoming MQTT messages.
Setting up 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 the device with AWS IoT Core. The following
entities are generated while following the instructions in the AWS IoT Core Setup Guide:
A device Endpoint.
An AWS IoT Thing (and associated ThingName).
PEM-encoded device certificate.
PEM-encoded private key.
PEM-encoded root CA certificate.
The entities are required by the simulator/device in order for it to connect with AWS IoT Core.
Setting up the cloud services for OTA
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.
By default, the OTA Update Manager 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 is required to give your account permissions to interact with
the AWS services required for creating an OTA Update.
Create an OTA User Policy.
We have created a helper wizard to improve the AWS IoT and OTA experience. This
script streamlines the creation of IoT things and OTA jobs, and also provides thing group management functionality. The setup steps you follow are
not different with this wizard, it simply prompts you for all the information needed to connect to AWS IoT and to handle the creation of any required
OTA-related tools. We highly recommend using the setup wizard, as it both reduces the time to connect to the AWS IoT ecosystem and
is easier to use than the manual setup.
Prepare for creating the OTA update job
To send an OTA job, there needs to be an updated firmware image stored in an S3 bucket. The AWS IoT OTA Manager service will read the image
out of this bucket and send it to the device.
An example of a production workflow would be:
Write the MCU firmware, integrating the OTA Client library source code.
Program the device hardware (the MCU) with the initial firmware.
Make changes to and test the firmware locally.
Generate the binary for the new version of the firmware.
Upload the new version to S3 and send it to the MCU with the an OTA Job.
Running the Demo
Build and Run the OTA demo project
The OTA demo project can be downloaded here. Instructions
to build the project can be found here.
Before continuing, verify that you are able to build and run the project.
Create the OTA update job
At this point, you should have:
Created an AWS IoT Thing with the AWS IoT Service.
Set up the S3 bucket and managed permissions for the various services.
Uploaded a "newer" firmware image to the S3 bucket.
Completed the setup required for code signing.
Configured the OTA client running on your device.
With the OTA Client running and the cloud services set up, the next step is to send
the device a new firmware image by creating an OTA job. Start by going to the AWS IoT console.
In the navigation pane of the AWS IoT console, choose Manage, and then choose Jobs.
Then press Create Job.
Create a Job - click to enlarge
Choose Create FreeRTOS OTA update job,
then press Next.
Create OTA Update Job - click to enlarge
On the OTA job properties page, enter a Job name for the
FreeRTOS OTA update job (for example, "ota_sim_update"). You can optionally enter a Description and add
Tags to your job. Then press Next to continue.
OTA Job Properties - click to enlarge
You can deploy an OTA update to a single device or a group of devices. On the OTA file configuration page, under
Devices to update, choose the things or thing groups associated with the devices you want to update. Under
Select the protocol for file transfer, select the check box next to MQTT.
Select a Device to update - click to enlarge
Under Sign and choose your file, keep the default option of Sign a new file for me selected.
Under Code signing profile, press the Create new profile button which is next to
Existing code signing profile.
Select the Files to OTA - click to enlarge
On the Create a code signing profile page, under Profile name, enter "ota_codesigning".
Under Device hardware platform, select "Windows Simulator". Under
Code signing certificate, change the default and select the
Select an existing certificate checkbox. Under Certificates, select the
certificate and certificate private keys that you generated earlier. If you followed the suggestion, these
will be named "ecdsasigner.crt" and "ecdsasigner.key". Then press the Import button. Under
Path name of code signing certificate on device, enter the path to the "ecdsasigner.crt" certificate
that you just imported. However, for the demo you should enter "/" for the path here.
Finally, press the Create button to make the code signing profile.
Create a Code Signing Profile - click to enlarge
Back on the OTA file configuration page, under File, change the default
and select the checkbox for Select an existing file, then press the Browse S3
button and choose the executable you uploaded to S3 during a previous step. Under Path name of file on
device, enter "/". This path is where the file that is downloaded during the OTA update
will be saved. Note: The File type feature is supported in
OTA library version v2.0.0 or higher.
Choose S3 file and location on device - click to enlarge
Under IAM role, select the IAM role created for the OTA process. Then press Next to continue.
Choose IAM role - click to enlarge
Under OTA job configuration, keep the default settings selected for Job run type
(snapshot), Job start rollout configuration (constant rate), and Job run timeout
configuration (No timeout). Then press the Create job button to finish creating the OTA
OTA Job Configuration - click to enlarge
You can monitor that status of the job by pressing the “View Job” pop-up or by
navigating to Manage > Jobs in the AWS IoT console. The job will be shown as
“IN PROGRESS” until the device has successfully downloaded the image.
OTA Job Status - click to enlarge
Receive the update
After the job has been created, the device should begin downloading the update. The progress of the download can be monitored on the terminal.
Below is an example of the console messages:
MQTT streams handling incoming message
Incoming data block
The following message will print to the monitor after receiving the final block of the download:
OTA Completed successfully!
When the job process is complete the state of the job will change from IN PROGRESS to SUCCEEDED in the IoT console.
OTA Job Status - click to enlarge
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.