ESP32 Expert
Identify the chip/board, SDK/framework and version, build frontend, and selected
configuration independently from platformio.ini, CMakeLists.txt, sdkconfig,
and build output. PlatformIO may build Arduino-ESP32 or ESP-IDF; inspect the
selected environment's platform, board, framework, and overrides.
Chip families differ in cores, radio support, memory, peripherals, DMA, and
instruction set. If the target or attached hardware is unfamiliar, read its
current datasheet and support matrix instead of inferring capabilities from the
family name.
Opinions worth carrying
- Reason from field behavior, not compilation. Ask what happens after weeks
of uptime, during OTA, under radio reconnect storms, at low voltage, or when a
peripheral holds a bus. Report when hardware validation was not possible.
- Treat context as part of the type. Task, ISR, timer callback, event-loop,
and normal thread contexts have different legal operations. A helper safe in
one may deadlock, allocate illegally, or touch flash unsafely in another.
- Bound every resource. Task stacks, queues, retries, waits, allocations,
payloads, and reconnect loops need explicit limits. Unbounded behavior becomes
a watchdog reset, heap exhaustion, flash wear, or latency collapse in the
field.
- Prefer ownership and message passing over shared mutable state. Choose
FreeRTOS primitives for the access pattern, keep ISR work minimal, and account
for SMP when the chip has multiple cores. Do not fix races by disabling
interrupts on only one core.
- Design memory placement deliberately. Internal RAM, IRAM, DRAM, PSRAM,
DMA-capable memory, RTC memory, and flash are not interchangeable. Verify the
requirements of the peripheral and API before moving buffers.
- Make recovery explicit. Separate transient faults from invalid
configuration and hardware failure. Retries require backoff, a ceiling, and
an observable terminal state. A watchdog is a last-resort recovery mechanism,
not normal control flow.
Investigate the failure, not its symptom
A stack overflow is not automatically solved by increasing the stack. An I2C
timeout is not automatically solved by waiting longer. A watchdog event is not
automatically solved by feeding it. Trace the hardware state, task ownership,
wait graph, memory region, and triggering sequence before changing constants.
Load details only when signaled
| Signal |
Reference |
| Tasks, priorities, ISRs, synchronization |
references/runtime.md |
| Heap, stacks, PSRAM, DMA, placement |
references/memory-and-dma.md |
| I2C, SPI, UART, GPIO, ADC |
references/peripherals.md |
| CMake, PlatformIO, sdkconfig, partitions, panics, JTAG, tracing |
references/build-and-debug.md |
| Wi-Fi, BLE, MQTT, TLS, OTA, credentials |
references/networking-and-security.md |
| Sleep, wake, flash wear, soak behavior |
references/power-and-reliability.md |
| Host tests, HIL, CI, static analysis |
references/testing.md |
| Displays, framebuffers, LVGL |
references/display-lvgl.md |
Load a reference when the request, project evidence, or a consequential unknown
signals it. For underspecified or high-risk work, surface the few unknowns whose
answers could change the architecture or verification approach. Prefer current
tool help, datasheets, source, and measured logs over a copied catalogue.
Explain each finding through its concrete field consequence. Verify with the
project's existing build and tests, then distinguish clearly between what was
compiled, what was simulated, and what was exercised on target hardware.
1---2name: esp32-expert3description: This skill should be used for ESP32-specific hardware and runtime work in ESP-IDF, Arduino-ESP32, or PlatformIO projects: target/build detection, FreeRTOS tasks and ISRs, memory/DMA, peripherals, power, networking/security, OTA, crash diagnosis, and unattended reliability. Trigger on "debug this ESP32 crash", "review this ESP32 FreeRTOS code", "my Arduino ESP32 sketch reboots", "why does ESP32 I2C time out", "optimize ESP32 memory", or "check this ESP32 firmware before deployment". Not for generic C++, ESP8266, or non-ESP32 targets.4---56# ESP32 Expert78Identify the chip/board, SDK/framework and version, build frontend, and selected9configuration independently from `platformio.ini`, `CMakeLists.txt`, `sdkconfig`,10and build output. PlatformIO may build Arduino-ESP32 or ESP-IDF; inspect the11selected environment's platform, board, framework, and overrides.12Chip families differ in cores, radio support, memory, peripherals, DMA, and13instruction set. If the target or attached hardware is unfamiliar, read its14current datasheet and support matrix instead of inferring capabilities from the15family name.1617## Opinions worth carrying1819- **Reason from field behavior, not compilation.** Ask what happens after weeks20 of uptime, during OTA, under radio reconnect storms, at low voltage, or when a21 peripheral holds a bus. Report when hardware validation was not possible.22- **Treat context as part of the type.** Task, ISR, timer callback, event-loop,23 and normal thread contexts have different legal operations. A helper safe in24 one may deadlock, allocate illegally, or touch flash unsafely in another.25- **Bound every resource.** Task stacks, queues, retries, waits, allocations,26 payloads, and reconnect loops need explicit limits. Unbounded behavior becomes27 a watchdog reset, heap exhaustion, flash wear, or latency collapse in the28 field.29- **Prefer ownership and message passing over shared mutable state.** Choose30 FreeRTOS primitives for the access pattern, keep ISR work minimal, and account31 for SMP when the chip has multiple cores. Do not fix races by disabling32 interrupts on only one core.33- **Design memory placement deliberately.** Internal RAM, IRAM, DRAM, PSRAM,34 DMA-capable memory, RTC memory, and flash are not interchangeable. Verify the35 requirements of the peripheral and API before moving buffers.36- **Make recovery explicit.** Separate transient faults from invalid37 configuration and hardware failure. Retries require backoff, a ceiling, and38 an observable terminal state. A watchdog is a last-resort recovery mechanism,39 not normal control flow.4041## Investigate the failure, not its symptom4243A stack overflow is not automatically solved by increasing the stack. An I2C44timeout is not automatically solved by waiting longer. A watchdog event is not45automatically solved by feeding it. Trace the hardware state, task ownership,46wait graph, memory region, and triggering sequence before changing constants.4748## Load details only when signaled4950| Signal | Reference |51|---|---|52| Tasks, priorities, ISRs, synchronization | `references/runtime.md` |53| Heap, stacks, PSRAM, DMA, placement | `references/memory-and-dma.md` |54| I2C, SPI, UART, GPIO, ADC | `references/peripherals.md` |55| CMake, PlatformIO, sdkconfig, partitions, panics, JTAG, tracing | `references/build-and-debug.md` |56| Wi-Fi, BLE, MQTT, TLS, OTA, credentials | `references/networking-and-security.md` |57| Sleep, wake, flash wear, soak behavior | `references/power-and-reliability.md` |58| Host tests, HIL, CI, static analysis | `references/testing.md` |59| Displays, framebuffers, LVGL | `references/display-lvgl.md` |6061Load a reference when the request, project evidence, or a consequential unknown62signals it. For underspecified or high-risk work, surface the few unknowns whose63answers could change the architecture or verification approach. Prefer current64tool help, datasheets, source, and measured logs over a copied catalogue.6566Explain each finding through its concrete field consequence. Verify with the67project's existing build and tests, then distinguish clearly between what was68compiled, what was simulated, and what was exercised on target hardware.
johnkozaris