Amazon-FreeRTOS Github Repository Migration Guide - FreeRTOS
Appendix

Amazon-FreeRTOS Github Repository Migration Guide

If you have an existing FreeRTOS project based on the now deprecated amazon-freertos repository, follow these steps:

  1. Stay up to date with the latest, publicly available security fixes. Check the FreeRTOS LTS libraries page for updates, or subscribe to the FreeRTOS-LTS GitHub repository to receive the latest LTS patches with critical and security bug fixes. You can download or clone the latest FreeRTOS LTS patches required directly from the individual GitHub repositories.

  2. Consider refactoring the network transport interface implementation to optimize your hardware platform. The abstract APIs like secure sockets and Wifi APIs are not required by the latest coreMQTT library. See Transport Interface for further details.

Appendix

The following table provides recommendations for all demo projects, legacy libraries, and abstract APIs within the Amazon-FreeRTOS repository.

Migrated libraries and demos
Name Type Recommendations

coreHTTP

demos and library

Clone or download the coreHTTP library directly from the coreHTTP repository (sub-module if using git) in the FreeRTOS Github organization. The coreHTTP demos are in the primary FreeRTOS distribution. For more details, refer to the coreHTTP page.

coreMQTT

demos and library

Clone or download the coreMQTT library directly from the coreMQTT repository (sub-module if using git) in the FreeRTOS Github organization. The coreMQTT demos are in the primary FreeRTOS distribution. For more details, refer to the coreMQTT page.

coreMQTT-Agent

demos and library

Clone or download the coreMQTT-Agent library directly from the coreMQTT-Agent repository (sub-module if using git) in the FreeRTOS Github organization. The coreMQTT-Agent demos are in the coreMQTT-Agent-Demos repository. For more details, refer to the coreMQTT-Agent page.

device_defender_for_aws

demos and library

The AWS IoT Device Defender library is in its repository in the AWS GitHub organisation. Clone or download it (sub-module if using git) directly from the AWS IoT Device Defender repository. The AWS IoT Device Defender demos are in the primary FreeRTOS distribution. For more details, refer to the AWS IoT Device Defender page.

device_shadow_for_aws

demos and library

The AWS IoT Device Shadow library is in its repository in the AWS GitHub organisation. Clone or download it (sub-module if using git) directly from the AWS IoT Device Shadow) repository. The AWS IoT Device Shadow demos are in the primary FreeRTOS distribution. For more details, refer to the AWS IoT Device Shadow page.

jobs_for_aws

demos and library

The AWS IoT Jobs library is in its repository in the AWS GitHub organization. Clone or download it (sub-module if using git) directly from the AWS IoT Jobs repository. The AWS IoT Jobs demos are in the primary FreeRTOS distribution. For more details, refer to the AWS IoT Jobs page.

OTA

demos and library

The AWS IoT Over-The-Air (OTA) Update library is in its repository in the AWS GitHub organization. Clone or download it (sub-module if using git) directly from the AWS IoT OTA repository. The AWS IoT OTA demos are in the primary FreeRTOS distribution. For more details, refer to the AWS IoT OTA page.

CLI and FreeRTOS_Plus_CLI

demos and library

There is a CLI example running on WinSim. Refer to the FreeRTOS Plus Command Line Interface page for more details. The Featured FreeRTOS IoT reference integrations on the NXP i.MX RT1060 and STM32U5 platforms, also provide CLI examples on actual hardware.

logging

macro

There are implementations of the logging macro for specific hardware platforms used by some of the FreeRTOS libraries. Refer to the logging page for how to implement the logging macro. Refer to one of the FreeRTOS featured IoT references for an example running on actual hardware.

greengrass_connectivity

demo

[Migration in progress] This demo project assumed that cloud connectivity was available before connecting to an AWS IoT Greengrass device. A new project that demonstrates local authentication and discovery capability is under development. Expect the new demo project to be published shortly in the FreeRTOS Github organization.
Deprecated libraries and demos
Name Type Recommendations

BLE

demos and libraries

The FreeRTOS BLE library implements the proprietary MQTT protocol and supports publishing and subscribing to MQTT topics over Bluetooth Low Energy (BLE) through a proxy device such as a mobile phone. This is no longer mandated. Use either your own BLE stack or a third-party option such as NimBLE to best optimize your project.

dev_mode_key_provisioning

demos

The Featured FreeRTOS IoT reference integrations on the NXP i.MX RT1060, STM32U5, or ESP32-C3 platforms provide examples of crucial provisioning using a CLI.

posix

abstraction and demo

Not recommended for use.

wifi_provisioning

example

This example demonstrated how to provision WiFi credentials on a device using the Amazon-FreeRTOS BLE library. Refer to the FreeRTOS Featured IoT reference on the ESP32C3 platform for an example of WiFi provisioning via BLE.

Legacy abstract APIs

code

These are APIs that were created to provide an abstract interface for various third-party software stacks, connectivity modules, and MCU platforms from a variety of vendors. For example, there are interfaces for WiFi abstraction, secure sockets, and so on. They are supported in the Amazon-FreeRTOS repository and are in the folder /libraries/abstractions/. These APIs are not required when using the FreeRTOS LTS libraries.

The libraries and demos in the table above will not get security patches or bug fixes.

Third-party libraries

When demos in Amazon-FreeRTOS use third-party libraries, we recommend that you sub-module them directly from their third-party repositories.

  • CMock: clone it (submodule if you use git) directly from the Cmock repository.

  • jsmn: not recommended and no longer supported.

  • lwip: clone it (submodule if you use git) directly from the lwip-tcpip repository.

  • lwip_osal: refer to the FreeRTOS Featured Reference Integrations on i.MX RT1060 or STM32U5 for how to implement lwip_osal on your hardware platform/board.

  • mbedtls: clone it (submodule if you use git) directly from the Mbed-TLS repository. The mbedtls config and utilities can be reused; make a local copy in this case.

  • pkcs11: clone it (submodule if you use git) directly from either the corePKCS11 library or the OASIS PKCS 11 repository.

  • tinycbor: clone it (submodule if you use git) directly from thetinycbor repository.

  • tinycrypt: we recommend that you use crypto accelerators from your MCU platform, if available. If you want to continue to use tinycrypt, clone it (submodule if you use git) directly from the tinycrypt repository.

  • tracealyzer_recorder: clone it (submodule if you use git) directly from Percepio's trace recorder repository.

  • unity: clone it (submodule if you use git) directly from the ThrowTheSwitch/Unity repository.

  • win_pcap: win_pcap is no longer maintained. We recommend that you use libslirp, libpcap (posix), or npcap instead.

Porting tests and integration tests

All tests under the /tests folder that are required to validate integration of FreeRTOS libraries were migrated to the FreeRTOS-Libraries-Integration-Tests repository. These can be used to test PAL implementation and library integration. The same tests are used by AWS IoT Device Tester (IDT) for the AWS Device Qualification Program for FreeRTOS.