Amazon FreeRTOS
Porting Guide

Porting Amazon FreeRTOS to Your Device

Before a microcontroller board can run Amazon FreeRTOS, some Amazon FreeRTOS code must be ported to the device's hardware.

To port Amazon FreeRTOS to your device

  1. Follow the instructions in Downloading Amazon FreeRTOS for Porting to download the latest version of Amazon FreeRTOS for porting.

  2. Follow the instructions in Setting Up Your Amazon FreeRTOS Source Code for Porting to configure the files and folders in your Amazon FreeRTOS download for porting and testing.

  3. Follow the instructions in Porting the Amazon FreeRTOS Libraries to port the Amazon FreeRTOS libraries to your device. Each porting topic includes instructions on testing the ports.

System Requirements

The device that you port to Amazon FreeRTOS must be a microcontroller board that meets the following minimum requirements:

  • 25MHz processing speed

  • 64KB RAM

  • 128KB program memory per executable image stored on the MCU

  • (If Porting the OTA Library) Two executable images stored on the MCU

Porting Older Versions of Amazon FreeRTOS

If you are porting an older version of Amazon FreeRTOS, go to the amazon-freertos GitHub repository, and checkout the version of Amazon FreeRTOS that you are porting by its version tag. The qualification and testing documentation will be in PDF format, in the tests folder. See the table below for the qualification and testing documentation history.

Revision History of Amazon FreeRTOS Porting and Qualification Documentation


Porting and Qualification Documentation Version

Change History

Amazon FreeRTOS Version

June 17, 2019

201906.00 (Porting Guide)

201906.00 (Qualification Guide)

  • Release 201906.00

  • Directory structured updated

201906.00 Major

May 21, 2019

1.4.8 (Porting Guide)

1.4.8 (Qualification Guide)


February 25, 2019


  • Removed download and configuration instructions from Getting Started Guide Template Appendix (page 84)




December 27, 2018


  • Updated Checklist for Qualification appendix with CMake requirement (page 70)



December 12, 2018


  • Added lwIP porting instructions to TCP/IP porting appendix (page 31)


November 26, 2018


  • Added Bluetooth Low Energy porting appendix (page 52)

  • Added AWS IoT Device Tester for Amazon FreeRTOS testing information throughout document

  • Added CMake link to Information for listing on the Amazon FreeRTOS Console appendix (page 85)


November 7, 2018


  • Updated PKCS #11 PAL interface porting instructions in PKCS #11 porting appendix (page 38)

  • Updated path to CertificateConfigurator.html (page 76)

  • Updated Getting Started Guide Template appendix (page 80)


October 8, 2018


  • Added new "Required for AFQP" column to aws_test_runner_config.h test configuration table (page 16)

  • Updated Unity module directory path in Create the Test Project section (page 14)

  • Updated "Recommended Porting Order" chart (page 22)

  • Updated client certificate and key variable names in TLS appendix, Test Setup (page 40)

  • File paths changed in Secure Sockets porting appendix, Test Setup (page 34); TLS porting appendix, Test Setup (page 40); and TLS Server Setup appendix (page 57)


August 27, 2018


  • Added OTA Updates porting appendix (page 47)

  • Added Bootloader porting appendix (page 51)



August 9, 2018


  • Updated "Recommended Porting Order" chart (page 22)

  • Updated PKCS #11 porting appendix (page 36)

  • File paths changed in TLS porting appendix, Test Setup (page 40), and TLS Server Setup appendix, step 9 (page 51)

  • Fixed hyperlinks in MQTT porting appendix, Prerequisites (page 45)

  • Added AWS CLI config instructions to examples in Instructions to Create a BYOC appendix (page 57)



July 31, 2018


Initial version of the Amazon FreeRTOS Qualification Program Guide


Porting FAQs

What is an Amazon FreeRTOS port?

An Amazon FreeRTOS port is a board-specific implementation of APIs for the required Amazon FreeRTOS libraries and the Amazon FreeRTOS that your platform supports. The port enables the APIs to work on the board, and implements the required integration with the device drivers and BSPs that are provided by the platform vendor. Your port should also include any configuration adjustments (e.g. clock rate, stack size, heap size) that are required by the board.

My device does not support Wi-Fi, Bluetooth Low Energy, or over-the-air (OTA) updates. Are all libraries required to port Amazon FreeRTOS?

The primary requirement for Amazon FreeRTOS is that your device can connect to the AWS Cloud. If, for example, you can connect to the cloud across a secure ethernet connection, Amazon FreeRTOS, the Wi-Fi library is not a required. Keep in mind that some test and demo applications will not work without all of the libraries ported.

Can I reach an "echo server" from two different networks (for example, from two subnets across 2 different access points)?

An echo server is required to pass the TCP/IP and TLS port tests. The echo server must be reachable from the network that a board is connected to. Please consult your IT support to enable routing across subnets if you need devices on different subnets to communicate with a single echo server.

What network ports need to be open to run the Amazon FreeRTOS port tests?

The following network connections are required to run the Amazon FreeRTOS port tests:



443, 8883



Greengrass Discovery

If you have questions about porting that are not answered on this page or in the rest of the Amazon FreeRTOS Porting Guide, please contact the Amazon FreeRTOS engineering team.