xTimerCreate() function in FreeRTOS - Step-by-Step Execution

Concept Flow - xTimerCreate() function

Call xTimerCreate() with parameters

↓

Allocate Timer Object

↓

Set Timer Name

↓

Set Timer Period

↓

Set Auto-Reload Flag

↓

Set Timer Callback Function

↓

Return Timer Handle or NULL if fail

The function creates a timer object step-by-step and returns a handle to it or NULL if creation fails.

Execution Sample

FreeRTOS

TimerHandle_t myTimer = xTimerCreate(
  "MyTimer",
  pdMS_TO_TICKS(1000),
  pdTRUE,
  (void *) 0,
  vTimerCallback
);

Creates a timer named 'MyTimer' that fires every 1000 ms repeatedly and calls vTimerCallback when it expires.

Execution Table

Step	Parameter	Action	Result
1	pcTimerName = "MyTimer"	Store timer name	Name set to 'MyTimer'
2	xTimerPeriodInTicks = pdMS_TO_TICKS(1000)	Convert ms to ticks	Period set to 1000 ticks
3	uxAutoReload = pdTRUE	Set auto-reload flag	Timer will auto-reload
4	pvTimerID = (void *) 0	Store timer ID	Timer ID set to 0
5	pxCallbackFunction = vTimerCallback	Set callback	Callback set to vTimerCallback
6	Allocate timer object	Create timer in memory	Timer object created
7	Return timer handle	Provide handle to caller	Handle returned (non-NULL)

💡 Timer created successfully and handle returned; if allocation failed, NULL would be returned.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	After Step 6	Final
pcTimerName	NULL	"MyTimer"	"MyTimer"	"MyTimer"	"MyTimer"	"MyTimer"	"MyTimer"	"MyTimer"
xTimerPeriodInTicks	0	0	1000	1000	1000	1000	1000	1000
uxAutoReload	0	0	0	1 (pdTRUE)	1	1	1	1
pvTimerID	NULL	NULL	NULL	NULL	0	0	0	0
pxCallbackFunction	NULL	NULL	NULL	NULL	NULL	vTimerCallback	vTimerCallback	vTimerCallback
Timer Object	NULL	NULL	NULL	NULL	NULL	NULL	Allocated	Allocated
Timer Handle	NULL	NULL	NULL	NULL	NULL	NULL	NULL	Non-NULL handle

Key Moments - 3 Insights

Why does xTimerCreate return NULL sometimes?

If the timer object cannot be allocated in memory (see Step 6 in execution_table), xTimerCreate returns NULL indicating failure.

What does the auto-reload flag control?

The auto-reload flag (Step 3) determines if the timer restarts automatically after expiry (pdTRUE) or runs only once (pdFALSE).

What is the role of the callback function?

The callback function (Step 5) is called when the timer expires to perform user-defined actions.

Visual Quiz - 3 Questions

Look at the execution_table, what is the timer period in ticks after Step 2?

A 0 ticks

B 500 ticks

C 1000 ticks

D Undefined

💡 Hint

Check the 'Result' column in row for Step 2 in execution_table.

At which step is the callback function assigned?

A Step 3

B Step 5

C Step 6

D Step 7

💡 Hint

Look at the 'Parameter' and 'Action' columns in execution_table for callback assignment.

If the timer allocation fails, what does xTimerCreate return?

A NULL

B An error code

C A valid timer handle

D The timer name

💡 Hint

Refer to the exit_note and Step 6 in execution_table about allocation failure.

Concept Snapshot

xTimerCreate() creates a software timer in FreeRTOS.
Syntax: xTimerCreate(name, period_ticks, auto_reload, id, callback)
Returns a timer handle or NULL if creation fails.
Auto-reload controls if timer repeats.
Callback runs when timer expires.

Full Transcript

The xTimerCreate() function in FreeRTOS creates a software timer object. It takes parameters like the timer's name, period in ticks, auto-reload flag, an ID, and a callback function. The function allocates memory for the timer, sets these parameters, and returns a handle to the timer. If memory allocation fails, it returns NULL. The auto-reload flag determines if the timer repeats automatically. The callback function is called when the timer expires. This trace shows each step from parameter setting to returning the handle, helping beginners understand how the timer is created internally.

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