FreeRTOS Software Timer: Change Period and Reset Timer

In this post, we will learn how to change the FreeRTOS software timer period and how to reset the software timer. we will demonstrate examples with Arduino. In the last tutorials, we have learned to use FreeRTOS software timer with Arduino and we have learned how to update or query software timer ID. 

Software Timer Period

In real time operating systems, we use software timers to perform some task within a specified rate using a callback function. The rate of callback of function execution is determined by the period of the software timer. In the last tutorial, we have created software timers using FreeRTOS xTimerCreate() API function.

We define a period of software timer using one of the input arguments of xTimerCreate() function. But sometimes, we need to change the period of the software timer during run-time or after the FreeRTOS scheduler has started. Because, using xTimerCreate() API, we set the time period of the software timer before the schulder has started. 

FreeRTOS Timer Period Change API

FreeRTOS provide API function to change software timer period during run-time that is TimerChangePeriod() API Function. 

xTimerChangePeriod() is used to change the period of software timer. If the timer (whose period we want to change) is in running state, then the timer will expire according to its new period. 

Note: Timer will calculate its new expiry timer according to relative to when xTimerChangePeriod() was called, not relative to when the timer wasoriginally started.

On the other hand, if the timer is in dormant state ( not running), it will recalculate its period and enter the running state. 

Note: xTimerChangePeriod() can be called from a task only. If you want to change the period of software timer from interrupt service routine, use this xTimerChangePeriodFromISR() function.

This line shows the prototype of this xTimerChangePeriod() API: 

BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, TickType_t xTimerChangePeriod, TickType_t xTicksToWait );
  • The first input argument to xTimerChangePeriod is a handle of a software timer whose period you want to change
  • Second input argument “xTimerChangePeriod” is used to define the new period
  • xTickTowait argument uses the timer command queue to send the ‘change period’ command to the daemon task. xTicksToWait specifies the maximum amount of time the calling task should remain in the Blocked state to wait for space to become available on the timer command queue, should the queue already be full.

The return values are pdPASS or pdFalse. 

For more information on xTimerChangePeriod, check this link. 

FreeRTOS Software Timer Period Change Example with Arduino

In this example, we will first create a timer with a time period of 1 second and after 5 times execution of the callback function, we will update the timer period to 2 seconds. That means, At the start, the software timer will expire after every one second for 5 times. After that, we will update its period to 2 seconds.  

Arduino Code 

In this example code, first we created a AutoReloadTimer with a period of 1 second and the callback function is defined with a name of “prvTimerCallback”. But after the timer expires 5 times, we update the timer with a new period. 

#include <Arduino_FreeRTOS.h>
#include <timers.h>
#define mainAUTO_RELOAD_TIMER_PERIOD pdMS_TO_TICKS( 500 ) 
#define mainAUTO_RELOAD_TIMER_PERIOD2 pdMS_TO_TICKS( 1000 )
TimerHandle_t xAutoReloadTimer;
BaseType_t xTimer2Started;
void setup()
{
Serial.begin(9600); // Enable serial communication library.
xAutoReloadTimer = xTimerCreate(
/* Text name for the software timer - not used by FreeRTOS. */
"AutoReload",
/* The software timer's period in ticks. */
mainAUTO_RELOAD_TIMER_PERIOD,
/* Setting uxAutoRealod to pdTRUE creates an auto-reload timer. */
pdTRUE,
/* This example does not use the timer id. */\\
0,
/* The callback function to be used by the software timer being created. */
prvTimerCallback);
/* Check the software timers were created. */
if(( xAutoReloadTimer != NULL ) )
{
/* Start the software timers, using a block time of 0 (no block time). The scheduler has
not been started yet so any block time specified here would be ignored anyway. */
xTimer2Started = xTimerStart( xAutoReloadTimer, 0 );
/* The implementation of xTimerStart() uses the timer command queue, and xTimerStart()
will fail if the timer command queue gets full. The timer service task does not get
created until the scheduler is started, so all commands sent to the command queue will
stay in the queue until after the scheduler has been started. Check both calls to
xTimerStart() passed. */
if( ( xTimer2Started == pdPASS ) )
{
/* Start the scheduler. */
vTaskStartScheduler();
}
}
}

void loop() 
{
  // put your main code here, to run repeatedly:
}

static void prvTimerCallback( TimerHandle_t xTimer )
{
TickType_t xTimeNow;
uint32_t ulExecutionCount;
/* A count of the number of times this software timer has expired is stored in the timer's
ID. Obtain the ID, increment it, then save it as the new ID value. The ID is a void
pointer, so is cast to a uint32_t. */
ulExecutionCount = ( uint32_t ) pvTimerGetTimerID( xTimer );
ulExecutionCount++;
vTimerSetTimerID( xTimer, ( void * ) ulExecutionCount );
/* Obtain the current tick count. */
xTimeNow = xTaskGetTickCount();
/* The handle of the one-shot timer was stored in xOneShotTimer when the timer was created.
Compare the handle passed into this function with xOneShotTimer to determine if it was the
one-shot or auto-reload timer that expired, then output a string to show the time at which
the callback was executed. */

Serial.print("Auto-reload timer callback executing ");
Serial.println( xTimeNow/31 );
if( ulExecutionCount >= 5 )
{
xTimerChangePeriod( xAutoReloadTimer, /* The timer being updated. */
mainAUTO_RELOAD_TIMER_PERIOD2, /* The new period for the timer. */
0 ); /* Do not block when sending this command. */
}
}

Arduino Serial Monitor Output 

As you can see from the output of the Arduino serial monitor that first prvTimerCallback function executed after every one second. But after the timer being updated with a new period, prvTimerCallback function starts to execute after every 2 seconds. For demonstration purposes, you can define a LED toggle function which will toggle LED first at the rate of one second. After that timer period will update, LED will toggle at the rate of two seconds. 

FreeRTOS Software timer period change example with Arduino

Video Demonstration 

FreeRTOS Resetting Software Timer 

FreeRTOS API also provides functionality to reset software timers. Resetting a software timer just re-start the timer, but its period remains the same. The new expiry time will be calculated as soon as reset time API will be called.  

This picture shows the demonstration of software timer resetting API. As you can see, at the start timer t1 beings with a period of 6 ticks. That means, it will expire on t7. On the contrary, timer1 resets at t5. Therefore, its new expiry time calculates at time t7. Hence, it will expire on t11. But again, timer1 resets at t9. Again its new expiry calculates at time9. Now, timer1 will expire at time t15. Hence, its callback function will be executed at t15.

FreeRTOS resetting a software timer with Arduino

FreeRTOS Sofware Timer Reset API

xTimerReset()  is used to reset software timer. xTimerResetFromISR() is a interrupt service routine version. This is a prototype of this API.  

BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
  • The first input argument to xTimerChangePeriod is a handle of a software timer whose period you want to change
  • xTicksToWait uses the timer command queue to send the ‘change period’ command to the daemon task. xTicksToWait specifies the maximum amount of time the calling task should remain in the Blocked state to wait for space to become available on the timer command queue, should the queue already be full.

For example code, we recommend you use the above given code and try to experiment with a period of timer using FreeRTOS xTimerReset() API.

Leave a Comment