FreeRTOS Demo Applications
Port documentation pages are grouped by device manufacturer. Expand the list of supported devices, then
click the manufacturer of interest to be taken to a list of demo documentation pages.
The RTOS source code download includes a pre-configured
demonstration project for each RTOS port. The demo targets the evaluation board used for that port's development.
At the time of its creation, each preconfigured project built directly as downloaded without any warnings or errors, although subsequent
tooling changes may mean that is no longer the case. There is also a separate page
that describes how to create a hardware independent demo project.
The demonstration projects are provided as:
An aid to learning how to use FreeRTOS - each source file demonstrates a component of the RTOS.
A preconfigured starting point for new applications - to ensure the correct development tool setup (compiler switches,
debugger format, etc) it is recommended that new applications are created by
modifying the existing demo projects. Once you have the demo application running,
incrementally remove the demo functions and source files and replace them with your own application code. Note: it is best
to set configUSE_TICK_HOOK to 0 in FreeRTOSConfig.h when removing demo functions.
Stopping execution of the tick hook may make some demos fail, but will
prevent an example tick hook function attempting to interact with a demo that has been removed from the project
(which could otherwise result in a crash).
Locating a demo application
Each demo project has a documentation page that details the location of the project within the FreeRTOS download,
as well as other demo specific important and time saving information (such as how to set up the hardware, and how to build the project).
All the RTOS kernel only demos (demos that do not demonstrate any other libraries) are in subdirectories of the
The name of the subdirectory identifies the target device and the compiler used to build the project it contains. Please see the
FreeRTOS source code organization page for a full explanation of the FreeRTOS directory structure,
quick start guide for further practical information.
The structure of a demo application
Most demo applications use a #define
in the project's main.c
file to select between
building a basic "blinky" style project and building a comprehensive test and demo project.
Simple "blinky" demo configuration
Blinky demo projects are contained in a single source file and implement a subset of
the functionality described on the hardware independent demo functions
As a minimum the Blinky project will demonstrate how to use a FreeRTOS
queue to pass a value between two tasks - toggling an LED or printing output each time the value is received. Many blinky projects
also demonstrate a single software timer that uses the same queue.
Comprehensive test/demo configuration
Comprehensive demo projects create all or a subset of the
"common demo tasks
so called because the tasks are common to all comprehensive demos. The number of tasks created depends on the resources
available on the target hardware (microcontroller or microprocessor) - the amount of RAM available for task stacks
being the limiting factor.
The older common demo tasks only contain demonstrations of how to use the RTOS features.
Newer common demo tasks contain integration tests - making their implementation more complex.
Comprehensive demo applications create a 'check' task, or more rarely, a 'check'
function called from the tick hook. Each common demo task contains self monitoring code, and
it is the job of the check task to periodically (normally every three or five seconds, depending on the demo) query
each task to first ensure the task is still executing, and second determine if the task detected
any errors. The check task then reports the system status by either toggling an LED or printing
out a message. If the check task toggles an LED then the toggle rate will be the
task's original period (three or five seconds, depending on the demo) if no errors are present,
and increase to toggle many times a second if an error is reported by any task.
Note: The self monitoring code in common demo tasks may report errors purely because
the tasks are competing with each other for processing time. That is avoided by tuning the task
priorities relative to each other.
The pseudocode below shows the structure of a comprehensive demo.
/* main_full() is called from main() if the #define in main.c is set to create
the comprehensive demo, rather than simple blinky demo. */
int main_full( void )
/* Setup the microcontroller hardware for the demo. */
/* Create the common demo application tasks, for example: */
/* Create any tasks defined within main.c itself, or otherwise specific to the
demo being built. */
xTaskCreate( vCheckTask, "check", STACK_SIZE, NULL, TASK_PRIORITY, NULL );
/* Start the RTOS scheduler, this function should not return as it causes the
execution context to change from main() to one of the created tasks. */
/* Should never get here! */
- The demo projects often use all the available RAM on the target processor, requiring some tasks to be
removed before any more can be added.
- The majority of projects building the standard demo tasks only demonstrate and test the kernel. There are
separate projects that demonstrate additional libraries such as the TCP/IP stack,
or FreeRTOS core libraries.
- The standard demo project files are provided for the purpose of demonstrating the use of and testing the RTOS kernel. They are not
intended to provide examples of optimised solutions. This is particularly true of comtest.c (which uses an example UART driver), which
is generally written with the intent of stressing (and therefore testing) the RTOS kernel implementation rather than
providing an example of an optimal integration (normally a UART interface would use a stream buffer
rather than a queue).
Partest.c, accessing LEDs
Older demo applications includes a file called partest.c (the name is historic and since lost its meaning, but is derived
from 'parallel port test'). The file contains the interface functions for setting LEDs, clearing LEDs and toggling
LEDs. It is mentioned here because the function of the file is not obvious from its name.
"Full" vs "Minimal" demo application files
There are two directories that contain source files that implement common demo tasks. Files located in the
directory assume a hosted environment and are only used by demos that run
on top of old DOS systems (which is also why the Partest.c filename is cryptic - it could only use short filenames in 8.3 format).
All the other demo projects build the common demo source files from the FreeRTOS/Demo/Common/Minimal
directory, none of which assume a hosted environment.
Common demo task functionality
There is old documentation
that outlines the behaviour of the original
common demo tasks. Recent common demo tasks are designed more for integration testing than purely for
demonstration. That means they can be complex, and so are not documented outside of the source files
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.