One-shot vs auto-reload timers in FreeRTOS - Trade-offs & Expert Analysis

Overview - One-shot vs auto-reload timers

What is it?

In FreeRTOS, timers are tools that let your program do something after a delay. One-shot timers run once and stop, while auto-reload timers repeat their action at regular intervals. Both help manage tasks without blocking the main program flow.

Why it matters

Without timers, programs would waste time waiting or miss important events. Timers let your system react on time and keep running smoothly, like a kitchen timer reminding you when food is ready. Choosing the right timer type ensures your program behaves correctly and efficiently.

Where it fits

Before learning timers, you should understand tasks and scheduling in FreeRTOS. After mastering timers, you can explore advanced synchronization and event handling techniques to build responsive embedded systems.

Mental Model

Core Idea

One-shot timers trigger once after a delay, while auto-reload timers keep triggering repeatedly at set intervals.

Think of it like...

Think of a one-shot timer like an alarm clock you set once to wake you up, and an auto-reload timer like a metronome that keeps ticking steadily to keep the beat.

┌───────────────┐       ┌───────────────┐
│ One-shot Timer│       │Auto-reload Timer│
├───────────────┤       ├───────────────┤
│ Starts delay  │       │Starts delay   │
│ Waits once    │       │Waits interval │
│ Fires once    │       │Fires repeatedly│
│ Stops        │       │Resets and repeats│
└───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a FreeRTOS timer?

Concept: Introduce the basic idea of timers in FreeRTOS as tools to schedule actions after delays.

In FreeRTOS, a timer is a software object that waits for a set time and then runs a function called a callback. This lets your program do things later without stopping everything else. Timers help manage time-based events easily.

Result

You understand that timers let your program schedule future actions without blocking.

Knowing timers let you handle delays without freezing your program is key to writing efficient embedded code.

2

Foundation

Creating and starting a timer

Concept: Learn how to create a timer and start it running in FreeRTOS.

To use a timer, you create it with xTimerCreate(), giving it a name, period, auto-reload flag, ID, and callback function. Then you start it with xTimerStart(). The timer counts down and calls your function when done.

Result

You can set up a timer that will call your code after a delay.

Understanding the creation and start process is essential before choosing timer types.

3

Intermediate

One-shot timer behavior

🤔Before reading on: Do you think a one-shot timer repeats automatically or stops after firing once? Commit to your answer.

Concept: Explain how one-shot timers fire once and then stop until restarted.

A one-shot timer waits for its set period, then calls its callback once. After firing, it stops and does not restart unless you manually start it again. This is useful for single delayed actions.

Result

The timer fires once and then stops until restarted.

Knowing one-shot timers stop automatically helps prevent unintended repeated actions.

4

Intermediate

Auto-reload timer behavior

🤔Before reading on: Will an auto-reload timer fire once or keep firing repeatedly? Commit to your answer.

Concept: Show how auto-reload timers automatically restart after firing to repeat actions.

An auto-reload timer waits for its period, calls its callback, then resets and starts counting again automatically. This repeats forever or until you stop the timer. It's great for periodic tasks like blinking an LED.

Result

The timer fires repeatedly at fixed intervals without manual restarts.

Understanding auto-reload timers automate repetition saves effort and ensures consistent timing.

5

Intermediate

Choosing between one-shot and auto-reload

🤔Before reading on: Which timer type would you use for a single delayed action versus a repeating task? Commit to your answer.

Concept: Help decide when to use each timer type based on task needs.

Use one-shot timers for actions that happen once after a delay, like a timeout. Use auto-reload timers for repeated actions, like polling sensors regularly. Picking the right type avoids bugs and wasted CPU time.

Result

You can select the correct timer type for your task's timing needs.

Knowing when to use each timer type prevents logic errors and improves system efficiency.

6

Advanced

Timer callback execution context

🤔Before reading on: Do timer callbacks run in the main task or a special timer task? Commit to your answer.

Concept: Explain that timer callbacks run in a dedicated timer service task, not in interrupt or main tasks.

