KernelSoftware timers

Updated Jun 2025

xTimerCreateStatic

[Timer API]

timers.h

1 TimerHandle_t xTimerCreateStatic
2                 ( const char * const pcTimerName,
3                   const TickType_t xTimerPeriod,
4                   const UBaseType_t uxAutoReload,
5                   void * const pvTimerID,
6                   TimerCallbackFunction_t pxCallbackFunction
7                   StaticTimer_t *pxTimerBuffer );

Copy

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:

1. configUSE_TIMERS and configSUPPORT_STATIC_ALLOCATION must both be set to 1 in FreeRTOSConfig.h.
2. The FreeRTOS/Source/timer.c C source file must be included in the build.

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 the required 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(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod(), and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.

Parameters:

• pcTimerName

  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.

• xTimerPeriod

  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. The timer period must be greater than 0.

• uxAutoReload

  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.

• pvTimerID

  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 vTimerSetTimerID() and pvTimerGetTimerID()API functions to save a value between calls to the timer's callback function.

• pxCallbackFunction

  The function to call when the timer expires. Callback functions must have the prototype defined by TimerCallbackFunction_t, which is:

  1void vCallbackFunction( TimerHandle_t xTimer );
  
  Copy

• pxTimerBuffer

  Must point to a variable of type StaticTimer_t, which is then used to hold the timer's state.

Returns:

If the timer is created successfully then a handle to the newly created timer is returned. If pxTimerBuffer is NULL then the timer will not be created and NULL is returned.

Example usage:

1 pxTimerBuffer #define NUM_TIMERS 5
2
3 /* An array to hold handles to the created timers. */
4 TimerHandle_t xTimers[ NUM_TIMERS ];
5
6 /* An array of StaticTimer_t structures, which are used to store
7    the state of each created timer. */
8 StaticTimer_t xTimerBuffers[ NUM_TIMERS ];
9
10 /* Define a callback function that will be used by multiple timer
11    instances. The callback function does nothing but count the number
12    of times the associated timer expires, and stop the timer once the
13    timer has expired 10 times. The count is saved as the ID of the
14    timer. */
15 void vTimerCallback( TimerHandle_t xTimer )
16 {
17 const uint32_t ulMaxExpiryCountBeforeStopping = 10;
18 uint32_t ulCount;
19
20    /* Optionally do something if the pxTimer parameter is NULL. */
21    configASSERT( pxTimer );
22
23    /* The number of times this timer has expired is saved as the
24       timer's ID. Obtain the count. */
25    ulCount = ( uint32_t ) pvTimerGetTimerID( xTimer );
26
27    /* Increment the count, then test to see if the timer has expired
28       ulMaxExpiryCountBeforeStopping yet. */
29    ulCount++;
30
31    /* If the timer has expired 10 times then stop it from running. */
32    if( ulCount >= ulMaxExpiryCountBeforeStopping )
33    {
34        /* Do not use a block time if calling a timer API function
35           from a timer callback function, as doing so could cause a
36           deadlock! */
37        xTimerStop( xTimer, 0 );
38    }
39    else
40    {
41       /* Store the incremented count back into the timer's ID field
42          so it can be read back again the next time this software timer
43          expires. */
44       vTimerSetTimerID( xTimer, ( void * ) ulCount );
45    }
46 }
47
48 void main( void )
49 {
50 long x;
51
52    /* Create then start some timers. Starting the timers before
53       the RTOS scheduler has been started means the timers will start
54       running immediately that the RTOS scheduler starts. */
55    for( x = 0; x < NUM_TIMERS; x++ )
56    {
57        xTimers[ x ] = xTimerCreateStatic
58                  ( /* Just a text name, not used by the RTOS kernel. */
59                    "Timer",
60                    /* The timer period in ticks, must be greater than 0. */
61                    ( 100 * x ) + 100,
62                    /* The timers will auto-reload themselves when they expire. */
63                    pdTRUE,
64                    /* The ID is used to store a count of the number of times
65                       the timer has expired, which is initialised to 0. */
66                    ( void * ) 0,
67                    /* Each timer calls the same callback when it expires. */
68                    vTimerCallback,
69                    /* Pass in the address of a StaticTimer_t variable, which
70                       will hold the data associated with the timer being
71                       created. */
72                    &( xTimerBuffers[ x ] );
73                  );
74
75        if( xTimers[ x ] == NULL )
76        {
77            /* The timer was not created. */
78        }
79        else
80        {
81            /* Start the timer. No block time is specified, and
82               even if one was it would be ignored because the RTOS
83               scheduler has not yet been started. */
84            if( [xTimerStart](/Documentation/02-Kernel/04-API-references/11-Software-timers/04-xTimerStart)( xTimers[ x ], 0 ) != pdPASS )
85            {
86                /* The timer could not be set into the Active state. */
87            }
88        }
89    }
90
91    /* ...
92 Create tasks here.
93 ... */
94
95    /* Starting the RTOS scheduler will start the timers running as they have
96       already been set into the active state. */
97    vTaskStartScheduler();
98
99    /* Should not reach here. */
100    for( ;; );
101 }

Copy