跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

esp32-build-fix

Diagnoses and fixes ESP-IDF build, link, CMake/Kconfig, component-manager and flashing failures, using the build log to classify the error before changing anything. Use when "idf.py build fails", "undefined reference to", "No such file or directory" for a header, "Failed to resolve component", "CMake Error", "multiple definition of", "region `iram0_0_seg' overflowed", "app partition is too small", "implicit declaration of function", "esptool Failed to connect", "Wrong boot mode detected", "No serial data received", "Permission denied /dev/ttyUSB0", "A fatal error occurred", "set-target", or after an ESP-IDF version upgrade (v4 → v5) breaks the build.

agodianel · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add agodianel/esp32-claude-workbench --skill esp32-build-fix

技能说明


name: esp32-build-fix description: Diagnoses and fixes ESP-IDF build, link, CMake/Kconfig, component-manager and flashing failures, using the build log to classify the error before changing anything. Use when "idf.py build fails", "undefined reference to", "No such file or directory" for a header, "Failed to resolve component", "CMake Error", "multiple definition of", "region `iram0_0_seg' overflowed", "app partition is too small", "implicit declaration of function", "esptool Failed to connect", "Wrong boot mode detected", "No serial data received", "Permission denied /dev/ttyUSB0", "A fatal error occurred", "set-target", or after an ESP-IDF version upgrade (v4 → v5) breaks the build. license: MIT metadata: source: esp32-workbench version: "0.2.0"

ESP32 Build & Flash Fix

Classify first, then make the smallest fix. Never "fix" a build by deleting configuration the user cares about.

Tools

If the esp32-workbench MCP server is connected, call its tools; otherwise run the CLI. If esp32wb is not on PATH, use uvx --from git+https://github.com/agodianel/esp32-claude-workbench esp32wb <args>. Add --json for machine-readable output.

NeedMCP toolCLI
Classify build / flash outputbuild_log_triageidf.py build 2>&1 | tee build.log; esp32wb build-log build.log (or ... | esp32wb build-log -)
App vs partition sizepartition_checkesp32wb partitions partitions.csv --sdkconfig sdkconfig --bin build/<app>.bin
sdkconfig sanitysdkconfig_reviewesp32wb sdkconfig sdkconfig
Chip facts (toolchain, USB/strapping pins for download mode)chip_infoesp32wb chip <target>
API changed / renamed?search_esp_docsesp32wb docs search "<symbol or error>" --target T

Steps

1. Capture the full first error

Rerun with output captured (idf.py build 2>&1 | tee build.log). The first error matters; later ones are usually cascades. Run esp32wb build-log build.log.

2. Establish context

  • idf.py --version and the version the project expects (README, CI, idf_component.yml dependencies.idf).
  • Target: CONFIG_IDF_TARGET in sdkconfig vs the board you have. A stale sdkconfig from another target causes many confusing errors.
  • Was it building before? What changed (IDF upgrade, new component, new target, managed_components update)?

3. Classify and fix

CategorySignatureUsual fix
Missing headerfatal error: xyz.h: No such file or directoryAdd the owning component to REQUIRES/PRIV_REQUIRES; in recent IDF v5.x releases drivers are split into esp_driver_* components (e.g. esp_driver_gpio, esp_driver_i2c) — driver still works as an umbrella
Linkerundefined reference toSource not in SRCS, missing REQUIRES, C/C++ name mangling (extern "C"), Kconfig option disabling the feature
Duplicate symbolmultiple definition ofFunction defined in a header without static inline, or same file compiled twice
Kconfig'CONFIG_X' undeclaredOption renamed/removed in this IDF version or not enabled; check sdkconfig and IDF migration guide
Component managerFailed to resolve component, version solver errorsFix idf_component.yml constraints; idf.py update-dependencies
API change after upgradeimplicit declaration, unknown type nameFollow the ESP-IDF migration guide (ADC → adc_oneshot, I2C → i2c_master driver, legacy timer/RMT/I2S drivers replaced)
Memory overflowregion 'iram0_0_seg' overflowed, dram0_0_seg overflowMove code out of IRAM, reduce static buffers, enable PSRAM for large buffers
App too bigapp partition is too small / partition check failsLarger app partition or custom partitions.csv, -Os (CONFIG_COMPILER_OPTIMIZATION_SIZE), drop unused features
Target mismatchstatic assertions, missing SoC symbolsidf.py set-target <target> (this regenerates sdkconfig)
Toolchain / envxtensa-...-elf-gcc: not found, riscv32-esp-elf-gcc: not found, Python env errorsRe-run install.sh <target> / export.sh for the IDF version in use

Details and examples: build failure playbook.

4. Flash and monitor failures

Read flash failure playbook for esptool errors (Failed to connect, Wrong boot mode detected, No serial data received, permission denied, invalid header boot loops after flashing). Download-mode entry and the USB port differ per chip — check esp32wb chip <target> for the boot strapping pins and USB-Serial-JTAG pins.

5. Verify

  • Clean build of the affected configuration (idf.py fullclean && idf.py build only after the targeted fix, to prove it is not a stale-cache artifact).
  • No new warnings.
  • If flashing was the issue: flash + boot log showing app_main reached.
  • Record commands and output as test evidence in the mission.

Safety

  • idf.py set-target and deleting sdkconfig discard local menuconfig changes. Back up sdkconfig first and make sure sdkconfig.defaults captures what matters.
  • idf.py erase-flash wipes NVS (Wi-Fi credentials, calibration, bonds). Ask first.
  • Never burn eFuses or enable secure boot/flash encryption to "fix" a flash error.
  • A code change made to fix the build still needs a (brief) implementation contract.