FreeRTOS Core Concepts (Theory)

1. What is RTOS

RTOS (Real-Time Operating System) is an operating system kernel designed specifically for embedded devices. Its core function is to schedule multiple tasks according to priority and time constraints, ensuring that critical tasks respond within specified time limits.

1.1 Bare Metal vs RTOS

1.2 Why Use RTOS

Imagine a smartwatch — the following pseudocode comparison shows execution differences between bare metal and RTOS in the same scenario:

​x
Bare Metal (Bare Metal) — all operations run sequentially in one loop:
  while(1) {
      readHeartRateSensor();    // takes 50ms
      refreshScreen();          // takes 80ms
      WiFiUploadData();         // takes 200ms, blocks touch during upload
      detectTouchButton();       // takes 5ms
  }

RTOS — each function is a separate task, scheduler assigns CPU by priority:
  Task HeartRate (Prio 4):   read sensor every 100ms
  Task Touch (Prio 3):       woken by touch, refreshes UI immediately
  Task WiFi (Prio 2):        uploads data in idle time
  Task Screen (Prio 1):      lowest priority, refreshes when CPU is free
  → touch always responsive, WiFi never blocks heart-rate reading

In bare metal programs, all code executes serially on a single timeline. RTOS splits the program into multiple independent tasks — blocking operations no longer waste CPU, urgent events no longer wait in queue.

2. Task

2.1 What is a Task

A task is the basic execution unit in FreeRTOS. Each task is a C function that never returns (infinite loop) with its own stack space.

Below is a minimal task skeleton: infinite loop + delay to yield CPU is the fixed pattern for FreeRTOS tasks.

xxxxxxxxxx
// Task function, never returns
void vMyTask(void *pvParameters)
{
    // Every task must be an infinite loop
    while (1) {
        // do work
        // block for 1 second, yield CPU
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

2.2 Task State Machine

FreeRTOS tasks transition between five states. The following state diagram shows all possible transition paths:

xxxxxxxxxx
   Created ──► Ready ──► Running ──► Blocked (waiting for event/delay)
               ▲                     │
                │        ┌────────────┘
                │        ▼
                ├── Suspended
                │
                └── Deleted

2.3 Task Creation

xTaskCreate is the core API for creating tasks. Below is the complete function signature and parameter descriptions:

xxxxxxxxxx
BaseType_t xTaskCreate(
    TaskFunction_t pvTaskCode,     // task function pointer
    // task name (for debugging, max 16 chars)
    const char * const pcName,
    // stack size in WORDS, not bytes
    uint32_t usStackDepth,
    // parameter passed to task
    void *pvParameters,
    // priority (higher = higher priority)
    UBaseType_t uxPriority,
    // task handle (pass NULL if not needed)
    TaskHandle_t *pxCreatedTask
);

// Pinned-to-core version
BaseType_t xTaskCreatePinnedToCore(..., BaseType_t xCoreID);
// Core 1 = APP_CPU (user application)

Stack size unit is WORDS, not bytes. On ESP32-S3, one word = 4 bytes. usStackDepth = 2048 means 2048 × 4 = 8192 bytes = 8KB.

2.4 Task Lifecycle Control

2.5 Task Diagnostics

The following three diagnostic APIs are the most commonly used debugging tools during development — check priority, stack remaining, running core:

xxxxxxxxxx
// Query current task priority
UBaseType_t prio = uxTaskPriorityGet(NULL);

// Query remaining stack space (Stack High Water Mark)
// Stack high water mark (words), smaller = riskier
UBaseType_t remaining = uxTaskGetStackHighWaterMark(NULL);

// Query which core the current task is running on
int core = xPortGetCoreID();

3. Scheduler

3.1 Scheduling Policy

FreeRTOS uses fixed priority preemptive + same priority round-robin time slicing scheduling. The following three rules summarize the core logic of the entire scheduling policy:

xxxxxxxxxx
Rule 1 (Preemption):
  Higher priority task ready → immediately preempts lower priority task

Rule 2 (Time Slice):
  Same priority tasks ready → round-robin switch every tick

Rule 3 (Idle Fallback):
  No task ready → IDLE task runs (priority 0)

3.2 Priority

• Value range: 0 ~ (configMAX_PRIORITIES - 1), default 0 ~ 24

• Larger number = higher priority

• IDLE task has fixed priority 0

• ESP-IDF main task (running app_main) has default priority 1

3.3 Preemption Diagram

The following timeline shows how high priority tasks immediately preempt low priority tasks:

xxxxxxxxxx
  Prio 3 (High):   ............████████████............
  Prio 2 (Mid):    ....████████............████████....
  Prio 1 (Low):    ████................................
                   ↑             ↑              ↑
                Low runs    High preempts  High ends
                                         Low resumes

3.4 Round-Robin Time Slice Diagram

Multiple tasks of the same priority alternate execution by time slice, switching every tick:

xxxxxxxxxx
  Mid1 (Prio 2):   ████............████............
  Mid2 (Prio 2):   ....████............████............
                   ├─ 1 tick ─┤  kernel switches every tick

3.5 When Tasks Yield CPU

A high priority task that doesn't yield CPU will starve all lower priority tasks. High priority tasks must call vTaskDelay or blocking APIs at appropriate locations, otherwise the system essentially degrades to bare metal.

4. Inter-Task Communication

4.1 Five Mechanisms Overview

4.2 Queue — FIFO Data Pipeline

FIFO data pipeline, standard way to pass data between tasks. The following code creates a queue with capacity 10 for unsigned 32-bit integers, and demonstrates basic send/receive usage:

xxxxxxxxxx
// 10 slots, 4 bytes each
QueueHandle_t xQueue = xQueueCreate(10, sizeof(uint32_t));

// send, 100ms timeout
xQueueSend(xQueue, &data, pdMS_TO_TICKS(100));
// receive, block indefinitely
xQueueReceive(xQueue, &data, portMAX_DELAY);

Blocking vs Non-blocking:

4.3 Binary Semaphore — ISR → Task Notification

Most commonly used for ISR → task notification. ISR is hardware interrupt service routine, cannot block, must complete quickly. Semaphore lets ISR only do "notification" and delegates actual processing to task.

xxxxxxxxxx
// Initial value = 0
SemaphoreHandle_t xSem = xSemaphoreCreateBinary();
xSemaphoreGiveFromISR(xSem, &xHigherPriorityTaskWoken);

// inside task:
// block until ISR notification
xSemaphoreTake(xSem, portMAX_DELAY);

Must use FromISR version in ISR: xSemaphoreGiveFromISR / xQueueSendFromISR etc. Calling normal API in ISR will trigger assert.

4.4 Mutex — Mutual Exclusion Lock

Protect shared resources, ensuring only one task enters critical section at a time. Key differences from binary semaphore:

The following code uses mutex to protect increment operation of a global variable:

xxxxxxxxxx
// Create mutex
SemaphoreHandle_t xMutex = xSemaphoreCreateMutex();

// Take lock — block if held
xSemaphoreTake(xMutex, portMAX_DELAY);
g_shared_var++;                           // ← critical section
xSemaphoreGive(xMutex);                   // Give lock back

4.5 Event Group — 24-bit Bitmap

24-bit bitmap, can wait for multiple events all ready or any ready. The following code creates an event group and waits for all event bits to be ready:

 USB Emulated Mass Storage Experiment
Task Creation and Management