Back to Details

esp32-debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ESP32 Firmware Debugging Guide

ESP32固件调试指南

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
当用户遇到以下情况时，可使用此技能：
  • 遭遇ESP-IDF项目中的编译错误
  • 看到运行时崩溃或"Guru Meditation Error"消息
  • 出现内存相关崩溃或栈溢出
  • 遇到I2C/SPI/UART通信故障
  • 需要帮助解读串口监视器输出

Debugging Techniques

调试技巧

1. Compilation Error Analysis

1. 编译错误分析

Missing Includes
fatal error: driver/gpio.h: No such file or directory
Fix: Check CMakeLists.txt and add the component to REQUIRES:
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.
缺失头文件引用
fatal error: driver/gpio.h: No such file or directory
修复方法：检查CMakeLists.txt并将组件添加到REQUIRES中：
cmake
idf_component_register(
    SRCS "main.c"
    REQUIRES driver
)
未定义引用
undefined reference to 'some_function'
修复方法：确保包含该函数的组件已添加到REQUIRES或PRIV_REQUIRES中。
类型错误 查找函数声明与实现之间的类型不匹配问题。

2. Runtime Panic Analysis

2. 运行时崩溃分析

Guru Meditation Error Patterns
ErrorCauseFix
StoreProhibited
Writing to invalid memoryCheck pointer initialization
LoadProhibited
Reading from invalid memoryCheck null pointers
InstrFetchProhibited
Corrupted function pointerCheck callback assignments
IntegerDivideByZero
Division by zeroAdd zero checks
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.
Guru Meditation Error 常见类型
错误类型原因修复方法
StoreProhibited
写入无效内存检查指针初始化
LoadProhibited
读取无效内存检查空指针
InstrFetchProhibited
函数指针损坏检查回调函数赋值
IntegerDivideByZero
除零操作添加零值检查
栈溢出
Guru Meditation Error: Core 0 panic'ed (Stack overflow)
修复方法：在创建任务时增大栈空间：
c
xTaskCreatePinnedToCore(task_fn, "name", 4096, NULL, 5, NULL, 0);
//                                        ^^^^ 增大此数值
栈溢出攻击检测（Stack Smashing）
Stack smashing detected
修复方法：本地缓冲区溢出问题 - 检查数组边界和字符串操作。

3. Memory Debugging

3. 内存调试

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
检查堆内存使用情况
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());
常见内存问题
  • 内存泄漏：使用
    malloc()
    后未调用
    free()
  • 重复释放：多次释放同一块内存
  • 释放后使用：访问已被释放的内存

4. Communication Debugging

4. 通信调试

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
I2C问题
E (1234) i2c: i2c_master_cmd_begin(xxx): I2C_NUM error
排查清单：
  • 验证I2C地址（7位 vs 8位格式）
  • 检查SDA/SCL GPIO引脚配置
  • 确保存在上拉电阻（典型值为4.7K）
  • 验证时钟频率兼容性
串口/UART问题
  • 波特率不匹配
  • TX/RX引脚接反
  • 未连接地线

5. Build Commands for Debugging

5. 用于调试的构建命令

bash
undefined
bash
undefined

Clean build to eliminate stale objects

清理构建以清除陈旧对象

make robocar-clean && make robocar-build-main
make robocar-clean && make robocar-build-main

Build with verbose output

构建并输出详细日志

cd packages/esp32-projects/robocar-main && idf.py build -v
cd packages/esp32-projects/robocar-main && idf.py build -v

Start serial monitor

启动串口监视器

make robocar-monitor-main PORT=/dev/cu.usbserial-0001
undefined
make robocar-monitor-main PORT=/dev/cu.usbserial-0001
undefined

6. Useful ESP-IDF Config Options

6. 实用的ESP-IDF配置选项

Enable in 
sdkconfig
or via 
idf.py 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
可在
sdkconfig
中开启，或通过
idf.py menuconfig
配置：
  • CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT
    - 重启前打印崩溃信息
  • CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK
    - 更早检测栈溢出
  • CONFIG_HEAP_POISONING_COMPREHENSIVE
    - 检测堆内存损坏

Examples

示例

Example: Debugging a Stack Overflow

示例：调试栈溢出问题

User reports: "My ESP32 keeps crashing on startup"
  1. Ask for serial monitor output
  2. Look for "Stack overflow" in panic message
  3. Identify which task is overflowing
  4. Suggest increasing stack size from 2048 to 4096
  5. Explain FreeRTOS stack sizing considerations
用户反馈："我的ESP32启动后不断崩溃"
  1. 索要串口监视器输出
  2. 在崩溃信息中查找"Stack overflow"关键词
  3. 确定是哪个任务导致栈溢出
  4. 建议将栈空间从2048增大到4096
  5. 解释FreeRTOS栈空间大小的考量因素

Example: I2C Communication Failure

示例：I2C通信故障排查

User reports: "I2C device not responding"
  1. Verify address with I2C scanner
  2. Check GPIO configuration
  3. Verify pull-up resistors
  4. Check bus speed compatibility
  5. Suggest adding delays between transactions if needed
用户反馈："I2C设备无响应"
  1. 使用I2C扫描工具验证地址
  2. 检查GPIO配置
  3. 确认上拉电阻存在
  4. 检查总线速度兼容性
  5. 必要时建议在事务之间添加延迟