Quality RTOS & Embedded Software

SUPPORT
WHAT'S NEW
New FreeRTOS Long Term Support version now available.
FreeRTOS Extended Maintenance Program (EMP) registration now open.
FreeRTOS-Plus-TCP v3.0.0 released:
Featured FreeRTOS IoT Integrations:
Delta Over-the-Air Updates:
Homepage | FAQ

FreeRTOS FAQ - GitHub Repository Structure & Versioning

This is a subsection of the full FAQ

How are FreeRTOS Git repositories structured?
How are FreeRTOS libraries versioned?
Which library packages are available?
How do I obtain and use individual FreeRTOS libraries?
How do I obtain a FreeRTOS distribution package?

This is a subsection of the full FAQ



How are FreeRTOS Git repositories structured?

There are two types of repositories, single library repositories and package repositories. Each single library repository contains the source code for one library without any build projects or examples. Package repositories contain multiple libraries, and may contain pre-configured projects that demonstrate the library’s use.

While package repositories contain multiple libraries, they do not contain copies of those libraries. Instead, package repositories reference the libraries they contain as git sub-modules. Using sub-modules ensures there is a single source of truth for each individual library.

The individual library git repositories are split between two GitHub organisations. Repositories containing FreeRTOS specific libraries (such as FreeRTOS-Plus-TCP) or generic libraries (such as coreMQTT, which is cloud agnostic because it works with any MQTT broker) are in the FreeRTOS GitHub organisation. Repositories containing AWS IoT specific libraries (such as the AWS IoT over-the-air update client) are in the AWS GitHub organisation. The following diagram demonstrates the structure.

GitHub Repository Structure - click to enlarge



How are FreeRTOS libraries versioned?

Individual libraries use x.y.z style version numbers, similar to semantic versioning. x is the major version number, y the minor version number, and (from 2022) z is a patch number. Prior to 2022, z was a point release number, meaning patches to the first LTS libraries required a separate patch number of the form "x.y.z LTS Patch 2".

The LTS version of a FreeRTOS library will reserve the z in x.y.z for LTS patches. For example, if 3.1.0 is the LTS version of a FreeRTOS library, 3.1.1 will be a patch to the LTS version. This implies that a non-LTS point release of the library from the 3.1.z release commit will have to increment the minor (i.e y) number rather than the z number. This is so that patches to the LTS version can extended.

The reservation of z applies only to LTS versions of a library. Non-LTS versions of a library will increment z for point releases. For example, in subsequent releases from mainline, a future version of a FreeRTOS library, say 3.3.0, can make a point release of 3.3.1 while 3.1.0 continues to be the LTS version.

Library packages use yyyymm.x style date stamp version numbers. yyyy is the year, mm the month, and x an optional sequence number showing the release order within the month (or, in the case of the LTS package, x is a sequential patch number for that LTS release). The individual libraries contained in a package are whatever the latest version of that library was on that date (or, in the case of the LTS package, the latest patch version of the LTS libraries originally released as an LTS version on that date).



Which library packages are available?

There are four library packages.

  1. Primary FreeRTOS distribution (from the FreeRTOS GitHub organization):

    This contains many pre-configured projects that demonstrate the FreeRTOS kernel running on different processors and using different compilers, as well as projects that demonstrate other FreeRTOS libraries (such as FreeRTOS-Plus-TCP) running in emulated environments.

  2. Featured FreeRTOS IoT reference integrations (from the FreeRTOS GitHub organization):

    Featured FreeRTOS IoT integrations are pre-configured projects that demonstrate best practices to make IoT device software more secure and robust. These FreeRTOS IoT integrations are designed for improved security using a combination of FreeRTOS software and a partner-provided board with hardware security features.

  3. AWS IoT Embedded C SDK for devices (from the AWS GitHub organization):

    This contains many pre-configured projects that demonstrate the integration of FreeRTOS and AWS libraries running on a POSIX operating system instead of FreeRTOS.

  4. LTS versions of FreeRTOS libraries (from the FreeRTOS GitHub organization):

    This is for reference and convenience only. It contains just the Long Term Support (LTS) versions of the FreeRTOS libraries, with no example projects.



How do I obtain and use individual FreeRTOS libraries?

The recommended way to use individual libraries in your application is to sub-module them directly from GitHub into your application project. Alternatively, you can copy an individual library into your application by downloading a zip file of the library from the GitHub repository's Releases area. The following table contains links to individual libraries. The package downloads contain examples.

Library Git repo (including zip download)
FreeRTOS Kernel (RTOS kernel) https://github.com/FreeRTOS/FreeRTOS-Kernel
FreeRTOS-Plus-TCP (TCP/IP stack) https://github.com/FreeRTOS/FreeRTOS-Plus-TCP
coreMQTT-Agent (multi-threaded MQTT client) https://github.com/FreeRTOS/coreMQTT-Agent (includes coreMQTT)
coreMQTT (base MQTT client) https://github.com/FreeRTOS/coreMQTT
coreHTTP (HTTP client) https://github.com/FreeRTOS/coreHTTP
corePKCS11 (software mock of PKCS#11) https://github.com/FreeRTOS/corePKCS11
coreJSON (JSON) https://github.com/FreeRTOS/coreJSON
coreSNTP (SNTP) https://github.com/FreeRTOS/coreSNTP
AWS IoT Device Shadow https://github.com/aws/device-shadow-for-aws-iot-embedded-sdk
AWS IoT OTA https://github.com/aws/ota-for-aws-iot-embedded-sdk
AWS IoT Jobs https://github.com/aws/jobs-for-aws-iot-embedded-sdk
AWS IoT Device Defender https://github.com/aws/device-defender-for-aws-iot-embedded-sdk



How do I obtain a FreeRTOS distribution package?

Here are instructions for each package. Note, if using git to obtain a library package then additionally follow the repository cloning instructions in the package’s readme.md file to ensure you also initialize and sync sub-module references:

  1. Primary FreeRTOS distribution:

    Most people use the download button on the FreeRTOS.org website to obtain a zip file. The package distribution is also available from GitHub as either a git repository or zip file.

  2. Featured FreeRTOS IoT integrations:

    Each featured integration is distributed in a separate repository under FreeRTOS github organization with the "iot-reference-targetplatform" name format. Check for the list of the latest projects from the Featured FreeRTOS IoT Integration pages.

  3. AWS IoT Embedded C SDK for devices:

    This package is available from GitHub as either a git repository or zip file.

  4. LTS versions of FreeRTOS libraries:

    Similar to the primary FreeRTOS distribution, most people use the download button on the FreeRTOS.org website to obtain a zip file. The distribution is also available from GitHub as either a git repository or zip file.

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.