freertos

FreeRTOS

FreeRTOS is the most widely deployed RTOS in commercial embedded. This skill covers using it correctly — task boundaries, synchronization primitives, memory discipline, and common failure modes.

When to Use

• Designing task architecture for a new embedded system
• Reviewing FreeRTOS code for correctness (deadlock, priority inversion, stack overflow)
• Adding FreeRTOS to a bare-metal project
• Any task involving queues, semaphores, mutexes, or event groups
• Debugging a system that locks up, has priority inversion, or experiences stack overflow

When NOT to Use

• ESP32-specific IDF patterns (xTaskCreatePinnedToCore, IRAM_ATTR, portMUX) — see esp32-idf
• Bare metal without RTOS — see c-embedded for bare-metal patterns
• Linux POSIX threads — different API despite similar concepts

Core Principle

Every FreeRTOS object consumes RAM. Queues, tasks, semaphores — all are statically allocated or taken from the heap at creation time. In a system with 64KB SRAM, a misconfigured task stack or oversized queue is the difference between a working device and a reset loop.

Task Design

Anatomy of a Well-Designed Task

#include "FreeRTOS.h"
#include "task.h"

// Task parameters — prefer a config struct over void* casting
typedef struct {
    uint8_t  sensor_addr;
    uint16_t sample_rate_hz;
    QueueHandle_t output_queue;
} sensor_task_cfg_t;

static void sensor_task(void *pvParameters) {
    const sensor_task_cfg_t *cfg = (sensor_task_cfg_t *)pvParameters;
    TickType_t last_wake = xTaskGetTickCount();
    const TickType_t period = pdMS_TO_TICKS(1000 / cfg->sample_rate_hz);

    while (1) {
        // Fixed-rate: vTaskDelayUntil accounts for task run time
        // Use vTaskDelay only when exact period doesn't matter
        vTaskDelayUntil(&last_wake, period);

        int16_t reading;
        if (sensor_read(cfg->sensor_addr, &reading) == HAL_OK) {
            measurement_t m = { .value = reading, .tick = xTaskGetTickCount() };
            // Non-blocking send — log if full, don't block the sampling task
            if (xQueueSend(cfg->output_queue, &m, 0) != pdTRUE) {
                // Queue full — consumer is too slow
            }
        }
    }
    // Unreachable — tasks must not return. If exit needed: vTaskDelete(NULL)
}

// Task creation — check return value
TaskHandle_t sensor_handle = NULL;
BaseType_t result = xTaskCreate(
    sensor_task,
    "sensor",                   // name visible in debugger / task list
    256,                        // stack depth in WORDS (not bytes) on most ports
                                // ESP32: bytes. Check portSTACK_TYPE size.
    (void *)&sensor_cfg,        // parameters
    5,                          // priority (higher number = higher priority)
    &sensor_handle
);
configASSERT(result == pdPASS); // fail loudly if creation fails