FreeRTOS runs timer callbacks in a special timer service task. This means callbacks should be quick and not block. Long or blocking code in callbacks can delay other timers or tasks. Use synchronization if needed.

Result

You understand the execution context and constraints of timer callbacks.

Knowing callbacks run in a timer task helps avoid common bugs like deadlocks or missed deadlines.

7

Expert

Surprising behavior with timer resets and stops

🤔Before reading on: If you reset a one-shot timer before it fires, does it delay the callback or cause multiple calls? Commit to your answer.

Concept: Reveal subtle effects of resetting or stopping timers and how they affect callback timing.

Resetting a one-shot timer restarts its countdown, delaying the callback. Stopping a timer before it fires cancels the callback. For auto-reload timers, stopping pauses repetition. Misusing these can cause missed or duplicated callbacks.

Result

You can predict how timer control functions affect callback timing precisely.

Understanding timer control nuances prevents timing bugs that are hard to debug in real systems.

Under the Hood

FreeRTOS timers are software timers managed by a dedicated timer service task. When a timer starts, its countdown is tracked using the system tick count. When the countdown reaches zero, the timer's callback is queued to run in the timer service task context. Auto-reload timers automatically reset their countdown after firing, while one-shot timers do not. This design avoids running callbacks in interrupt context, improving safety and flexibility.

Why designed this way?

Running callbacks in a separate timer service task avoids the complexity and risks of executing user code in interrupts. It allows callbacks to use FreeRTOS APIs safely. The auto-reload and one-shot modes provide flexibility for different timing needs without extra coding. This design balances efficiency, safety, and ease of use in embedded systems.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Timer Created │──────▶│ Timer Started │──────▶│ Countdown Runs│
└───────────────┘       └───────────────┘       └───────────────┘
                                   │                      │
                                   ▼                      ▼
                        ┌─────────────────┐      ┌─────────────────┐
                        │ Countdown Zero  │      │ Timer Service   │
                        │ (Timer Fires)   │─────▶│ Task Executes   │
                        └─────────────────┘      │ Callback        │
                                   │             └─────────────────┘
                                   │
                    ┌──────────────┴───────────────┐
                    │                              │
          ┌───────────────────┐          ┌───────────────────┐
          │ One-shot Timer    │          │ Auto-reload Timer │
          │ Stops after fire  │          │ Resets and repeats│
          └───────────────────┘          └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a one-shot timer automatically restart after firing? Commit to yes or no.

Common Belief: One-shot timers automatically restart after firing once.

Reality: One-shot timers fire once and then stop until manually restarted.

Why it matters: Assuming automatic restart can cause missed actions or unexpected program behavior.

Quick: Do timer callbacks run in interrupt context? Commit to yes or no.

Common Belief: Timer callbacks run inside interrupts, so they must be very short.

Reality: Timer callbacks run in a dedicated timer service task, not in interrupt context.

Why it matters: Misunderstanding this can lead to overly simplified callbacks or unsafe code assumptions.

Quick: If you reset a one-shot timer before it fires, does it cause multiple callbacks? Commit to yes or no.

Common Belief: Resetting a one-shot timer before it fires causes multiple callbacks to queue up.

Reality: Resetting restarts the countdown and only one callback will occur after the new delay.

Why it matters: Believing otherwise may cause unnecessary complex code to prevent duplicate callbacks.

Quick: Does stopping an auto-reload timer immediately prevent any further callbacks? Commit to yes or no.

Common Belief: Stopping an auto-reload timer immediately cancels all pending callbacks.

Reality: Stopping prevents future callbacks but does not interrupt a callback already running.

Why it matters: Misunderstanding this can cause race conditions or unexpected callback executions.

Expert Zone

1

Timer callback execution order depends on timer periods and the timer service task scheduling, which can affect timing precision.

2

Using timer IDs allows passing context to callbacks, enabling flexible and reusable timer functions.

3

Excessive or long-running callbacks can delay other timers, so balancing callback workload is critical for real-time behavior.

When NOT to use

