protagonist-fy/low-level-dev-skills / skills/embedded/freertos
freertos
VerifiedFreeRTOS skill for embedded RTOS development. Use when creating tasks, managing priorities, using queues and mutexes, detecting stack overflows, configuring FreeRTOS via FreeRTOSConfig.h, or debugging FreeRTOS applications with OpenOCD and GDB. Activates on queries about FreeRTOS tasks, queues, semaphores, mutexes, configASSERT, stack overflow, vTaskDelay, or FreeRTOS-aware debugging.
FreeRTOS
Purpose
Guide agents through FreeRTOS application development: task creation and priorities, inter-task communication with queues and semaphores, stack overflow detection, configASSERT, and FreeRTOS-aware debugging with GDB and OpenOCD.
Triggers
- "How do I create a FreeRTOS task?"
- "How do I pass data between FreeRTOS tasks?"
- "My FreeRTOS task is crashing — how do I detect stack overflow?"
- "How do I use FreeRTOS mutexes?"
- "How do I debug FreeRTOS tasks with GDB?"
- "How do I configure FreeRTOSConfig.h?"
Workflow
1. Task creation and priorities
#include "FreeRTOS.h"
#include "task.h"
// Task function signature
void vMyTask(void *pvParameters) {
const char *name = (const char *)pvParameters;
for (;;) {
// Task body — must never return
printf("Task %s running\n", name);
vTaskDelay(pdMS_TO_TICKS(500)); // yield for 500ms
}
}
int main(void) {
// xTaskCreate(function, name, stack_depth_words, param, priority, handle)
TaskHandle_t xHandle = NULL;
xTaskCreate(vMyTask, "MyTask",
configMINIMAL_STACK_SIZE + 128, // words, not bytes!
(void *)"sensor",
tskIDLE_PRIORITY + 2, // higher = more urgent
&xHandle);
vTaskStartScheduler(); // never returns if heap is sufficient
for (;;); // should never reach here
}
Priority guidelines:
tskIDLE_PRIORITY(0) — idle task, never block here- ISR-deferred tasks — highest priority to service interrupts quickly
- Avoid priorities above
configMAX_PRIORITIES - 1
2. Queues — inter-task data passing
#include "queue.h"
typedef struct { uint32_t sensor_id; float value; } SensorReading_t;
QueueHandle_t xSensorQueue;
void vProducerTask(void *pvParam) {
SensorReading_t reading;
for (;;) {
reading.sensor_id = 1;
reading.value = read_adc();
// Send; block max 10ms if queue full
xQueueSend(xSensorQueue, &reading, pdMS_TO_TICKS(10));
vTaskDelay(pdMS_TO_TICKS(100));
}
}
void vConsumerTask(void *pvParam) {
SensorReading_t reading;
for (;;) {
// Block forever until item available
if (xQueueReceive(xSensorQueue, &reading, portMAX_DELAY) == pdTRUE) {
process(reading.value);
}
}
}
// Create before starting scheduler
xSensorQueue = xQueueCreate(10, sizeof(SensorReading_t));
From ISR: use xQueueSendFromISR() and pass &xHigherPriorityTaskWoken.
3. Semaphores and mutexes
#include "semphr.h"
// Binary semaphore — signaling (ISR→task)
SemaphoreHandle_t xSem = xSemaphoreCreateBinary();
void UART_ISR(void) {
BaseType_t xWoken = pdFALSE;
xSemaphoreGiveFromISR(xSem, &xWoken);
portYIELD_FROM_ISR(xWoken);
}
void vUartTask(void *p) {
for (;;) {
xSemaphoreTake(xSem, portMAX_DELAY);
// process received data
}
}
// Mutex — mutual exclusion (NOT from ISR)
SemaphoreHandle_t xMutex = xSemaphoreCreateMutex();
void vCriticalSection(void) {
if (xSemaphoreTake(xMutex, pdMS_TO_TICKS(100)) == pdTRUE) {
// protected access
shared_resource++;
xSemaphoreGive(xMutex);
}
}
// Recursive mutex (same task can take multiple times)
SemaphoreHandle_t xRecursive = xSemaphoreCreateRecursiveMutex();
xSemaphoreTakeRecursive(xRecursive, portMAX_DELAY);
xSemaphoreGiveRecursive(xRecursive);
Use mutex (not binary semaphore) for shared resources to get priority inheritance.
4. Stack overflow detection
// FreeRTOSConfig.h
#define configCHECK_FOR_STACK_OVERFLOW 2 // Method 2 (pattern + watermark)
#define configUSE_MALLOC_FAILED_HOOK 1
// Implement the hook (called when overflow detected)
void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) {
// Log the offending task name, then halt
configASSERT(0); // triggers assertion failure
}
void vApplicationMallocFailedHook(void) {
configASSERT(0);
}
Check watermarks at runtime:
// Returns minimum ever free stack words
UBaseType_t uxHighWaterMark = uxTaskGetStackHighWaterMark(xHandle);
printf("Stack headroom: %lu words\n", uxHighWaterMark);
// Rule of thumb: keep headroom > 20 words
5. Essential FreeRTOSConfig.h settings
// FreeRTOSConfig.h — adapt to your MCU
#define configCPU_CLOCK_HZ (SystemCoreClock)
#define configTICK_RATE_HZ 1000 // 1ms tick
#define configMAX_PRIORITIES 8
#define configMINIMAL_STACK_SIZE 128 // words
#define configTOTAL_HEAP_SIZE (16 * 1024) // bytes
#define configMAX_TASK_NAME_LEN 16
// Debug / safety
#define configUSE_TRACE_FACILITY 1
#define configUSE_STATS_FORMATTING_FUNCTIONS 1
#define configCHECK_FOR_STACK_OVERFLOW 2
#define configUSE_MALLOC_FAILED_HOOK 1
#define configASSERT(x) if((x)==0) { taskDISABLE_INTERRUPTS(); for(;;); }
// Features
#define configUSE_MUTEXES 1
#define configUSE_RECURSIVE_MUTEXES 1
#define configUSE_COUNTING_SEMAPHORES 1
#define configUSE_TIMERS 1
#define configTIMER_TASK_STACK_DEPTH (configMINIMAL_STACK_SIZE * 2)
6. GDB debugging with OpenOCD
# Connect GDB with FreeRTOS thread awareness
# OpenOCD provides FreeRTOS-aware RTOS plugin
# openocd.cfg addition
# source [find rtos/FreeRTOS.cfg] # auto-loads with most targets
# GDB session
(gdb) info threads # lists all FreeRTOS tasks
(gdb) thread 3 # switch to task 3
(gdb) bt # backtrace of that task's stack
(gdb) frame 2 # inspect specific frame
# Print task list from GDB (if trace facility enabled)
(gdb) call vTaskList(buf)
(gdb) printf "%s\n", buf
For OpenOCD setup details, see skills/embedded/openocd-jtag.
For FreeRTOSConfig.h reference, see references/freertos-config.md.
Related skills
- Use
skills/embedded/openocd-jtagfor GDB/OpenOCD remote debugging setup - Use
skills/embedded/linker-scriptsfor placing FreeRTOS heap in specific RAM regions - Use
skills/debuggers/gdbfor general GDB session management - Use
skills/embedded/zephyrfor an alternative RTOS with built-in device management
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |