Quality RTOS & Embedded Software

SUPPORT
WHAT'S NEW
FreeRTOS:
FreeRTOS LTS:
FreeRTOS:
FreeRTOS:
AWS Reference Integrations:
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+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 z a point release number. LTS libraries may also have a patch number. For example, if version x.y.z of coreMQTT was an LTS release, and that LTS library has since had two patches applied, its version number would be "coreHTTP x.y.z LTS Patch 2".

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+TCP) running in emulated environments.

  2. FreeRTOS AWS IoT reference integration distribution (from the AWS GitHub organization):

    This contains many pre-configured projects that demonstrate the integration of FreeRTOS and AWS libraries running on different processors (and in the Windows simulator), using different compilers, and being used to connect to AWS IoT services.

  3. AWS IoT Embedded C SDK for devices:

    Similar to the FreeRTOS AWS IoT reference integrations, but demonstrating the libraries running on a POSIX operating system instead of FreeRTOS.

  4. LTS versions of FreeRTOS libraries:

    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+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 synch 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. FreeRTOS AWS IoT reference integration distribution:

    This package distribution is available from the AWS account in GitHub, but is large. The Online Configuration Wizard (OCW, available through the AWS console) and AWS partner device catalog both provide more convenient distributions.

  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.