esp-idf

ESP-IDF 固件工程

适用场景

• 开发或配置 ESP-IDF 固件应用。
• 排查 ESP-IDF 项目中的编译错误或依赖问题。
• 刷写已获授权的硬件并验证运行时行为。
• 使用解码后的监视器输出调试运行时崩溃。

项目和环境

1. 找到包含顶层 CMakeLists.txt 的项目根目录。在多应用仓库中，找出每个受影响的项目根目录。
2. 阅读 README、CI 配置、sdkconfig.defaults*、清单和构建脚本，确定所需的 ESP-IDF 版本、目标和验证要求。
3. 创建项目时，使用 idf.py create-project <PROJECT_NAME>，不要手动生成脚手架文件。
4. 使用 idf.py --version 验证环境。优先采用仓库规定的设置方式；否则使用 EIM：
   • eim --version
   • 使用 eim list 查找已安装版本、选定版本和绝对路径
   • eim select <ESP_IDF_VERSION>
   • eim run "idf.py --version" <ESP_IDF_VERSION>
   • eim run "idf.py <command>" <ESP_IDF_VERSION>
   • 仅在获得安装授权时使用 eim install -i <ESP_IDF_VERSION>
   • 仅在用户要求交互式安装时使用 eim wizard
5. 如果无法使用 EIM，但所需的 ESP-IDF 环境已有效，则继续使用该环境。不要仅仅为了安装 EIM 而阻碍工作。
6. 使用与版本匹配的 ESP-IDF 文档和迁移指南。

目标和硬件识别

• 在探测硬件前，根据配置和构建输出确定项目目标。
• 使用 idf.py set-target <TARGET> 前先征求用户同意。该命令会清除 build/、将 sdkconfig 移至 sdkconfig.old 并重新配置项目；之后不要再执行多余的 fullclean。
• 仅当任务需要且已确认端口时才探测硬件。检查已安装的 esptool 帮助，并使用其支持的语法，例如：
  • 当前语法：esptool --port <PORT> chip-id
  • 旧版语法：esptool.py --port <PORT> chip_id
• 如果无法自动进入引导加载程序模式，请让用户将设备置于下载模式后再重试。
• 将配置的目标与实际芯片、启动时的闪存设置和应用元数据进行比较。除非确有需要，否则不要报告设备 MAC 地址。

构建和配置

• 正常的增量构建使用 idf.py build；构建失败时，检查首批相关错误以及引用的日志。
• 将 sdkconfig 视为生成文件。将有意设置的默认值放入 sdkconfig.defaults*；特定目标的默认值文件必须有基础文件 sdkconfig.defaults，即使该基础文件为空也不例外。
• 更改 Kconfig 或 Kconfig.projbuild 后，先询问是否运行 idf.py reconfigure。构建通常会检测到 Kconfig 定义变更，但已存储在 sdkconfig 中的值可能不会被更改后的默认值覆盖。
• 切勿手动编辑 build/、managed_components/ 或 dependencies.lock。
• 仅在确认存在旧构建问题且获得用户批准后，才使用 idf.py fullclean。

烧录、监控和诊断

• 切勿仅因开发板已连接就进行烧录。只有在用户提出要求，或确认端口、目标及设备可安全覆盖后获得明确授权，才能烧录。
• 使用 idf.py -p <PORT> flash 进行烧录；获准进行运行时验证时，使用 idf.py -p <PORT> flash monitor。
• 使用 idf.py -p <PORT> monitor 分析崩溃，以便将回溯中的地址解码为源代码位置。
• 持续捕获输出，直到出现所请求的行为或崩溃；干净地停止监控，并总结相关证据。
• 只有当固件提供控制台且终端支持时，才发送交互式输入。
• 将 linenoise 关于不支持转义序列的警告视为无害；它只会禁用行编辑和历史记录，不会影响固件行为。
• 怀疑存在内存损坏或泄漏时，先检查现有证据，再提出适当的堆跟踪或调试配置，并在更改配置前获得批准。

ESP-IDF 代码规范

• 将入口点保留为 void app_main(void)。
• 优先使用 ESP-IDF API 和头文件，而非临时编写的平台代码。
• 除非确有需要，否则使用 ESP_LOGI/W/E，避免过度使用 printf。
• 使用 idf_component_register(...) 注册组件；使用 REQUIRES 或 PRIV_REQUIRES 声明依赖项。
• 明确处理 esp_err_t 结果，并在适当情况下避免长时间阻塞操作，确保让出执行权。

组件注册表

• 在本地实现依赖项之前，先搜索 ESP 组件注册表。
• 有可用的注册表 MCP 工具时，优先使用；否则使用公共 REST API 作为备用方案。
• 在项目根目录下使用 idf.py add-dependency "namespace/component^<VERSION>" 添加依赖项。如果依赖项属于 main 之外的组件，请使用 --component=<NAME> 或 --path=<PATH>。
• 如果有多个候选项都符合要求，请比较兼容性、维护情况、许可和 API 适配度。只有在选择仍会对结果产生实质影响时，才询问用户。
• REST 端点和示例请参阅 component_registry.md。

交接

• 报告运行过的命令、ESP-IDF 版本、目标、测试和使用的硬件。
• 总结配置更改，并明确指出任何未经验证的内容。