Software Timers

FreeRTOS includes a mechanism called Software Timers that is very similar to what other RTOS call ‘Clocks’. In this section we will provide a brief introduction to FreeRTOS Software Timers. For all the details, please visit FreeRTOS Software Timers and the FreeRTOS API Reference.

The basics

A Software Timer allows you to execute a function some time in the future. To make use of this feature, you will need to:

  • Create a software timer

  • Define the software timer’s callback function (i.e. the function that you want to execute in the future)

  • Define the software timer’s period (i.e. the point in the future when you want it executed)

Warning

As indicated in FreeRTOS Software Timers, it is imperative that a timer’s callback does not attempt to block. That is, it cannot call vTaskDelay(), vTaskDelayUntil(), or specify a non-zero block time when accessing a queue or a semaphore.

You can select a Software Timer to be one-shot or auto-reload during creation. See more details about this in section Creating and Starting a Software Timer below. You may also want to check the FreeRTOS documentation, specifically FreeRTOS Software Timer One-Shot vs Autoreload and the description of xTaskCreate().

Using Software Timers

Please note that Software Timers are not part of the core FreeRTOS kernel. In order to use them, you must first take the following two steps:

  1. Add the FreeRTOS/Source/timers.c source file to your project, and…

  2. Define a few constants in the FreeRTOSConfig.h header file.

FreeRTOSConfig.h is part of the freertos_builds project.

See all the details at FreeRTOS Software Timer Configuration.

Details on Implementation

FreeRTOS Software Timers are provided by a timer service (or daemon) task. Your application will interact with FreeRTOS Timers through API functions, which will allow you to do operations such as create a timer, start and stop a timer, etc. These functions use a standard FreeRTOS queue to send commands to the timer service task. This queue is called the ‘timer command queue’ and cannot be accessed directly. Learn more about this at FreeRTOS Software Timers Service Task.

Creating and Starting a Software Timer

In this section we will provide an example of how to create and start a Software Timer. See more examples of usage in the FreeRTOS API Reference.

Listing 7. Create a FreeRTOS Software Timer
 1#include <FreeRTOS.h>
 2#include <stdarg.h>
 3
 4
 5TimerHandle_t xTimer;
 6
 7void main( void ) {
 8
 9    BaseType_t xReturned;
10
11    /* Create and start the timer. Recommended to do before starting the scheduler */
12    xTimer = xTimerCreate(
13            "Timer 1",                      /* Textual name, helpful during debugging! */
14            pdMS_TO_TICKS( 500 ),           /* Timer period: 500 ms */
15            pdTRUE,                         /* Autoreload */
16            ( void * ) 1,                   /* Timer ID. Can be used to identify which
17                                               timer expired if multiple timers share a
18                                               timer callback */
19            &vTimerCallback );              /* Function to call when timer expires. When
20                                               invoked by FreeRTOS, the Timer ID will be
21                                               passed as a parameter */
22
23    if(xTimer != NULL)
24    {
25        BaseType_t started;
26        started = xTimerStart(
27               xTimer,                      /* Handle returned by xTimerCreate */
28               0);                          /* Time to block in ticks: 0 (Do not block) */
29        if (pdPASS != sarted) {
30            /* Failed to start the timer! */
31        }
32     } else {
33       /* Failed to create the timer! */
34     }
35
36    /* Start the FreeRTOS scheduler */
37    vTaskStartScheduler();
38}
39
40/* Timer Callback Function (this may be reused by multiple timers if desired) */
41void vTimerCallback( TimerHandle_t xTimer )
42{
43    /* *** Enter your application code here *** */
44    /* Ex. */
45    static uint32_t timer_count__500ms = 0;
46    timer_count__500ms++;
47}