// Firmware crash analysis, stack trace decoder, and register dump interpreter for ESP32/ARM/AVR platforms. Use when debugging device crashes, panics, guru meditation errors, hard faults, or analyzing core dumps.
Fetch CodeRabbit review comments on the current PR, classify each finding, apply fixes for valid issues, and reply to each thread. Use before attempting gh pr merge when CodeRabbit has posted a review. Blocks merge on unresolved threads. Routes security-critical findings to a human.
Generate a structured multi-layer test plan for FastLED changes targeting ESP32. Covers host unit tests, WASM compile checks, platform compile checks, and hardware validation. Use after defining an implementation contract, before writing any code.
Generate a structured implementation contract before making any code changes to FastLED. Defines scope, affected files, API changes, platform impact, risk assessment, and test plan. Use before implementing any feature, bug fix, driver addition, or refactoring.
Review staged and unstaged code changes for FastLED coding standards violations, span usage mandates, and example quality. Use after making code changes to ensure compliance.
Review and implement hardware driver code — DMA safety, interrupt correctness, timing constraints, peripheral register usage, channel drivers, and peripheral mock implementations. Use when writing, modifying, or reviewing LED drivers, SPI/I2S/RMT/UART/PARLIO/LCD_CAM peripherals, GPIO configuration, or peripheral mock code.
Scan all CI builds and tests, find failures, fetch error logs, and fix the code. Prioritizes unit tests, example tests, then uno, attiny85, esp32s3, esp32c6, teensy41. Use when CI is red and you need to diagnose and repair build/test failures.
| name | embedded-debug |
| description | Firmware crash analysis, stack trace decoder, and register dump interpreter for ESP32/ARM/AVR platforms. Use when debugging device crashes, panics, guru meditation errors, hard faults, or analyzing core dumps. |
| argument-hint | <crash output or description of the issue> |
| context | fork |
| agent | embedded-debug-agent |
Analyze firmware crash output, decode stack traces, and diagnose embedded system failures.
$ARGUMENTS
| Platform | Crash Types |
|---|---|
| ESP32 (all variants) | Guru Meditation, LoadProhibited, StoreProhibited, InstrFetchProhibited, watchdog reset, brownout, cache errors |
| ARM Cortex-M (STM32, Teensy, nRF) | HardFault, MemManage, BusFault, UsageFault, watchdog reset |
| AVR (Arduino Uno/Mega) | Stack overflow (silent corruption), watchdog reset, undefined opcode |
| RISC-V (ESP32-C3/C6/H2) | Illegal instruction, load/store fault, breakpoint |
/embedded-debug
Guru Meditation Error: Core 0 panic'ed (LoadProhibited). Exception was unhandled.
Core 0 register dump:
PC : 0x400d1234 PS : 0x00060030 A0 : 0x800d5678
...
/embedded-debug Device reboots every 30 seconds, serial shows "rst:0x3 (SW_RESET)"
/embedded-debug Analyze the core dump from the last crash
| Exception | EXCVADDR hint | Likely Root Cause |
|---|---|---|
LoadProhibited | ~0x00000000 | NULL pointer dereference (uninitialized LED strip?) |
LoadProhibited | Other | Read from freed or out-of-bounds memory |
StoreProhibited | Any | Write to read-only or invalid memory address |
InstrFetchProhibited | Any | Jump to invalid/NULL function pointer or corrupt vtable |
IllegalInstruction | Any | Stack overflow corrupting code, or corrupt heap |
IntegerDivideByZero | N/A | Division by zero in LED index math |
Unaligned | Any | Misaligned memory access (DMA buffer not 4-byte aligned) |
Cache disabled but cache memory range accessed | Any | ISR accessing flash — add IRAM_ATTR to ISR function |
| Register | Meaning |
|---|---|
PC | Program Counter — where the crash happened |
EXCVADDR | Address that caused the fault (NULL pointer, invalid write target) |
A1 | Stack pointer — compare to task stack base to detect overflow |
A0 | Return address — calling function |
Symptoms: Cache disabled but cache memory range accessed or crash inside FreeRTOS API
Cause: FastLED ISR handler calling blocking or flash-accessing code.
Diagnosis: Look for crash inside xSemaphoreTake, vTaskDelay, printf, or any non-ISR-safe function.
Fix:
IRAM_ATTR to all ISR-related functionsxSemaphoreGiveFromISR, xQueueSendFromISR)Symptoms: rst:0x7 (TG0WDT_SYS_RESET) or rst:0x8 (TG1WDT_SYS_RESET)
Cause: Task or interrupt handler not yielding — common with:
show() blocking on DMA in a task with watchdog enabledvTaskDelay(0) or taskYIELD()Fix:
esp_task_wdt_reset() in long loops, orshow() to a dedicated task exempt from watchdog, orSymptoms: StackOverflow + task name, or IllegalInstruction with A1 near stack limit
Diagnosis: Check task stack size in xTaskCreate or xTaskCreatePinnedToCore. FastLED show() with large LED arrays can use significant stack.
Fix: Increase task stack size (minimum 4096 bytes for tasks calling FastLED show with encoding)
Symptoms: IllegalInstruction at random address, corrupted register values, intermittent crashes
Diagnosis: Enable diagnostics:
// In sdkconfig or menuconfig:
CONFIG_HEAP_POISONING_COMPREHENSIVE=y
CONFIG_HEAP_TASK_TRACKING=y
CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK=y
Common FastLED Cause: Writing past end of CRGB array (index out of bounds in user sketch)
# ESP32 (Xtensa)
xtensa-esp32-elf-addr2line -pfiaC -e build/firmware.elf 0xADDR1 0xADDR2
# ESP32-S3
xtensa-esp32s3-elf-addr2line -pfiaC -e build/firmware.elf 0xADDR1
# ESP32-C3/C6 (RISC-V)
riscv32-esp-elf-addr2line -pfiaC -e build/firmware.elf 0xADDR1
# Live decode via idf.py
idf.py -p /dev/ttyUSB0 monitor