Timers are not suitable for very high precision or very short delays due to tick resolution and task scheduling delays. For such cases, hardware timers or interrupts should be used instead.

Production Patterns

In production, auto-reload timers often handle periodic sensor reads or status updates, while one-shot timers manage timeouts or delayed retries. Combining timers with event groups or queues enables complex timed workflows.

Connections

Hardware Timers

Complementary tools

Understanding software timers alongside hardware timers helps design systems that balance precision and flexibility.

Event-driven Programming

Builds-on

Timers trigger events after delays, fitting naturally into event-driven designs that react to time and other signals.

Project Management Deadlines

Analogous pattern

Just like timers schedule tasks in code, deadlines schedule work in projects, showing how timing controls flow in many fields.

Common Pitfalls

#1 Using a one-shot timer when a repeating action is needed.

Wrong approach:

xTimerCreate("Timer", pdMS_TO_TICKS(1000), pdFALSE, 0, callback); // one-shot used for blinking LED

Correct approach:

xTimerCreate("Timer", pdMS_TO_TICKS(1000), pdTRUE, 0, callback); // auto-reload for blinking LED

Root cause:

Confusing the auto-reload flag leads to timers not repeating as expected.

#2 Running long or blocking code inside timer callbacks.

Wrong approach:

void callback(TimerHandle_t xTimer) { vTaskDelay(1000); /* blocking delay */ }

Correct approach:

void callback(TimerHandle_t xTimer) { xTaskNotifyGive(taskHandle); /* notify task to handle work */ }

Root cause:

Not realizing callbacks run in a shared timer task causes delays and missed timer events.

#3 Assuming timer callbacks run in interrupt context and using ISR-only APIs.

Wrong approach:

void callback(TimerHandle_t xTimer) { xQueueSendFromISR(queue, &data, NULL); }

Correct approach:

void callback(TimerHandle_t xTimer) { xQueueSend(queue, &data, 0); }

Root cause:

Misunderstanding callback context leads to using wrong FreeRTOS APIs.

Key Takeaways

FreeRTOS timers let you schedule code to run after delays without blocking your program.

One-shot timers fire once and stop, while auto-reload timers repeat automatically at intervals.

Timer callbacks run in a special timer service task, so they must be quick and non-blocking.

Choosing the right timer type and managing callbacks properly prevents bugs and timing issues.

Understanding timer internals helps write reliable, efficient embedded applications.

Practice

1. What is the main difference between a one-shot timer and an auto-reload timer in FreeRTOS?

easy

A. One-shot timers run once after a delay; auto-reload timers run repeatedly at fixed intervals.

B. One-shot timers run repeatedly; auto-reload timers run only once.

C. One-shot timers are faster than auto-reload timers.

D. Auto-reload timers cannot be stopped once started.

Solution

1. Step 1: Understand timer behavior

   One-shot timers execute their callback function only once after the specified delay.

2. Step 2: Compare with auto-reload timers

   Auto-reload timers automatically restart after each expiration, running repeatedly at fixed intervals.

3. Final Answer:

   One-shot timers run once after a delay; auto-reload timers run repeatedly at fixed intervals. -> Option A

4. Quick Check:

   One-shot = single run, Auto-reload = repeated runs [OK]

Hint: One-shot = once, Auto-reload = repeat [OK]

Common Mistakes:

• Confusing which timer runs repeatedly
• Thinking one-shot timers repeat automatically
• Assuming auto-reload timers cannot be stopped

2. Which of the following is the correct way to create an auto-reload timer in FreeRTOS using xTimerCreate?

easy

A. xTimerCreate("Timer", pdMS_TO_TICKS(1000), pdFALSE, NULL, TimerCallback);

B. xTimerCreate("Timer", 1000, pdTRUE, NULL, TimerCallback);

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

D. xTimerCreate("Timer", pdMS_TO_TICKS(1000), pdTRUE, NULL, TimerCallback);

Solution

1. Step 1: Identify auto-reload parameter

   The third parameter of xTimerCreate is uxAutoReload, which should be pdTRUE for auto-reload timers.

