laurigates ESP32 Firmware Debugging Guide
When to Use This Skill
Apply this skill when the user:
- Encounters compilation errors in ESP-IDF projects
- Sees runtime panics or "Guru Meditation Error" messages
- Has memory-related crashes or stack overflows
- Experiences I2C/SPI/UART communication failures
- Needs help interpreting serial monitor output
$ARGUMENTS may contain error messages or context about the issue.
Debugging Process
Ask for Context First
If the error isn't clear from $ARGUMENTS, ask the user to provide:
- Full error message or panic output
- Which project they're building
- Recent code changes
1. Compilation Error Analysis
Run a fresh build to capture the error:
just <project>::build 2>&1 | tail -100
Missing Includes
fatal error: driver/gpio.h: No such file or directory
Fix: Add the component to REQUIRES in main/CMakeLists.txt:
idf_component_register(
SRCS "main.c"
REQUIRES driver
)
Undefined References
undefined reference to 'some_function'
Fix: Ensure the component containing the function is in REQUIRES or PRIV_REQUIRES.
Type Errors Look for mismatched types between function declarations and implementations.
2. Runtime Panic Analysis
Guru Meditation Error Patterns
| Error | Cause | Fix |
|---|---|---|
StoreProhibited |
Writing to invalid memory | Check pointer initialization |
LoadProhibited |
Reading from invalid memory | Check null pointers |
InstrFetchProhibited |
Corrupted function pointer | Check callback assignments |
IntegerDivideByZero |
Division by zero | Add zero checks |
Double exception, backtrace CORRUPTED, A0 = a recognisable constant (e.g. 0x10000000) |
Stack buffer overflow upward into caller frames — a VLA or local array indexed past its end; the canary only watches the low end | Read the code between the last log line and the panic; look up the top byte of A0 in the driver just called. See .claude/rules/gated-init-paths.md |
Stack Overflow
Guru Meditation Error: Core 0 panic'ed (Stack overflow)
Fix: Increase stack size in task creation:
xTaskCreatePinnedToCore(task_fn, "name", 4096, NULL, 5, NULL, 0);
// ^^^^ increase this
Stack Smashing
Stack smashing detected
Fix: Local buffer overflow — check array bounds and string operations.
That message needs CONFIG_COMPILER_STACK_CHECK_MODE_* enabled. With it off (the robocar-unified default) the same overflow reports as a double exception with a corrupted backtrace instead — see the table above. Pin the fix with a host test that compiles the file unmodified under -fsanitize=address (packages/robocar/unified/test/test_pca9685_multi.c is the template).
3. Memory Debugging
Check Heap Usage
ESP_LOGI(TAG, "Free heap: %lu", esp_get_free_heap_size());
ESP_LOGI(TAG, "Min free heap: %lu", esp_get_minimum_free_heap_size());
Common Memory Issues
- Memory leak: Missing
free()aftermalloc() - Double free: Freeing same memory twice
- Use after free: Accessing freed memory
4. Communication Debugging
I2C Issues
E (1234) i2c: i2c_master_cmd_begin(xxx): I2C_NUM error
Checklist:
- Verify I2C address (7-bit vs 8-bit format)
- Check SDA/SCL GPIO pins
- Ensure pull-up resistors are present (4.7K typical)
- Verify clock frequency compatibility
Serial/UART Issues
- Baud rate mismatch
- TX/RX swapped
- Missing ground connection
Dual-Controller Sync (I2C)
- Check both controllers are running
- Verify I2C addresses match
- Check GPIO pin configuration
5. Build Commands for Debugging
# Clean build to eliminate stale objects
just <project>::clean && just <project>::build
# Start serial monitor
just <project>::monitor PORT=/dev/cu.usbserial-0001
6. Useful ESP-IDF Config Options
Enable in sdkconfig.defaults or via menuconfig:
CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT— Print panic info before rebootCONFIG_FREERTOS_WATCHPOINT_END_OF_STACK— Detect stack overflow earlierCONFIG_HEAP_POISONING_COMPREHENSIVE— Detect heap corruption
Common Fixes
| Symptom | Fix |
|---|---|
| Stack overflow | Increase task stack size in xTaskCreate |
| Memory leak | Check for missing free() calls |
| I2C timeout | Verify connections, pull-ups, addresses |
| Crash on startup | Increase CONFIG_ESP_MAIN_TASK_STACK_SIZE to 8192+ |