Amazon FreeRTOS - User Guide

104 Pages·2017·2.97 MB·English

FreeRTOS
User Guide
FreeRTOS User Guide
FreeRTOS: User Guide
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
FreeRTOS User Guide
Table of Contents
What is FreeRTOS? ............................................................................................................................. 1
Downloading FreeRTOS source code ............................................................................................. 1
FreeRTOS versioning................................................................................................................... 1
FreeRTOS Long Term Support .................................................................................................... 1
FreeRTOS Extended Maintenance Plan .......................................................................................... 2
FreeRTOS architecture................................................................................................................ 2
FreeRTOS-qualified hardware platforms ........................................................................................ 3
Development workflow............................................................................................................... 3
Additional resources................................................................................................................... 4
FreeRTOS kernel fundamentals............................................................................................................ 5
FreeRTOS kernel scheduler.......................................................................................................... 5
Memory management................................................................................................................. 5
Kernel memory allocation................................................................................................... 5
Application memory management........................................................................................ 6
Intertask coordination................................................................................................................. 6
Queues............................................................................................................................. 6
Semaphores and mutexes ................................................................................................... 7
Direct-to-task notifications.................................................................................................. 7
Stream buffers................................................................................................................... 7
Message buffers................................................................................................................. 8
Symmetric multiprocessing (SMP) support ..................................................................................... 9
Modifying applications to use the FreeRTOS-SMP kernel ....................................................... 10
Software timers....................................................................................................................... 10
Low power support .................................................................................................................. 10
FreeRTOSConfig.h ................................................................................................................ 10
AWS IoT Device SDK for Embedded C ................................................................................................. 12
Getting Started with FreeRTOS .......................................................................................................... 13
Getting Started with AWS IoT and FreeRTOS using Quick Connect .................................................. 13
Explore FreeRTOS libraries......................................................................................................... 13
Understand how to build a secure and robust AWS IoT product ...................................................... 13
Develop your AWS IoT application product .................................................................................. 13
Getting Started with FreeRTOS Extended Maintenance Plan (EMP) .......................................................... 15
Setting up an AWS account and permissions ................................................................................ 15
Create an IAM user and grant permissions ........................................................................... 15
Create a FreeRTOS EMP subscription in the AWS IoT console ......................................................... 16
Manage FreeRTOS EMP subscriptions .......................................................................................... 18
AWS IoT Device Tester for FreeRTOS ................................................................................................... 19
FreeRTOS qualification suite...................................................................................................... 19
Custom test suites.................................................................................................................... 20
Supported versions of IDT for FreeRTOS ..................................................................................... 20
Latest version of IDT for FreeRTOS ..................................................................................... 20
Earlier IDT versions ........................................................................................................... 21
Unsupported IDT versions......................................................................................................... 22
Download IDT for FreeRTOS ...................................................................................................... 29
Download IDT manually .................................................................................................... 29
Download IDT programmatically ........................................................................................ 29
Use IDT with FreeRTOS qualification suite 2.0 (FRQ 2.0) ................................................................ 33
Prerequisites.................................................................................................................... 34
Preparing to test your microcontroller board for the first time ............................................... 40
Use the IDT UI to run the FreeRTOS qualification suite .......................................................... 50
Running the FreeRTOS qualification 2.0 suite ....................................................................... 54
Understanding results and logs .......................................................................................... 56
Use IDT with FreeRTOS qualification suite 1.0 (FRQ 1.0) ................................................................ 59
Prerequisites.................................................................................................................... 60
iii
FreeRTOS User Guide
Preparing to test your microcontroller board for the first time ............................................... 63
Use the IDT UI to run the FreeRTOS qualification suite .......................................................... 75
Running Bluetooth Low Energy tests .................................................................................. 83
Running the FreeRTOS qualification suite ............................................................................ 86
Understanding results and logs .......................................................................................... 90
Use IDT to develop and run your own test suites .......................................................................... 93
Download the latest version of IDT for FreeRTOS ................................................................. 93
Test suite creation workflow .............................................................................................. 93
Tutorial: Build and run the sample IDT test suite .................................................................. 94
Tutorial: Develop a simple IDT test suite ............................................................................. 97
Test suite versions .................................................................................................................. 154
Troubleshooting ..................................................................................................................... 155
Troubleshooting device configuration ................................................................................ 156
Troubleshooting timeout errors ........................................................................................ 163
Cellular feature and AWS charges ..................................................................................... 164
Qualification report generation policy ............................................................................... 164
Support policy....................................................................................................................... 164
Security in AWS .............................................................................................................................. 165
Identity and Access Management .............................................................................................. 165
Audience....................................................................................................................... 166
Authenticating with identities.......................................................................................... 166
Managing access using policies ......................................................................................... 168
Learn more.................................................................................................................... 169
How AWS services work with IAM ..................................................................................... 169
Identity-based policy examples ........................................................................................ 172
Troubleshooting............................................................................................................. 174
Compliance validation............................................................................................................. 176
Resilience.............................................................................................................................. 176
Infrastructure security............................................................................................................. 176
Amazon-FreeRTOS Github Repository Migration Guide ........................................................................ 178
Appendix............................................................................................................................... 178
Archive.......................................................................................................................................... 182
FreeRTOS User Guide Archive ................................................................................................... 182
Previous FreeRTOS User Guide contents .................................................................................... 182
Getting Started with FreeRTOS ........................................................................................ 182
FreeRTOS console........................................................................................................... 308
Over-the-Air Updates...................................................................................................... 310
FreeRTOS Libraries.......................................................................................................... 365
FreeRTOS demos............................................................................................................ 407
iv
FreeRTOS User Guide
Downloading FreeRTOS source code
What is FreeRTOS?
Developed in partnership with the world's leading chip companies over a 15-year period, and now
downloaded every 170 seconds, FreeRTOS is a market-leading real-time operating system (RTOS)
for microcontrollers and small microprocessors. Distributed freely under the MIT open source license,
FreeRTOS includes a kernel and a growing set of libraries suitable for use across all industry sectors.
FreeRTOS is built with an emphasis on reliability and ease of use.
FreeRTOS includes libraries for connectivity, security, and over-the-air (OTA) updates. FreeRTOS also
includes demo applications that show FreeRTOS features on qualified boards.
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/FreeRTOS/FreeRTOS.
We release FreeRTOS code under the MIT open source license, so you can use it in commercial and
personal projects.
We also welcome contributions to the FreeRTOS documentation (FreeRTOS User Guide, FreeRTOS Porting
Guide, and FreeRTOS Qualification Guide). To view the markdown source for the documentation, see
https://github.com/awsdocs/aws-freertos-docs. It's released under the Creative Commons (CC BY-ND)
license.
Downloading FreeRTOS source code
Download the latest FreeRTOS and Long Term Support (LTS) packages from the Downloads page on
freertos.org.
FreeRTOS versioning
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 starting from 2022, z is a patch number. Before 2022, z was a
point release number, which required the first LTS libraries to have a patch number of the form "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. 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. For the LTS package, it's the
latest patch version of the LTS libraries originally released as an LTS version on that date.
FreeRTOS Long Term Support
FreeRTOS Long Term Support (LTS) releases receive security and critical bug fixes (should any be
necessary) for at least two years following their release. With this ongoing maintenance, you can
incorporate bug fixes throughout a development and deployment cycle without the expensive disruption
of updating to new major versions of FreeRTOS libraries.
With FreeRTOS LTS, you get the complete set of libraries needed to build secure connected IoT and
embedded products. LTS helps reduce maintenance and testing costs associated with updating libraries
on your devices already in production.
1
FreeRTOS User Guide
FreeRTOS Extended Maintenance Plan
FreeRTOS LTS includes the FreeRTOS kernel and IoT libraries: FreeRTOS+TCP, coreMQTT, coreHTTP,
corePKCS11, coreJSON, AWS IoT OTA, AWS IoT Jobs, AWS IoT Device Defender, and AWS IoT Device
Shadow. For more information, see the FreeRTOS LTS libraries.
FreeRTOS Extended Maintenance Plan
AWS also offers FreeRTOS Extended Maintenance Plan (EMP), which provides security patches and critical
bug fixes on your chosen FreeRTOS Long Term Support (LTS) version for up to ten additional years.
With FreeRTOS EMP, your FreeRTOS based long-lived devices can rely on a version that has feature
stability and receives security updates for years. You receive timely notifications of upcoming patches on
FreeRTOS libraries, so you can plan the deployment of security patches on your Internet of Things (IoT)
devices.
To learn more about FreeRTOS EMP, see the Features page. To get started, see Getting Started with
FreeRTOS Extended Maintenance Plan (EMP) (p. 15)
FreeRTOS architecture
FreeRTOS contains 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 can contain preconfigured projects that demonstrate
the library’s use.
While package repositories contain multiple libraries, they don't contain copies of those libraries. Instead,
package repositories reference the libraries they contain as git submodules. Using submodules ensures
that there is a single source of truth for each individual library.
The individual library git repositories are split between two GitHub organizations. 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
organization. Repositories containing AWS IoT specific libraries (such as the AWS IoT over-the-air update
client) are in the AWS GitHub organization. The following diagram explains the structure.
2
FreeRTOS User Guide
FreeRTOS-qualified hardware platforms
FreeRTOS-qualified hardware platforms
The following hardware platforms are qualified for FreeRTOS:
• ATECC608A Zero Touch Provisioning Kit for AWS IoT
• Cypress CYW943907AEVAL1F Development Kit
• Cypress CYW954907AEVAL1F Development Kit
• Cypress CY8CKIT-064S0S2-4343W Kit
• Espressif ESP32-DevKitC
• Espressif ESP-WROVER-KIT
• Espressif ESP-WROOM-32SE
• Espressif ESP32-S2-Saola-1
• Infineon XMC4800 IoT Connectivity Kit
• Marvell MW320 AWS IoT Starter Kit
• Marvell MW322 AWS IoT Starter Kit
• MediaTek MT7697Hx Development Kit
• Microchip Curiosity PIC32MZEF Bundle
• Nordic nRF52840-DK
• NuMaker-IoT-M487
• NXP LPC54018 IoT Module
• OPTIGA Trust X Security Solution
• Renesas RX65N RSK IoT Module
• STMicroelectronicsSTM32L4 Discovery Kit IoT Node
• Texas Instruments CC3220SF-LAUNCHXL
• Microsoft Windows 7 or later, with at least a dual core and a hard-wired Ethernet connection
• Xilinx Avnet MicroZed Industrial IoT Kit
Qualified devices are also listed on the AWS Partner Device Catalog.
For information about qualifying a new device, see the FreeRTOS Qualification Guide.
Development workflow
You start development by downloading FreeRTOS. You unzip the package and import it into your IDE.
You can then develop an application on your selected hardware platform and manufacture and deploy
these devices using the development process appropriate for your device. Deployed devices can connect
to the AWS IoT service or AWS IoT Greengrass as part of a complete IoT solution.
3
FreeRTOS User Guide
Additional resources
Additional resources
These resources might be helpful to you.
• For additional FreeRTOS Documentation, see freertos.org.
• For questions about FreeRTOS for the FreeRTOS engineering team, you can open an issue on the
FreeRTOS GitHub page.
• For technical questions about FreeRTOS, see the FreeRTOS Community Forums.
• For more information about connecting devices to AWS IoT, see Device Provisioning in the AWS IoT
Core Developer Guide.
• For technical support for AWS, see AWS Support Center.
• For questions about AWS billing, account services, events, abuse, or other issues with AWS, see the
Contact Us page.
4
FreeRTOS User Guide
FreeRTOS kernel scheduler
FreeRTOS kernel fundamentals
The FreeRTOS kernel is a real-time operating system that supports numerous architectures. It is ideal for
building embedded microcontroller applications. It provides:
• A multitasking scheduler.
• Multiple memory allocation options (including the ability to create completely statically-allocated
systems).
• Intertask coordination primitives, including task notifications, message queues, multiple types of
semaphore, and stream and message buffers.
• Support for symmetric multiprocessing (SMP) on multi-core microcontrollers.
The FreeRTOS kernel never performs non-deterministic operations, such as walking a linked list, inside
a critical section or interrupt. The FreeRTOS kernel includes an efficient software timer implementation
that does not use any CPU time unless a timer needs servicing. Blocked tasks do not require time-
consuming periodic servicing. Direct-to-task notifications allow fast task signaling, with practically no
RAM overhead. They can be used in most intertask and interrupt-to-task signaling scenarios.
The FreeRTOS kernel is designed to be small, simple, and easy to use. A typical RTOS kernel binary image
is in the range of 4000 to 9000 bytes.
For the most up-to-date documentation about the FreeRTOS kernel, see FreeRTOS.org. FreeRTOS.org
offers a number of detailed tutorials and guides about using the FreeRTOS kernel, including a Quick
Start Guide and the more in-depth Mastering the FreeRTOS Real Time Kernel.
FreeRTOS kernel scheduler
An embedded application that uses an RTOS can be structured as a set of independent tasks. Each task
executes within its own context, with no dependency on other tasks. Only one task in the application
is running at any point in time. The real-time RTOS scheduler determines when each task should run.
Each task is provided with its own stack. When a task is swapped out so another task can run, the task’s
execution context is saved to the task stack so it can be restored when the same task is later swapped
back in to resume its execution.
To provide deterministic real-time behavior, the FreeRTOS tasks scheduler allows tasks to be assigned
strict priorities. RTOS ensures the highest priority task that is able to execute is given processing
time. This requires sharing processing time between tasks of equal priority if they are ready to run
simultaneously. FreeRTOS also creates an idle task that executes only when no other tasks are ready to
run.
Memory management
This section provides information about kernel memory allocation and application memory
management.
Kernel memory allocation
The RTOS kernel needs RAM each time a task, queue, or other RTOS object is created. The RAM can be
allocated:
5
FreeRTOS User Guide
Application memory management
• Statically at compile time.
• Dynamically from the RTOS heap by the RTOS API object creation functions.
When RTOS objects are created dynamically, using the standard C library malloc() and free()
functions is not always appropriate for a number of reasons:
• They might not be available on embedded systems.
• They take up valuable code space.
• They are not typically thread-safe.
• They are not deterministic.
For these reasons, FreeRTOS keeps the memory allocation API in its portable layer. The portable
layer is outside of the source files that implement the core RTOS functionality, so you can provide an
application-specific implementation appropriate for the real-time system you're developing. When the
RTOS kernel requires RAM, it calls pvPortMalloc() instead of malloc()(). When RAM is being freed,
the RTOS kernel calls vPortFree() instead of free().
Application memory management
When applications need memory, they can allocate it from the FreeRTOS heap. FreeRTOS offers several
heap management schemes that range in complexity and features. You can also provide your own heap
implementation.
The FreeRTOS kernel includes five heap implementations:
heap_1
Is the simplest implementation. Does not permit memory to be freed.
heap_2
Permits memory to be freed, but not does coalesce adjacent free blocks.
heap_3
Wraps the standard malloc() and free() for thread safety.
heap_4
Coalesces adjacent free blocks to avoid fragmentation. Includes an absolute address placement
option.
heap_5
Is similar to heap_4. Can span the heap across multiple, non-adjacent memory areas.
Intertask coordination
This section contains information about FreeRTOS primitives.
Queues
Queues are the primary form of intertask communication. They can be used to send messages between
tasks and between interrupts and tasks. In most cases, they are used as thread-safe, First In First Out
(FIFO) buffers with new data being sent to the back of the queue. (Data can also be sent to the front
6