esp32-debugging

# 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: 1. Full error message or panic output 2. Which project they're building 3. Recent code changes ### 1. Compilation Error Analysis **Run a fresh build to capture the error:** ```bash 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`: ```cmake 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: ```c 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** ```c 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()` after `malloc()` - 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 ```bash # 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 reboot - `CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` — Detect stack overflow earlier - `CONFIG_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+ |