2. Step 2: Check time parameter format

   Use pdMS_TO_TICKS(1000) to convert milliseconds to ticks correctly.

3. Final Answer:

   xTimerCreate("Timer", pdMS_TO_TICKS(1000), pdTRUE, NULL, TimerCallback); -> Option D

4. Quick Check:

   Auto-reload needs pdTRUE and tick conversion [OK]

Hint: Auto-reload = pdTRUE, use pdMS_TO_TICKS for time [OK]

Common Mistakes:

• Using pdFALSE for auto-reload timers
• Passing raw milliseconds instead of ticks
• Confusing parameter order

3. Consider this FreeRTOS timer code snippet:

TimerHandle_t timer = xTimerCreate("MyTimer", pdMS_TO_TICKS(500), pdFALSE, NULL, TimerCallback);
xTimerStart(timer, 0);

What will happen when this timer expires?

medium

A. The TimerCallback function will be called once after 500 ms.

B. The TimerCallback function will be called repeatedly every 500 ms.

C. The timer will never start because pdFALSE is invalid.

D. The TimerCallback function will be called immediately and repeatedly.

Solution

1. Step 1: Analyze timer creation parameters

   The timer is created with pdFALSE for auto-reload, meaning it is a one-shot timer.

2. Step 2: Understand timer start and expiration

   After starting, the timer waits 500 ms, then calls TimerCallback once and stops.

3. Final Answer:

   The TimerCallback function will be called once after 500 ms. -> Option A

4. Quick Check:

   pdFALSE means one-shot = single callback [OK]

Hint: pdFALSE means one-shot, callback runs once [OK]

Common Mistakes:

• Thinking pdFALSE means repeated calls
• Assuming timer starts immediately
• Confusing pdFALSE with invalid parameter

4. You wrote this code to create an auto-reload timer but it only runs once:

TimerHandle_t timer = xTimerCreate("Timer", pdMS_TO_TICKS(1000), pdFALSE, NULL, TimerCallback);
xTimerStart(timer, 0);

What is the likely error?

medium

A. The timer period is too short to see repeated calls.

B. xTimerStart was called with zero block time.

C. The auto-reload parameter is set to pdFALSE instead of pdTRUE.

D. The timer callback function is missing.

Solution

1. Step 1: Check auto-reload parameter

   The timer was created with pdFALSE, which means it is a one-shot timer.

2. Step 2: Understand effect on timer behavior

   Because of pdFALSE, the timer runs only once and does not auto-reload.

3. Final Answer:

   The auto-reload parameter is set to pdFALSE instead of pdTRUE. -> Option C

4. Quick Check:

   pdFALSE disables auto-reload, causing single run [OK]

Hint: Auto-reload needs pdTRUE, not pdFALSE [OK]

Common Mistakes:

• Ignoring auto-reload parameter
• Thinking block time affects reload
• Assuming callback absence causes single run

5. You want to toggle an LED every 2 seconds indefinitely using a FreeRTOS timer. Which timer type and setup should you use?

hard

A. Create a one-shot timer with 2000 ms period and restart it manually each time.

B. Create an auto-reload timer with 2000 ms period to toggle LED automatically.

C. Create a one-shot timer with 1000 ms period and toggle LED twice per cycle.

D. Create an auto-reload timer with 1000 ms period and toggle LED every 2 cycles.

Solution

1. Step 1: Identify requirement for repeated action

   Toggling LED every 2 seconds indefinitely means the action repeats automatically.

2. Step 2: Choose timer type and period

   An auto-reload timer with 2000 ms period will call the toggle function every 2 seconds without manual restart.

3. Final Answer:

   Create an auto-reload timer with 2000 ms period to toggle LED automatically. -> Option B

4. Quick Check:

   Repeated action = auto-reload timer with correct period [OK]

Hint: Repeated tasks use auto-reload timers with correct period [OK]

Common Mistakes:

• Using one-shot timer and forgetting to restart
• Setting wrong timer period
• Confusing toggle frequency with timer period