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|.

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 TIMERS ONESHOT VS AUTORELOAD| and the description of |FreeRTOS 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 TIMERS CONFIG|.

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|.

Listing 28. 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}