mcpField
E
esp32-debugging

esp32-debugging

github.com/laurigates开发7310 次安装今天更新
代码仓库

关于 esp32-debugging

esp32-debugging 是面向 ESP-IDF 项目的调试技能，帮助开发者分析编译错误、运行时崩溃、内存问题和外设通信故障。内容包含诊断步骤、常见原因及构建和监控命令。

主要功能

  1. 01分析编译错误与运行时崩溃
  2. 02排查内存和栈问题
  3. 03诊断 I2C、SPI 和 UART 故障
  4. 04提供构建与串口监控命令
  5. 05列出 ESP-IDF 配置选项

适用场景

  1. 01分析 ESP-IDF 编译失败
  2. 02解读 Guru Meditation Error
  3. 03排查堆栈或内存崩溃
  4. 04诊断 I2C 或串口通信问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laurigates/mcu-tinkering-lab --skill esp32-debugging

安装后在 Claude Code 中输入/esp32-debugging确认已加载。

详细介绍

ESP32 固件调试指南

何时使用此技能

在用户遇到以下情况时应用此技能：

  • ESP-IDF 项目编译出错
  • 出现运行时 panic 或 “Guru Meditation Error” 消息
  • 发生与内存相关的崩溃或栈溢出
  • I2C/SPI/UART 通信失败
  • 需要帮助解读串口监视器输出

$ARGUMENTS 可能包含错误消息或问题背景。

调试流程

首先询问背景信息

如果 $ARGUMENTS 中的错误信息不明确，请让用户提供：

  1. 完整的错误消息或 panic 输出
  2. 正在构建的项目
  3. 最近的代码变更
1. 编译错误分析

执行全新构建以捕获错误：

just <project>::build 2>&1 | tail -100

缺少头文件

fatal error: driver/gpio.h: No such file or directory

修复：将组件添加到 main/CMakeLists.txt 中的 REQUIRES：

idf_component_register(
    SRCS "main.c"
    REQUIRES driver
)

未定义的引用

undefined reference to 'some_function'

修复：确保包含该函数的组件位于 REQUIRES 或 PRIV_REQUIRES 中。

类型错误 检查函数声明与实现之间是否存在类型不匹配。

2. 运行时 panic 分析

Guru Meditation Error 模式

错误原因修复方法
StoreProhibited写入无效内存检查指针是否已初始化
LoadProhibited读取无效内存检查空指针
InstrFetchProhibited函数指针损坏检查回调赋值
IntegerDivideByZero除以零添加零值检查
Double exception，回溯为 CORRUPTED，A0 = 可识别的常量（例如 0x10000000）栈缓冲区向上溢出到调用者栈帧——VLA 或局部数组的索引超出末尾；栈金丝雀只监视低端阅读最后一条日志到 panic 之间的代码；在刚刚调用的驱动中查找 A0 的最高字节。参见 .claude/rules/gated-init-paths.md

栈溢出

Guru Meditation Error: Core 0 panic'ed (Stack overflow)

修复：在任务创建时增大栈大小：

xTaskCreatePinnedToCore(task_fn, "name", 4096, NULL, 5, NULL, 0);
//                                        ^^^^ increase this

栈破坏

Stack smashing detected

修复：局部缓冲区溢出——检查数组边界和字符串操作。

此消息需要启用 CONFIG_COMPILER_STACK_CHECK_MODE_*。关闭该选项时（robocar-unified 的默认设置），同一溢出会报告为 double exception，并伴有损坏的回溯——参见上表。使用主机测试固定此修复：在不修改文件的情况下，使用 -fsanitize=address 编译该文件（packages/robocar/unified/test/test_pca9685_multi.c 可作为模板）。

3. 内存调试

检查堆使用情况

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. 通信调试

I2C 问题

E (1234) i2c: i2c_master_cmd_begin(xxx): I2C_NUM error

检查清单：

  • 确认 I2C 地址格式（7 位还是 8 位）
  • 检查 SDA/SCL GPIO 引脚
  • 确保已安装上拉电阻（通常为 4.7K）
  • 确认时钟频率兼容

串口/UART 问题

  • 波特率不匹配
  • TX/RX 接反
  • 缺少接地连接

双控制器同步（I2C）

  • 检查两个控制器是否都在运行
  • 确认 I2C 地址一致
  • 检查 GPIO 引脚配置
5. 用于调试的构建命令
# Clean build to eliminate stale objects
just <project>::clean && just <project>::build

# Start serial monitor
just <project>::monitor PORT=/dev/cu.usbserial-0001
6. 有用的 ESP-IDF 配置选项

在 sdkconfig.defaults 中启用，或通过 menuconfig 启用：

  • CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT — 重启前打印 panic 信息
  • CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK — 更早检测栈溢出
  • CONFIG_HEAP_POISONING_COMPREHENSIVE — 检测堆损坏

常见修复方法

症状修复方法
栈溢出在 xTaskCreate 中增大任务栈大小
内存泄漏检查是否缺少 free() 调用
I2C 超时检查连接、上拉电阻和地址
启动时崩溃将 CONFIG_ESP_MAIN_TASK_STACK_SIZE 增大到 8192+

评论

支持 Markdown