SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsesp32-idf

esp32-idf

Coding & development

View repository

Updated 10-15 17:27

About this skill

ESP-IDF Projects and Builds (esp32-idf)

This Skill is the project entry point for the ESP32 family under the ESP-IDF toolchain: creating projects, setting the target, partition tables, dependency locking, build/flash, and v5→v6 migration troubleshooting. The concurrency model and business code go to esp32-freertos; pins and peripheral drivers go to esp32-peripherals.

Determine Task Type

Determine the deliverable first, then enter the corresponding Workflow:

  1. New project — build an IDF project skeleton from scratch and get build→flash→monitor working → go to Workflow A.
  2. Port an existing project(focus: v5 → v6 major version migration) — compile errors, legacy drivers removed, esp-mqtt moved to the component manager → go to Workflow B, and read v5-to-v6-migration。
  3. Component development / dependency management — add third-party components, lock versions, fix dependencies.lock → go to Workflow C.
  4. OTA rework(dual app slots + otadata + rollback) → This Skill only builds the partition table skeleton; implementation is handed off to esp32-ota。
  5. Chip not yet selected → hand off first to esp32-variants。

Preflight (verify at runtime first, then act)

idf.py --version          # 本机 IDF 实际版本；不在 PATH 会直接报错
# 已有工程时：
ls CMakeLists.txt sdkconfig partitions.csv dependencies.lock 2>/dev/null
grep -m1 "CONFIG_IDF_TARGET" sdkconfig 2>/dev/null   # 项目当前 target
ls managed_components 2>/dev/null

Distinguishthree version axes(do not mix them up):

Version axis How to confirm Determines what
Local IDF idf.py --version measured What the current machine can build
Project lock The esp-idf tag/branch actually checked out by the project ($IDF_PATH）+ dependencies.lock locked component versions The project's real behavior;managed_components/ do not edit by hand
Official latest stable Baseline is v6.1(as of 2026-09-02, verify GitHub releases at runtime) Upgrade evaluation reference, not adopted automatically
  • target must be checked against the physical chip: the chip model on the module silkscreen/schematic must match the value of set-target before continuing; if it does not match, stop and ask.
  • Specific version numbers such as v6.1, v6.0.2, and v5.5.5 are baseline values "as of 2026-09-02"; when citing them, always include the date and prompt for runtime verification.

Offline Baseline

  • This Skill's ESP-IDF facts are based on a dated baseline:ESP-IDF v6.1, read 2026-09-02, no automatic updates.
  • v6.x has breaking changes relative to v5.x (old drivers removed, esp-mqtt moved to the component manager); examples avoid relying on removed legacy APIs.
  • For behavior changes in later versions, rely on official documentation and GitHub releases; do not assert from memory.

Contracts (hardware contracts)

  • Chip/module model: based on the physical silkscreen or schematic; never guess the target from the project name.
  • Flash size and partition offsets: the flash capacity in menuconfig must match the physical device; when partition offsets are uncertain,do not fabricate, use automatic layout (see partition-table-template）。
  • Flashing channel: confirm the serial device (-p PORT or ESPPORT) and permissions; flashing will overwrite device state.
  • For issues involving partition tables, pins, or memory layout: stop when uncertain, and route to runtime verification or official sources.

Capability Boundaries + Hand-off

This Skill covers project skeleton/build/dependencies/migration troubleshooting. The following intents are explicitly handed off:

User Intent Skill
Tasks/queues/semaphores/dual-core pinning esp32-freertos
GPIO/I2C/SPI/UART/ADC/PWM pins and drivers esp32-peripherals
Chip not yet decided / chip change evaluation esp32-variants
OTA upgrade implementation (esp_ota_* / https ota / rollback confirmation) esp32-ota
Secure Boot v2 / Flash encryption esp32-secureboot
Wi-Fi provisioning (Unified Provisioning/SoftAP/BLE) esp32-wifi-provision
Deep/Light sleep, battery life design esp32-lowpower
panic/coredump/JTAG interpretation esp32-debug
On-board acceptance testing (before claiming "hardware works") fw-hil-testing
Run logic without a board first (QEMU/Wokwi) fw-emulation
Rust no_std on ESP32 (esp-hal) Out of scope rust-skills/rust-embedded(refuse and hand off)

Workflow A: New project

idf.py create-project hello_idf && cd hello_idf
idf.py set-target esp32s3        # 清空 build/ 并重新生成 sdkconfig；默认 target 是 esp32
idf.py menuconfig                # 决策点见 references/menuconfig-decisions.md
idf.py build                     # 期望：build/ 下生成 .bin/.elf/.map，末尾报告分区占用
idf.py -p /dev/ttyUSB0 flash monitor   # 可链式执行，顺序由 idf.py 保证；-p 也可用 ESPPORT

Expected output: after esptool finishes writing, the chip resets and outputs the boot log; monitor keeps printing runtime logs (exit with the shortcut it prompts).

  • When partition requirements exceed a "single factory", first change partitions.csv then build (see references for templates).
  • Add a third-party component:idf.py add-dependency <ns/name=版本> write idf_component.yml; after recursive dependency resolution it lands in managed_components/, and generates dependencies.lock(if corrupted, can be rebuilt with idf.py reconfigure rebuild).

Workflow B: v5 → v6 migration troubleshooting

  1. idf.py --version Confirm the local IDF major version and compare it with the version locked by the project.
  2. Locate by error: missing headers/symbols → suspected legacy driver removal; mqtt-related → suspected conversion to component manager.
  3. Read the breaking-change list and verification methods in v5-to-v6-migration ;Do notrecite "the complete list of removed APIs" from memory.
  4. Switch to the new-style interfaces one by one and rebuild; commit each type of fix separately for easy rollback.

Workflow C: Components and version locking

  1. idf.py add-dependency espressif/mqtt declarations such as these go into idf_component.yml。
  2. Verify that dependencies.lock and managed_components/ are consistent; put both under version control.
  3. Do not hand-edit the contents of managed_components/ —upgrade via dependency declarations.
  4. CI reproducible build = pin the esp-idf checkout version + commit dependencies.lock。

Validation Gates

  • idf.py build zero errors, and the artifact's partition usage does not exceed the target app partition (at build time it verifies the image fits in some app partition).
  • idf.py partition-table The printed result matches the partitions.csv expectation.
  • Before flashing, restate the target and serial port; in monitor, see the boot log and no repeated resets.
  • When there is no real hardware evidence, the report must be marked Build Verification Only。

Pitfalls

  1. Do notskip set-target and directly use another chip's build directory for flashing—set-target clears build and regenerates sdkconfig, and mixing them will flash the wrong image.
  2. Do nothand-edit the code in managed_components/ to "fix bugs"—it is lost on upgrade; modify upstream or add a patch component.
  3. Do notfabricate partition offset values—leave Offset blank and let the tool lay it out automatically; app partitions are naturally 64KB aligned.
  4. Do notcontinue using v5 legacy driver calls in v6.x or assume esp-mqtt is built in—read the migration reference first.
  5. Do notreport "build passed" as "board works"—before flash verification it only counts as Build Verification Only.
  6. Do notCite undated version numbers—all "latest versions" must include "as of 2026-09-02" and prompt for runtime verification.

Official Sources

Privacy

This Skill does not collect, store, or send user data, Wi-Fi credentials, or keys. Flashing and monitor only access the local serial device explicitly specified by the user; accessing official links complies with the user's environment network policy.