Amazon FreeRTOS
User Guide

Amazon FreeRTOS Over-the-Air Updates

The Amazon FreeRTOS Over-the-Air Update service enables you to:

  • Digitally sign and encrypt firmware before deployment.

  • Securely deploy new firmware images to a single device, a group of devices, or your entire fleet.

  • Deploy firmware to devices as they are added to groups, reset, or reprovisioned.

  • Verify the authenticity and integrity of the new firmware after it's deployed to devices.

  • Monitor the progress of a deployment.

  • Debug a failed deployment.

Devices communicate with the Amazon FreeRTOS OTA Update service using MQTT messages. Each device must subscribe to the appropriate topics to receive messages. MQTT messages are used to notify devices that an update is available, report the status of an update, and to stream the firmware updates. Each device has its own set of MQTT topics.

OTA Update includes the following components:

OTA Manager Service

The OTA Manager service enables users to create and manage deployments of firmware images on one or more devices or MCUs. The OTA Manager Service uses the AWS IoT Jobs service to schedule deployments.

AWS IoT Jobs Service

The AWS IoT Jobs service is a cloud-based managed service for scheduling, orchestration, notification, and status reporting of OTA updates and other remote operations on distributed fleets of small devices. To update a device, you create an OTA update job. The job specifies which devices should perform the update and where to find the firmware image, among other things. When a job is deployed to a device, a job execution is created. The job execution represents a single device applying the update. For more information, see AWS IoT Jobs.

Streaming Service

The Streaming service delivers new firmware images over MQTT to your devices. The Streaming service breaks up the firmware image into chunks and delivers each chunk as an MQTT message to the devices that are being updated. The service can redeliver blocks or a full image on request.

Code Signing for Amazon FreeRTOS Service

Code Signing for Amazon FreeRTOS is a managed AWS service that enables you to sign code that you create for any IoT device that is supported by Amazon Web Services (AWS). Code Signing is integrated with Amazon FreeRTOS and AWS Certificate Manager (ACM). Amazon FreeRTOS customers can use Code Signing to sign a code image before publishing it to a microcontroller device. You can use ACM to import a third-party code signing certificate that you can use during the signing process.

OTA Library and Agent

The OTA library allows the device developer to logically separate the application from the OTA process. The OTA library controls an OTA agent that is executed as a FreeRTOS task.

The OTA agent is responsible for:

  • Downloading a new executable image from the cloud.

  • Validating the image in a way that is appropriate for the application and device.

  • Handling interruptions during the download.

  • Managing updates that are separated into multiple sections.

The OTA agent also supports a Greengrass-mediated OTA mode for devices that are not directly connected to the cloud. In this mode, the update is downloaded by a trusted Greengrass core, which then pushes the update to Amazon FreeRTOS devices connected to it.

By automating firmware signature verification, the OTA library makes it easy for you to protect the integrity of your devices. By defining a portable abstraction layer (PAL), the OTA library minimizes the burden for onboarding new hardware to OTA-enabled applications.

Currently, OTA is supported in the following regions only:

  • us-east-1 / US East (N. Virginia)

  • us-east-2 / US East (Ohio)

  • us-west-2 / US West (Oregon)

  • eu-west-1 / EU (Ireland)

  • eu-central-1 / EU (Frankfurt)

  • eu-west-2 / EU (London)

  • ap-northeast-1 / Asia Pacific (Tokyo)

  • ap-southeast-2 / Asia Pacific (Sydney)

The region you are working in is displayed in the upper-right corner of the AWS Management Console. You can use the drop-down list to change the region. Before you create an OTA update, make sure you are working in one of these supported regions.


For the Amazon FreeRTOS OTA agent to commit a firmware upgrade, the firmware image must include the OTA agent library. The firmware version must be more recent than the currently installed firmware.

OTA Workflow

This section describes the OTA update workflow. For a tutorial that uses the Texas Instruments SimpleLink Wi-Fi CC3220SF-LAUNCHXL Wireless Microcontroller LaunchPad Development Kit, see OTA Demo Application.

  1. Create a self‐signed certificate or purchase a code‐signing certificate and a private key and import them into ACM. For more information, see Create a Code-Signing Certificate and Private Key.

  2. Deploy a device with factory-provisioned firmware (for example, v1.0). The v1.0 firmware must be configured to trust the code-signing certificate created in step 1. For more information, see Installing the Initial Firmware.

  3. When a firmware update is required, make the code changes and build the new image. For more information, see Creating a Firmware Update.

  4. Upload the new firmware image into an Amazon S3 bucket. For more information, see Uploading Updated Firmware.

  5. Digitally sign the new firmware image. You can do this step manually, or you can use the AWS IoT console which uses the Code Signing for Amazon FreeRTOS service.

  6. Using the AWS IoT Device Management console, schedule an OTA update job. For more information, see Create an OTA Update Job.

  7. The the Amazon FreeRTOS OTA agent OTA agent on the device receives the updated firmware image.

  8. The device verifies the digital signature, checksum, and version number of the new image.

  9. Reset the board and, based on application-defined logic, commit the update. This includes notifying AWS IoT Device Management that the device has (or has not) successfully completed the OTA update.

OTA Security

The following are three aspects of OTA security:

Connection security

The OTA Update service relies on existing security mechanisms like TLS mutual authentication, used by AWS IoT. OTA update traffic passes through the AWS IoT device gateway and uses AWS IoT security mechanisims. Each incoming and outgoing MQTT message through the device gateway undergoes strict authentication and authorization.

Authenticity and integrity of OTA updates

Firmware can be digitally signed before an OTA update to ensure that it is from a reliable source and has not been tampered with. The Amazon FreeRTOS OTA Update service uses the Code Signing for Amazon FreeRTOS service to automatically sign your firmware. For more information, see Code Signing for Amazon FreeRTOS. The OTA agent, which runs on your devices, performs integrity checks on the firmware when it arrives on the device.

Operator security

Every API call made through the control plane API undergoes standard IAM Signature Version 4 authentication and authorization. To create a deployment, you must have permissions to invoke the CreateDeployment, CreateJob, and CreateStream APIs. In addition, in your Amazon S3 bucket policy or ACL, you must give read permissions to the AWS IoT service principal so that the firmware update stored in Amazon S3 can be accessed during streaming.

Code Signing for Amazon FreeRTOS

The AWS IoT console uses Code Signing for Amazon FreeRTOS to automatically sign your firmware image for any device supported by AWS IoT.

Code Signing for Amazon FreeRTOS uses a certificate and private key that you import into ACM. You can use a self–signed certificate for testing, but we recommend that you obtain a certificate from a well–known commercial certificate authority (CA).

Code–signing certificates use the X.509 version 3 Key Usage and Extended Key Usage extensions. The Key Usage extension is set to Digital Signature and the Extended Key Usage extension is set to Code Signing. For more information about signing your code image, see the Code Signing for Amazon FreeRTOS Developer Guide and the Code Signing for Amazon FreeRTOS API Reference.


The Code Signing for Amazon FreeRTOS feature is currently in beta. You can download the SDK from

Monitoring Updates

The code deployment manager createDeployment API returns the job ID from the AWS IoT Jobs service. You can use the job ID and the MQTT AWS IoT Jobs APIs to track the progress and status of the OTA updates across the fleet of the devices.


Gets the details of a job execution. A job execution is an instance of a job running on a single device.


Lists all job executions for a job.


Gets the list of all job executions for a thing.

For more information, see AWS IoT Jobs API.