FreeRTOS quick start
Beginners guide
Updated Mar 2025
Build your first FreeRTOS project
Introduction
FreeRTOS is designed to be simple and easy to use: Only 3 source files that are common to all RTOS ports, and one microcontroller specific source file are required, and its API is designed to be simple and intuitive.
FreeRTOS is ported to many different microcontroller architectures, and many different compilers. Each official port comes with an official demo that (at least at the time of its creation) compiles and executes on the hardware platform on which it was developed without any modification.
The demo projects are provided to ensure new users can get started with FreeRTOS in the quickest possible time, and with the minimum of fuss.
Each architecture supported by FreeRTOS is used in many different microcontrollers, meaning FreeRTOS can be used with literally thousands of different microcontroller part numbers. Multiplying this number by the number of supported compilers, and then multiplying again by the ever increasing number of starter kits and evaluation boards that are being brought to the market, and it is obvious that, despite our best efforts, we can only provide official demo projects that exactly match a tiny fraction of possible combinations.
It is always recommended that a new FreeRTOS project is created by starting with, and then adapting, one of the provided pre-configured demos. Doing this ensures the new project includes all the necessary source and header files, and installs the necessary interrupt service routines, with no effort on the part of the project's creator.
Some FreeRTOS users also want to know how to create FreeRTOS projects by means other than adapting an existing project. The procedure for doing this is documented below.
Getting Started with Simple FreeRTOS Demo Projects
[See also the Quick Start Guide and the demo application introduction page.]
Try It Now, Using the Windows or Linux Port, or in QEMU
No hardware yet? Don't worry - you can run a simple blinky demo in a Windows or Linux environment using free tools and the FreeRTOS Windows or Linux port - although neither of these RTOS ports will exhibit true real time behaviour. Alternatively run the demo using the FreeRTOS Arm Cortex-M3 port in QEMU.
If you are a beginner, then don't read the main documentation pages for either the Windows or Linux RTOS ports yet, and start by configuring the example to use the blinky demo (ignore the comprehensive demo for now). Detailed instructions for Windows follows.
Instructions for Windows
- If you don't already have it installed, download and install
the free version of Microsoft Visual Studio
. - If you have not done so already, download and unzip the official FreeRTOS distribution.
- Start Visual Studio, then use the File|Open|Project/Solution menu item to open the Win32.sln solution file, which is located in the FreeRTOS/Demo/WIN32-MSVC directory of the official FreeRTOS distribution.
- Find the definition of mainCREATE_SIMPLE_BLINKY_DEMO_ONLY at the top of main.c, and make sure it is set to 1.
- Read the comments at the top of main_blinky.c, before compiling and then either debugging or running the application.
The output produced by the FreeRTOS Windows port simple blinky demo
Anatomy of a FreeRTOS Project
A FreeRTOS application will start up and execute just like a non-RTOS application until vTaskStartScheduler() is called. vTaskStartScheduler() is normally called from the application's main() function. The RTOS only controls the execution sequencing after vTaskStartScheduler() has been called.
It is highly recommended to ensure that code is executing correctly (correct start up code, correct linker configuration, etc.) on the chosen target before attempting to use any RTOS functionality.
Source Files
FreeRTOS is supplied as standard C source files that are built along with all the other C files in your project. The FreeRTOS source files are distributed in a zip file. The RTOS source code organisation page describes the structure of the files in the zip file.
As a minimum, the following source files must be included in your project:
- FreeRTOS/Source/tasks.c
- FreeRTOS/Source/queue.c
- FreeRTOS/Source/list.c
- FreeRTOS/Source/portable/[compiler]/[architecture]/port.c.
- FreeRTOS/Source/portable/MemMang/heap_x.c where 'x' is 1, 2, 3, 4 or 5.
If the directory that contains the port.c file also contains an assembly language file, then the assembly language file must also be used.
Optional Source Files
If you need software timer functionality, then add FreeRTOS/Source/timers.c to your project.
If you need event group functionality, then add FreeRTOS/Source/event_groups.c to your project.
If you need stream buffer or message buffer functionality, then add FreeRTOS/Source/stream_buffer.c to your project.
If you need co-routine functionality, then add FreeRTOS/Source/croutine.c to your project (note co-routines are deprecated and not recommended for new designs).
Header Files
The following directories must be in the compiler's include path (the compiler must be told to search these directories for header files):
- FreeRTOS/Source/include
- FreeRTOS/Source/portable/[compiler]/[architecture].
- Whichever directory contains the FreeRTOSConfig.h file to be used - see the Configuration File paragraph below.
Depending on the port, it may also be necessary for the same directories to be in the assembler's include path.
Configuration File
Every project also requires a file called FreeRTOSConfig.h. FreeRTOSConfig.h tailors the RTOS kernel to the application being built. It is therefore specific to the application, not the RTOS, and should be located in an application directory, not in one of the RTOS kernel source code directories.
If heap_1, heap_2, heap_4 or heap_5 is included in your project, then the FreeRTOSConfig.h definition configTOTAL_HEAP_SIZE will dimension the FreeRTOS heap. Your application will not link if configTOTAL_HEAP_SIZE is set too high.
The FreeRTOSConfig.h definition configMINIMAL_STACK_SIZE sets the size of the stack used by the idle task. If configMINIMAL_STACK_SIZE is set too low, then the idle task will generate stack overflows. It is advised to copy the configMINIMAL_STACK_SIZE setting from an official FreeRTOS demo provided for the same microcontroller architecture. The FreeRTOS demo projects are stored in sub directories of the FreeRTOS/Demo directory. Note that some demo projects are old, so they do not contain all the available configuration options.
Application writers can use the FreeRTOSConfig.h template
as a starting point to create the FreeRTOSConfig.h file for their application.
Interrupt Vectors
[Cortex-M users: Information on installing interrupt handers is provided in the "The application I created compiles, but does not run" FAQ]
Every RTOS port uses a timer to generate a periodic tick interrupt. Many ports use additional interrupts to manage context switching. The interrupts required by an RTOS port are serviced by the provided RTOS port source files.
The method used to install the interrupt handlers provided by the RTOS port is dependent on the port and compiler being used. Refer to, and if necessary copy, the provided official demo application for the port being used. Also refer to the documentation page provided for the official demo application.