--- name: esp32-arduino-embedded-c description: Guidance for production-grade ESP32 Arduino and Embedded C/C++ development. Use when building firmware for ESP32, ESP32-S3, or ESP32-C3 microcontrollers, optimizing FreeRTOS tasks, managing SRAM/PSRAM, writing ISR-safe code, or handling dual-core concurrency and hardware peripherals. --- # ESP32 Arduino & Embedded C/C++ Production Guidelines This skill provides architecture patterns, memory management guidelines, hardware interrupt safety rules, and production code patterns for high-reliability ESP32 embedded applications using Arduino / ESP-IDF C++. --- ## 1. Core Architecture & Multi-Core Strategy ### 1.1 Dual-Core Pinning & Priority Allocation ESP32 (dual-core Xtensa LX6/LX7) splits responsibilities across **Core 0 (PRO_CPU)** and **Core 1 (APP_CPU)**: - **Core 0**: Reserved primarily for Wi-Fi, Bluetooth, TCP/IP stack, and system tasks managed by ESP-IDF. - **Core 1**: Dedicated to application logic, sensor polling, motor control, display UI, and real-time DSP. ``` Core 0 (PRO_CPU) Core 1 (APP_CPU) +-----------------------+ +-----------------------+ | WiFi / Bluetooth Task | | App Logic / Sensor | | TCP/IP Stack | | Data Processing Task | | System Watchdog WDT | | Real-time Control Task| +-----------------------+ +-----------------------+ ^ ^ | FreeRTOS Queue / EventGroup | +------------------------------------+ ``` - **Task Priorities**: FreeRTOS priorities range from `0` (lowest, idle) to `configMAX_PRIORITIES - 1` (highest, typically 24). - Real-time hard timing tasks: Priority 18 - 22 - I/O & Sensor Polling: Priority 10 - 15 - Network & Telemetry tasks: Priority 5 - 8 - Background/Idle tasks: Priority 1 - 3 ### 1.2 Task Stack & Watchdog Timers (WDT) - **Task Watchdog Timer (TWDT)**: Monitors tasks for starvation or deadlocks. Any task pinned to a core executing a loop must either block (`vTaskDelay()`, `xQueueReceive()`) or trigger `esp_task_wdt_reset()`. - Never use blocking `delay()` from Arduino in FreeRTOS tasks — use `vTaskDelay(pdMS_TO_TICKS(ms))` or `vTaskDelayUntil()`. --- ## 2. Real-Time Memory Management ### 2.1 Dynamic Allocation Hazards In embedded real-time systems, heap allocation (`malloc`, `new`, `std::string`, `std::vector`, `Arduino String`) causes: 1. **Heap Fragmentation**: Repeated allocations of varying sizes leave non-contiguous small gaps, leading to runtime `Out of Memory (OOM)` crashes after days/weeks of continuous operation. 2. **Nondeterministic Execution**: Heap allocation time depends on current heap topology, violating hard real-time guarantees. ### 2.2 Memory Allocation Best Practices - **Static Task Creation**: Use `xTaskCreateStatic()` instead of `xTaskCreate()` to allocate TCB (Task Control Block) and stack at compile time. - **Static Queues & Semaphores**: Use `xQueueCreateStatic()` and `xSemaphoreCreateBinaryStatic()`. - **Pre-allocated Buffers**: Allocate fixed-size array buffers in BSS/Data section or during initialization. - **PSRAM Allocation (ESP32-WROVER / S3)**: For large buffers (e.g., audio samples, camera frames, network ring buffers), explicitly allocate from External SPI RAM: ```cpp uint8_t *frame_buffer = (uint8_t *)heap_caps_malloc(BUFFER_SIZE, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); ``` ### 2.3 Stack Monitoring & High Water Mark Continuously monitor task stack consumption during testing: ```cpp UBaseType_t highWaterMark = uxTaskGetStackHighWaterMark(NULL); ESP_LOGI("STACK", "Task remaining stack: %u bytes", highWaterMark * sizeof(StackType_t)); ``` --- ## 3. Hardware Interrupt Safety (ISR) ### 3.1 IRAM Placement Interrupt Service Routines (ISRs) and functions invoked inside ISRs **must** reside in Internal RAM (IRAM) to prevent crash/exception if flash cache is disabled during flash write/read operations. - Annotate ISR functions with `IRAM_ATTR`. ### 3.2 ISR Guardrails - **Keep ISRs Ultra-Short**: Only clear interrupt flags, sample raw hardware counter/registers, and post notification to a FreeRTOS task. - **No Blocking Calls**: Never call `delay()`, `vTaskDelay()`, `printf()`, `ESP_LOGI()`, or `xQueueSend()` from inside an ISR. - **FromISR API**: Use only FreeRTOS functions suffixing with `FromISR` (e.g., `xQueueSendFromISR()`, `vTaskNotifyGiveFromISR()`). - **HigherPriorityTaskWoken**: Always pass `BaseType_t xHigherPriorityTaskWoken` and yield with `portYIELD_FROM_ISR(xHigherPriorityTaskWoken)`. ### 3.3 Spinlocks & Critical Sections For dual-core shared variables modified inside ISR: ```cpp portMUX_TYPE mySpinlock = portMUX_INITIALIZER_UNLOCKED; void IRAM_ATTR gpio_isr_handler(void* arg) { portENTER_CRITICAL_ISR(&mySpinlock); // Read/write shared hardware registers or variables safely portEXIT_CRITICAL_ISR(&mySpinlock); } ``` --- ## 4. Anti-Patterns & Critical Pitfalls | Anti-Pattern | Severity | Consequence | Correct Pattern | |---|---|---|---| | Using `String` concats in loops | Critical | Heap fragmentation, silent OOM crashes | Use `char` arrays, `snprintf()`, or static buffers | | Long execution inside ISR | Critical | WDT trigger, interrupt starvation, system crash | Offload processing to high-priority FreeRTOS task via Task Notification | | Shared variable modification without lock | High | Data corruption, subtle race conditions across dual cores | Use `std::atomic`, `portMUX_TYPE`, or FreeRTOS Mutex | | `delay(100)` inside FreeRTOS tasks | Medium | Core starvation, WDT triggering, unhandled yields | Use `vTaskDelay(pdMS_TO_TICKS(100))` | | Unchecked pointer return from `malloc`/`heap_caps_malloc` | High | Null pointer dereference panic | Always check `NULL` return before access | --- ## 5. Production Code Example Below is a complete, production-grade ESP32 FreeRTOS C++ firmware template featuring static queues, ISR-to-Task notifications, hardware watchdog protection, and safe spinlock memory synchronization. ```cpp #include #include "freertos/FreeRTOS.h" #include "freertos/task.h" #include "freertos/queue.h" #include "esp_task_wdt.h" #include "esp_log.h" #include static const char *TAG = "MAIN_APP"; // Pin Definitions constexpr gpio_num_t SENSOR_PIN = GPIO_NUM_4; // Queue Configuration constexpr size_t QUEUE_LENGTH = 16; constexpr size_t ITEM_SIZE = sizeof(uint32_t); // Static Queue Storage static QueueHandle_t xSensorQueue = nullptr; static StaticQueue_t xStaticQueueStruct; static uint8_t ucQueueStorageArea[QUEUE_LENGTH * ITEM_SIZE]; // Static Task Storage for Processing Task constexpr configSTACK_DEPTH_TYPE PROCESS_STACK_SIZE = 4096; static TaskHandle_t xProcessingTaskHandle = nullptr; static StaticTask_t xProcessTaskBuffer; static StackType_t xProcessStack[PROCESS_STACK_SIZE]; // Spinlock for ISR Shared State static portMUX_TYPE g_spinlock = portMUX_INITIALIZER_UNLOCKED; static volatile uint32_t g_isr_event_count = 0; // Thread-safe atomic counter for telemetry static std::atomic g_processed_events(0); // --- ISR Handler --- void IRAM_ATTR sensor_gpio_isr_handler(void *arg) { BaseType_t xHigherPriorityTaskWoken = pdFALSE; uint32_t timestamp = xTaskGetTickCountFromISR(); portENTER_CRITICAL_ISR(&g_spinlock); g_isr_event_count++; portEXIT_CRITICAL_ISR(&g_spinlock); // Send timestamp to static queue without blocking xQueueSendFromISR(xSensorQueue, ×tamp, &xHigherPriorityTaskWoken); // Context switch if higher priority task was woken portYIELD_FROM_ISR(xHigherPriorityTaskWoken); } // --- Data Processing Task (Core 1) --- void ProcessingTask(void *pvParameters) { uint32_t received_timestamp = 0; ESP_LOGI(TAG, "Processing Task started on Core %d", xPortGetCoreID()); for (;;) { // Wait indefinitely for queue items if (xQueueReceive(xSensorQueue, &received_timestamp, portMAX_DELAY) == pdTRUE) { // Business logic processing g_processed_events.fetch_add(1, std::memory_order_relaxed); ESP_LOGD(TAG, "Processed event registered at tick: %u", received_timestamp); } // Periodically log memory health if (g_processed_events.load() % 100 == 0) { UBaseType_t hwm = uxTaskGetStackHighWaterMark(NULL); ESP_LOGI(TAG, "Processed: %u | Task High Water Mark: %u bytes", g_processed_events.load(), hwm * sizeof(StackType_t)); } } } void setup() { Serial.begin(115200); while (!Serial && millis() < 2000) {} ESP_LOGI(TAG, "Initializing Production ESP32 Firmware..."); // 1. Initialize Static Queue xSensorQueue = xQueueCreateStatic(QUEUE_LENGTH, ITEM_SIZE, ucQueueStorageArea, &xStaticQueueStruct); configASSERT(xSensorQueue != nullptr); // 2. Configure GPIO Pin & ISR Interrupt gpio_config_t io_conf = {}; io_conf.intr_type = GPIO_INTR_NEGEDGE; io_conf.mode = GPIO_MODE_INPUT; io_conf.pin_bit_mask = (1ULL << SENSOR_PIN); io_conf.pull_down_en = GPIO_PULLDOWN_DISABLE; io_conf.pull_up_en = GPIO_PULLUP_ENABLE; gpio_config(&io_conf); // Install GPIO ISR Service and Attach Handler gpio_install_isr_service(ESP_INTR_FLAG_IRAM); gpio_isr_handler_add(SENSOR_PIN, sensor_gpio_isr_handler, nullptr); // 3. Create Static Worker Task pinned to Core 1 xProcessingTaskHandle = xTaskCreateStaticPinnedToCore( ProcessingTask, "DataProcessor", PROCESS_STACK_SIZE, nullptr, 12, // Priority xProcessStack, &xProcessTaskBuffer, 1 // Core 1 (APP_CPU) ); configASSERT(xProcessingTaskHandle != nullptr); ESP_LOGI(TAG, "System initialization complete."); } void loop() { // Main loop runs on Core 1 (Arduino default task priority 1) // Yield execution to allow lower-priority background routines vTaskDelay(pdMS_TO_TICKS(1000)); } ```