xTimerCreate() function in FreeRTOS

Introduction

The xTimerCreate() function helps you make a timer that runs code after a set time or repeatedly. It makes managing timed tasks easy without blocking your program.

You want to run a task after a delay, like turning off a light after 5 minutes.

You need to repeat an action regularly, like checking a sensor every second.

You want to stop a task if it takes too long, like a timeout for a button press.

You want to schedule a task without using delay functions that freeze your program.

Syntax

FreeRTOS

TimerHandle_t xTimerCreate(
    const char * const pcTimerName,
    const TickType_t xTimerPeriodInTicks,
    const UBaseType_t uxAutoReload,
    void * const pvTimerID,
    TimerCallbackFunction_t pxCallbackFunction
);

pcTimerName is a name you give the timer for easy identification.

xTimerPeriodInTicks sets how long before the timer runs, in ticks (small time units).

Examples

This creates a one-shot timer named "MyTimer" that runs myTimerCallback after 1000 milliseconds.

FreeRTOS

TimerHandle_t myTimer = xTimerCreate(
    "MyTimer",
    pdMS_TO_TICKS(1000),
    pdFALSE,
    NULL,
    myTimerCallback
);

This creates a timer that repeats every 500 milliseconds and passes an ID of 1 to the callback.

FreeRTOS

TimerHandle_t periodicTimer = xTimerCreate(
    "PeriodicTimer",
    pdMS_TO_TICKS(500),
    pdTRUE,
    (void *) 1,
    periodicCallback
);

Sample Program

This program creates a one-shot timer that calls vTimerCallback after 2 seconds. It starts the timer and simulates waiting. The callback prints a message.

FreeRTOS

#include "FreeRTOS.h"
#include "timers.h"
#include "task.h"
#include <stdio.h>

void vTimerCallback(TimerHandle_t xTimer) {
    printf("Timer callback called!\n");
}

int main(void) {
    TimerHandle_t xMyTimer = xTimerCreate(
        "TestTimer",
        pdMS_TO_TICKS(2000),
        pdFALSE,
        NULL,
        vTimerCallback
    );

    if (xMyTimer != NULL) {
        xTimerStart(xMyTimer, 0);
    }

    // Simulate scheduler running and waiting for timer
    // In real FreeRTOS, the scheduler would handle this
    for (int i = 0; i < 3; i++) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }

    return 0;
}

Important Notes

Timers run their callbacks in the timer service task, so keep callbacks short and fast.

Use pdMS_TO_TICKS() to convert milliseconds to ticks for easier timing.

Remember to start the timer with xTimerStart() after creating it.

Summary

xTimerCreate() makes timers to run code after delays or repeatedly.

Timers help manage time-based tasks without stopping your program.

Always start your timer after creating it to make it work.

Practice

1. What is the main purpose of the xTimerCreate() function in FreeRTOS?

easy

A. To create a software timer that can run a function after a delay or repeatedly

B. To start the scheduler for task management

C. To create a hardware interrupt

D. To allocate memory for tasks

Solution

1. Step 1: Understand the role of xTimerCreate()

   The function xTimerCreate() is used to create software timers in FreeRTOS, which can execute a callback function after a delay or periodically.

2. Step 2: Compare with other options

   Starting the scheduler, creating hardware interrupts, or allocating memory for tasks are not the purpose of xTimerCreate().

3. Final Answer:

   To create a software timer that can run a function after a delay or repeatedly -> Option A

4. Quick Check:

   Timer creation = software timer setup [OK]

Hint: xTimerCreate() makes timers to run code later [OK]

Common Mistakes:

• Confusing timer creation with starting the scheduler
• Thinking it creates hardware interrupts
• Assuming it allocates memory for tasks

2. Which of the following is the correct way to call xTimerCreate() to create a one-shot timer named "MyTimer" with a 1000 tick delay and a callback function TimerCallback?

easy

A. xTimerCreate("MyTimer", 1000, pdTRUE, NULL, TimerCallback);

B. xTimerCreate("MyTimer", 1000, pdFALSE, NULL, TimerCallback);

C. xTimerCreate("MyTimer", 1000, pdFALSE, TimerCallback, NULL);

D. xTimerCreate("MyTimer", 1000, pdFALSE, NULL, &TimerCallback);

Solution

1. Step 1: Understand xTimerCreate() parameters

   The parameters are: name (string), period (ticks), auto-reload (pdTRUE or pdFALSE), timer ID (can be NULL), and callback function pointer.

2. Step 2: Check each option

   xTimerCreate("MyTimer", 1000, pdFALSE, NULL, TimerCallback); correctly uses pdFALSE for one-shot, NULL for timer ID, and TimerCallback as the function pointer. xTimerCreate("MyTimer", 1000, pdTRUE, NULL, TimerCallback); uses pdTRUE (auto-reload), which is wrong for one-shot. xTimerCreate("MyTimer", 1000, pdFALSE, TimerCallback, NULL); swaps callback and timer ID. xTimerCreate("MyTimer", 1000, pdFALSE, NULL, &TimerCallback); uses &TimerCallback which is incorrect; function name alone is used.

