Amazon FreeRTOS
Porting Guide

Amazon FreeRTOS Porting

What is Amazon FreeRTOS?

Amazon FreeRTOS is a real-time operating system that augments the FreeRTOS kernel with libraries for connectivity, security, and over-the-air (OTA) updates. Amazon FreeRTOS also includes demo applications that show Amazon FreeRTOS features on qualified boards.

Amazon FreeRTOS is an open-source project. You can download the source code, contribute changes or enhancements, or report issues on the GitHub site at https://github.com/aws/amazon-freertos. We release Amazon FreeRTOS code under the MIT open source license, so you can use it in commercial and personal projects.

We also welcome contributions to the Amazon FreeRTOS documentation (Amazon FreeRTOS User Guide, Amazon FreeRTOS Porting Guide, and Amazon FreeRTOS Qualification Guide). The markdown source for the documentation is available at https://github.com/awsdocs/aws-freertos-docs. It is released under the Creative Commons (CC BY-ND) license.

The three types of Amazon FreeRTOS releases are major, minor, and long-term support (LTS). A major denotation indicates the addition of new features or significant updates to multiple libraries. All releases use date-based versioning with the format YYYYMM.NN, where:

  • Y represents the year.

  • M represents the month.

  • N represents the release order within the designated month (00 being the first release).

For example, a second release in June 2019 would be 201906.01.

Previously, Amazon FreeRTOS used semantic versioning for major releases. Although it has moved to date-based versioning (Amazon FreeRTOS 1.4.8 updated to Amazon FreeRTOS 201906.00), the FreeRTOS kernel and each individual Amazon FreeRTOS library still retain semantic versioning. In semantic versioning, the version number itself (X.Y.Z) indicates whether the release is a major, minor, or point release. This can create situations where semantic versioning indicates a major release based on changes that don’t affect an individual application. You can use the semantic version of a library to assess the scope and impact of a new release on your application.

LTS releases are maintained differently than other release types. Major and minor releases are frequently updated with new features in addition to defect resolutions. LTS releases are only updated with changes to address critical defects and security vulnerabilities. No new features are introduced in a given LTS release after launch. They are maintained for at least three calendar years after release, and provide device manufacturers the option to use a stable baseline as opposed to a more dynamic baseline represented by major and minor releases.

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

Date

Porting and Qualification Documentation Version

Change History

Amazon FreeRTOS Version

October 29, 2019

201910.00 (Porting Guide)

201910.00 (Qualification Guide)

  • Release 201910.00

  • Updated random number generator porting information.

201910.00

August 26, 2019

201908.00 (Porting Guide)

201908.00 (Qualification Guide)

201908.00

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)

1.4.8

February 25, 2019

1.1.6

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

1.4.5

1.4.6

1.4.7

December 27, 2018

1.1.5

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

1.4.5

1.4.6

December 12, 2018

1.1.4

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

1.4.5

November 26, 2018

1.1.3

  • 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)

1.4.4

November 7, 2018

1.1.2

  • 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)

1.4.3

October 8, 2018

1.1.1

  • 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)

1.4.2

August 27, 2018

1.1.0

  • Added OTA Updates porting appendix (page 47)

  • Added Bootloader porting appendix (page 51)

1.4.0

1.4.1

August 9, 2018

1.0.1

  • 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)

1.3.1

1.3.2

July 31, 2018

1.0.0

Initial version of the Amazon FreeRTOS Qualification Program Guide

1.3.0

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:

Port

Protocol

443, 8883

MQTT

8443

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.