liminfo

FreeRTOS Reference

Free reference guide: FreeRTOS Reference

28 results

About FreeRTOS Reference

The FreeRTOS API Reference is a searchable cheat sheet for the most essential FreeRTOS kernel functions used in embedded systems development. It covers six core areas: task management (xTaskCreate, vTaskDelete, vTaskDelay, vTaskDelayUntil), inter-task communication via queues (xQueueCreate, xQueueSend, xQueueReceive), synchronization primitives including binary and counting semaphores, mutex creation with priority inheritance, software timers, and heap memory management using pvPortMalloc and vPortFree.

FreeRTOS is the world's most widely deployed real-time operating system (RTOS), running on hundreds of microcontroller families including ARM Cortex-M, RISC-V, ESP32, STM32, and AVR. Firmware engineers, embedded systems developers, and IoT product teams use FreeRTOS to build deterministic, multitasking applications. This reference is especially valuable when writing interrupt service routines (ISRs), implementing producer-consumer patterns with queues, or diagnosing stack overflow issues with uxTaskGetStackHighWaterMark.

Entries are grouped into six categories — Tasks, Queues, Semaphores, Mutexes, Timers, and Memory — each with the function prototype, a plain-English description, and a ready-to-paste C code example. Real-world scenarios such as periodic tasks with vTaskDelayUntil, ISR-safe signaling with xSemaphoreGiveFromISR, recursive mutex nesting, dotenv-style timer callbacks, and heap profiling with xPortGetFreeHeapSize are all included to speed up day-to-day development.

Key Features

  • Task lifecycle API: xTaskCreate, vTaskDelete, vTaskDelay, vTaskDelayUntil, vTaskPrioritySet
  • Queue API: xQueueCreate, xQueueSend, xQueueReceive, xQueuePeek, uxQueueMessagesWaiting
  • Semaphore API: xSemaphoreCreateBinary, xSemaphoreCreateCounting, xSemaphoreGive, xSemaphoreTake, xSemaphoreGiveFromISR
  • Mutex API: xSemaphoreCreateMutex, xSemaphoreCreateRecursiveMutex, xSemaphoreTakeRecursive with priority inheritance
  • Software timer API: xTimerCreate, xTimerStart, xTimerStop, xTimerChangePeriod
  • Heap memory API: pvPortMalloc, vPortFree, xPortGetFreeHeapSize, uxTaskGetStackHighWaterMark, configTOTAL_HEAP_SIZE
  • ISR-safe variants highlighted separately to prevent incorrect usage in interrupt context
  • Practical C code examples for every entry — ready to paste into your firmware project

Frequently Asked Questions

What is FreeRTOS and who uses this reference?

FreeRTOS is an open-source real-time operating system kernel for microcontrollers. This reference is used by embedded firmware engineers, IoT developers, and electronics hobbyists who need a fast lookup for API function names, parameter order, and usage patterns without opening the full FreeRTOS documentation.

What is the difference between vTaskDelay and vTaskDelayUntil?

vTaskDelay suspends a task for a relative number of ticks from the point the call is made, meaning accumulated processing time shifts the period. vTaskDelayUntil suspends until an absolute tick count is reached, which maintains a precise, jitter-free periodic interval — the preferred choice for control loops.

When should I use a mutex vs a semaphore in FreeRTOS?

Use a mutex (xSemaphoreCreateMutex) when protecting a shared resource because it includes priority inheritance to prevent priority inversion. Use a binary semaphore when signaling between tasks or from an ISR, where ownership and priority inheritance are not needed.

How do I safely give a semaphore from an interrupt service routine?

Use the ISR-safe variant xSemaphoreGiveFromISR instead of xSemaphoreGive. Pass a BaseType_t variable and call portYIELD_FROM_ISR at the end to request a context switch if a higher-priority task was unblocked.

What does configTOTAL_HEAP_SIZE control?

configTOTAL_HEAP_SIZE, defined in FreeRTOSConfig.h, sets the total size of the heap region from which pvPortMalloc allocates memory. If a pvPortMalloc call returns NULL, the heap is exhausted. Use xPortGetFreeHeapSize to monitor available heap at runtime.

How do I detect stack overflow in FreeRTOS?

Call uxTaskGetStackHighWaterMark(NULL) from within a task to get the minimum number of stack words that remained free. A low value (near zero) indicates the task came close to overflowing. Set configCHECK_FOR_STACK_OVERFLOW to 1 or 2 in FreeRTOSConfig.h to enable runtime stack overflow hooks.

What is the difference between pdMS_TO_TICKS and a raw tick value?

pdMS_TO_TICKS converts a millisecond duration to the equivalent number of FreeRTOS ticks using the configured configTICK_RATE_HZ. Always use pdMS_TO_TICKS for portability — if you change the tick rate in FreeRTOSConfig.h, delays specified with pdMS_TO_TICKS automatically scale correctly.

Can I create a FreeRTOS task that runs on a fixed period?

Yes. Wrap the task body in an infinite loop and call vTaskDelayUntil with a fixed period in ticks. Initialize xLastWakeTime with xTaskGetTickCount before the loop. This pattern ensures the task runs at a constant frequency regardless of how long each iteration takes.