Amazon FreeRTOS
User Guide

Amazon FreeRTOS Developer Guide

This section contains information required for writing embedded applications with Amazon FreeRTOS.

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

You can also connect a terminal emulator like Tera Term or CoolTerm to see serial output from your device as it processes an OTA update.

OTA Error Codes

The following table lists error codes returned by the OTA Update service.

Error Code Description
ResourceAlreadyExist The requested resource already exists in the AWS account.
ResourceNotFound The requested resource does not exist.
InvalidRequest The request is not valid.
VersionConflict The requested resource is being updated.
Unauthorized Access is denied.
StreamingFileConflict The file associated with the stream has been modified.
InternalFailure The service encountered an internal error.

Supported Platforms

Texas Instruments CC3220SF-LAUNCHXL

The SimpleLink Wi-Fi CC3220SF-LAUNCHXL LaunchPad Development Kit includes the CC3220SF, a single-chip wireless microcontroller (MCU) with ARM Cortex -M4 Core at 80 MHz, 1 MB Flash, 256 KB of RAM, and enhanced security features. The on-chip Wi-Fi module offloads TLS and TCP/IP processing, freeing up memory and compute for the application on the main microcontroller. For more information about this platform, see, Texas Instruments CC3220SF-LAUNCHXL.

STMicroelectronics STM32L4 Discovery Kit – IoT Node

The STM32L4 IoT Discovery Kit (B-L475E-IOT01A) supports Wi-Fi and integrates additional sensors. The kit has an STM32L4 Series MCU based on ARM Cortex -M4 core at 80 MHz with 1 MB of flash memory and 128 KB of SRAM, and Wi-Fi module Inventek ISM43362-M3G-L44. The Wi-Fi module offloads TCP/IP processing from the MCU. The interface to the Wi-Fi module for this kit has not yet been optimized for use with Amazon FreeRTOS, so there are limitations on its use. We recommend using the Secure Sockets APIs from low-priority tasks only, and to limit transmit throughput. Revisions to improve this interface are planned in the future. For more information about this platform, see STMicroelectronicsSTM32L4Discovery Kit IoT Node.

NXP LPC54108 IoT Module

The LPC54018 IoT Module from NXP includes an LPC54018 MCU with a 180MHz ARM Cortex-M4 core with 360 KB of SRAM, 128 MB of Quad-SPI Flash (Macronix MX25L12835FM2), and a Longsys IEEE802.11b/g/n Wi-Fi module based on Qualcomm GT1216. The Wi-Fi module offloads TCP/IP processing from the MCU. The LPC54018 IoT Module requires a debugger and J-Link connector (available in the NXP Direct store) or a baseboard. For more information about this platform, see NXP LPC54018 IoT Module.

Microchip Curiosity PIC32MZEF

The Curiosity PIC32MZEF development board from Microchip includes a PIC32MZEF MCU with a 200 MHz 32-bit MIPS M-class core with 2 MB of Flash and 512 KB of SRAM. For users who need to use Ethernet, the LAN8720A Ethernet PHY daughter board can be connected to the Curiosity PIC32MZEF development board. For more information about this platform, see Microchip PIC32MZ2048EFM100.