( const char * const pcTimerName,
const TickType_t xTimerPeriod,
const UBaseType_t uxAutoReload,
void * const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction );
Creates a new software timer instance and
returns a handle by which the timer can be referenced.
For this RTOS API function to be available:
configUSE_TIMERS and configSUPPORT_DYNAMIC_ALLOCATION
must both be set to 1 in FreeRTOSConfig.h (configSUPPORT_DYNAMIC_ALLOCATION
can also be left undefined, in which case it will default to 1).
The FreeRTOS/Source/timers.c C source file must be included in the
Each software timer requires a small amount of RAM that is used to hold the
timer's state. If a timer is created using xTimerCreate() then this
RAM is automatically allocated from the FreeRTOS heap.
If a software timer is created using xTimerCreateStatic()
then the RAM is provided by the application writer, which requires an additional
parameter, but allows the RAM to be statically allocated at compile
time. See the Static Vs
Dynamic allocation page for more information.
Timers are created in the dormant state. The xTimerStart(),
API functions can all be used to transition a timer into the active state.
A human readable text name that is assigned to the timer. This is done purely to assist
debugging. The RTOS kernel itself only ever references a timer by its handle,
and never by its name.
The period of the timer. The period is specified in ticks, and
the macro pdMS_TO_TICKS() can be used to convert a time
specified in milliseconds to a time specified in ticks. For
example, if the timer must expire after 100 ticks, then
simply set xTimerPeriod to 100. Alternatively, if the timer
must expire after 500ms, then set xTimerPeriod to
pdMS_TO_TICKS( 500 ). pdMS_TO_TICKS() can only be used if
configTICK_RATE_HZ is less than or equal to 1000.
If uxAutoReload is set to pdTRUE, then the timer will
expire repeatedly with a frequency set by the xTimerPeriod parameter. If
uxAutoReload is set to pdFALSE, then the timer will be a one-shot and enter
the dormant state after it expires.
An identifier that is assigned to the timer being created.
Typically this would be used in the timer callback function to
identify which timer expired when the same callback function
is assigned to more than one timer, or together with the
API functions to save a value between calls to the timer's
The function to call when the timer expires. Callback functions must
have the prototype defined by TimerCallbackFunction_t, which is:
void vCallbackFunction( TimerHandle_t xTimer );.
If the timer is created successfully then a handle to the newly
created timer is returned. If the timer cannot be created because either
there is insufficient FreeRTOS heap remaining to allocate the timer
structures, or the timer period was set to 0, then NULL is returned.
#define NUM_TIMERS 5
/* An array to hold handles to the created timers. */
TimerHandle_t xTimers[ NUM_TIMERS ];
/* Define a callback function that will be used by multiple timer
instances. The callback function does nothing but count the number
of times the associated timer expires, and stop the timer once the
timer has expired 10 times. The count is saved as the ID of the
void vTimerCallback( TimerHandle_t xTimer )
const uint32_t ulMaxExpiryCountBeforeStopping = 10;
/* Optionally do something if the pxTimer parameter is NULL. */
configASSERT( pxTimer );
/* The number of times this timer has expired is saved as the
timer's ID. Obtain the count. */
ulCount = ( uint32_t ) pvTimerGetTimerID( xTimer );
/* Increment the count, then test to see if the timer has expired
ulMaxExpiryCountBeforeStopping yet. */
/* If the timer has expired 10 times then stop it from running. */
if( ulCount >= ulMaxExpiryCountBeforeStopping )
/* Do not use a block time if calling a timer API function
from a timer callback function, as doing so could cause a
xTimerStop( pxTimer, 0 );
/* Store the incremented count back into the timer's ID field
so it can be read back again the next time this software timer
vTimerSetTimerID( xTimer, ( void * ) ulCount );
void main( void )
/* Create then start some timers. Starting the timers before
the RTOS scheduler has been started means the timers will start
running immediately that the RTOS scheduler starts. */
for( x = 0; x < NUM_TIMERS; x++ )
xTimers[ x ] = xTimerCreate
( /* Just a text name, not used by the RTOS
/* The timer period in ticks, must be
greater than 0. */
( 100 * x ) + 100,
/* The timers will auto-reload themselves
when they expire. */
/* The ID is used to store a count of the
number of times the timer has expired, which
is initialised to 0. */
( void * ) 0,
/* Each timer calls the same callback when
it expires. */
if( xTimers[ x ] == NULL )
/* The timer was not created. */
/* Start the timer. No block time is specified, and
even if one was it would be ignored because the RTOS
scheduler has not yet been started. */
if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
/* The timer could not be set into the Active
Create tasks here.
/* Starting the RTOS scheduler will start the timers running
as they have already been set into the active state. */
/* Should not reach here. */
for( ;; );
Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2016 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd..
See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.