esp32-arduino-embedded-c

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.