3. Final Answer:

   xTimerCreate("MyTimer", 1000, pdFALSE, NULL, TimerCallback); -> Option B

4. Quick Check:

   One-shot timer = pdFALSE, callback last parameter [OK]

Hint: Use pdFALSE for one-shot, callback is last parameter [OK]

Common Mistakes:

• Using pdTRUE for one-shot timers
• Swapping callback and timer ID parameters
• Using & before callback function name

3. Consider the following code snippet:

TimerHandle_t myTimer = xTimerCreate("Timer1", 500, pdTRUE, NULL, TimerCallback);
if (myTimer != NULL) {
    xTimerStart(myTimer, 0);
}

What will happen when this code runs?

medium

A. A timer named "Timer1" will start and call TimerCallback every 500 ticks repeatedly

B. The timer will run only once after 500 ticks and then stop

C. The code will cause a compile-time error due to wrong parameters

D. The timer will never start because xTimerStart is missing

Solution

1. Step 1: Analyze timer creation parameters

   The timer is created with pdTRUE, meaning it is auto-reload and will repeat. The period is 500 ticks.

2. Step 2: Check timer start call

   The timer is started immediately with xTimerStart(myTimer, 0), so it will begin running and call TimerCallback every 500 ticks repeatedly.

3. Final Answer:

   A timer named "Timer1" will start and call TimerCallback every 500 ticks repeatedly -> Option A

4. Quick Check:

   pdTRUE + xTimerStart = repeated timer [OK]

Hint: pdTRUE means repeat; xTimerStart actually starts timer [OK]

Common Mistakes:

• Thinking pdTRUE means one-shot
• Forgetting to call xTimerStart after creation
• Assuming timer runs without starting

4. Identify the error in the following code snippet:

TimerHandle_t timer = xTimerCreate("Timer", 1000, pdFALSE, NULL, TimerCallback);
xTimerStart(timer, 0);
// ...
void TimerCallback(TimerHandle_t xTimer) {
    // callback code
}

medium

A. TimerCallback function is defined after it is used, causing a compile error

B. pdFALSE should be pdTRUE for one-shot timers

C. xTimerStart is called before checking if timer is NULL

D. Timer name cannot be a string literal

Solution

1. Step 1: Check timer creation and start sequence

   The timer is created and immediately started without checking if the returned handle is NULL, which can cause runtime errors if creation failed.

2. Step 2: Verify other parts

   Defining TimerCallback after usage is allowed in C if a prototype exists or compiler supports it. pdFALSE is correct for one-shot. Timer name as string literal is valid.

3. Final Answer:

   xTimerStart is called before checking if timer is NULL -> Option C

4. Quick Check:

   Always check timer handle before starting [OK]

Hint: Check timer handle != NULL before starting [OK]

Common Mistakes:

• Skipping NULL check on timer handle
• Confusing pdFALSE and pdTRUE for timer type
• Thinking string literals are invalid timer names

5. You want to create a timer that runs a callback every 200 ticks but only after an initial delay of 1000 ticks. Which approach using xTimerCreate() and FreeRTOS timers is correct?

hard

A. Create a one-shot timer with 200 ticks period and restart it manually every 1000 ticks

B. Create a one-shot timer with 1200 ticks period and use it as auto-reload

C. Create an auto-reload timer with 1200 ticks period and start it immediately

D. Create an auto-reload timer with 200 ticks period and start it after a one-shot timer of 1000 ticks triggers the first callback to start the auto-reload timer

Solution

1. Step 1: Understand the requirement

   The timer should wait 1000 ticks before first callback, then run every 200 ticks repeatedly.

2. Step 2: Analyze options

   Create an auto-reload timer with 200 ticks period and start it after a one-shot timer of 1000 ticks triggers the first callback to start the auto-reload timer uses a one-shot timer for initial delay, which on expiry starts the auto-reload timer for repeated 200 ticks callbacks. This matches the requirement. Create a one-shot timer with 1200 ticks period and use it as auto-reload incorrectly combines periods and auto-reload. Create an auto-reload timer with 1200 ticks period and start it immediately starts immediately without initial delay. Create a one-shot timer with 200 ticks period and restart it manually every 1000 ticks misuses one-shot timer and manual restart timing.

3. Final Answer:

   Create an auto-reload timer with 200 ticks period and start it after a one-shot timer of 1000 ticks triggers the first callback to start the auto-reload timer -> Option D

4. Quick Check:

   Initial delay + repeated timer = chain one-shot then auto-reload [OK]

Hint: Use one-shot timer first, then start auto-reload timer [OK]

Common Mistakes:

• Trying to set initial delay inside one timer period
• Using wrong timer type for initial delay
• Starting auto-reload timer immediately without delay