# Send ESP-IDF Helper to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "esp-idf-helper",
    "name": "ESP-IDF Helper",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/547895019/esp-idf-helper",
    "canonicalUrl": "https://clawhub.ai/547895019/esp-idf-helper",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/esp-idf-helper",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=esp-idf-helper",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "references/esp-idf-cli.md",
      "references/idf-py-help.txt",
      "scripts/capture_idf_help.sh",
      "scripts/flash_with_progress.sh",
      "scripts/monitor_auto_attach.sh"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/esp-idf-helper"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/esp-idf-helper",
    "downloadUrl": "https://openagent3.xyz/downloads/esp-idf-helper",
    "agentUrl": "https://openagent3.xyz/skills/esp-idf-helper/agent",
    "manifestUrl": "https://openagent3.xyz/skills/esp-idf-helper/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/esp-idf-helper/agent.md"
  }
}
```
## Documentation

### Goal

Provide a repeatable, command-line-first workflow for ESP-IDF development on Linux/WSL: configure → build → flash → monitor → debug/troubleshoot.

### Method 1: Activate ESP-IDF first (Recommended)

# 1) Source the ESP-IDF environment (once per terminal session)
cd /path/to/esp-idf
. ./export.sh

# 1.1) Enable ccache to speed up compilation (recommended)
export IDF_CCACHE_ENABLE=1

# 2) Go to your project and build
cd /path/to/your/project
idf.py set-target <target>    # Set target chip (once per project)
idf.py build                 # Compile
idf.py -p <PORT> -b <BAUD> flash  # Flash to device (optional)

### Common commands

idf.py set-target <target> — Set chip target: esp32, esp32s2, esp32s3, esp32c3, esp32p4
idf.py menuconfig — Configure project settings (must run in a new terminal window)
idf.py build — Build the project
idf.py update-dependencies — Update project component dependencies
idf.py partition-table — Build partition table and print partition entries
idf.py partition-table-flash — Flash partition table to device
idf.py storage-flash — Flash storage filesystem partition
idf.py size — Show firmware size information
idf.py -p <PORT> -b <BAUD> flash — Flash firmware (default baud: 1152000)
idf.py -p <PORT> monitor — Open serial monitor
idf.py -p <PORT> -b <BAUD> monitor — Open serial monitor with specific baud (e.g. 1152000)
idf.py -p <PORT> -b <BAUD> flash monitor — Flash then monitor
bash {baseDir}/scripts/monitor_auto_attach.sh --project <PROJECT_DIR> --idf <IDF_DIR> --port <PORT> --baud <BAUD> — Auto attach serial (usbipd) and retry monitor on open failure
bash {baseDir}/scripts/flash_with_progress.sh --project <PROJECT_DIR> --idf <IDF_DIR> --port <PORT> --mode <MODE> — Flash with real-time progress output (supports auto usbipd attach retry, error summary, and second retry)

flash_with_progress 使用示例

# 普通烧录整个固件（带进度）
bash {baseDir}/scripts/flash_with_progress.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --mode flash

# 加密烧录 app（带进度）
bash {baseDir}/scripts/flash_with_progress.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --mode encrypted-app-flash

# 仅烧录分区表（带进度）
bash {baseDir}/scripts/flash_with_progress.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --mode partition-table-flash

# 仅烧录文件系统分区（storage，带进度）
bash {baseDir}/scripts/flash_with_progress.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --mode storage-flash

# 指定波特率并关闭自动串口映射重试
bash {baseDir}/scripts/flash_with_progress.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --baud 460800 \\
  --mode flash \\
  --no-auto-attach

# 串口异常时自动二次重试（默认 retries=2，也可手动指定）
bash {baseDir}/scripts/flash_with_progress.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --mode encrypted-app-flash \\
  --retries 2

idf.py fullclean — Clean build directory

### 在新窗口打开 monitor（Windows + WSL2）

推荐用脚本方式，避免 PowerShell/cmd 引号和 UNC 路径问题。

### 在新窗口打开 menuconfig（必须）

menuconfig 是 TUI 交互界面，必须在新窗口打开（不要在非交互后台中运行）。

在 WSL 直接运行（你已在独立终端时）：

bash {baseDir}/scripts/run_menuconfig.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR>

从 Windows PowerShell 拉起新窗口运行：

Start-Process powershell -ArgumentList '-NoExit','-Command','wsl.exe -d <DISTRO> --cd / -- bash {baseDir}/scripts/run_menuconfig.sh --project <PROJECT_DIR> --idf <IDF_DIR>'

### 打开串口失败时自动映射并重试

当 idf.py monitor 因串口打开失败（端口不存在/被占用）报错时，可自动执行 usbipd 串口映射脚本并重试一次：

bash {baseDir}/scripts/monitor_auto_attach.sh \\
  --project <PROJECT_DIR> \\
  --idf <IDF_DIR> \\
  --port <PORT> \\
  --baud <BAUD> \\
  --keyword "ESP32"

在 WSL 创建启动脚本：

cat >/tmp/run_monitor.sh <<'EOF'
#!/usr/bin/env bash
set -e
cd /path/to/your/project
source /path/to/esp-idf/export.sh
exec idf.py -p <PORT> -b 1152000 monitor
EOF
chmod +x /tmp/run_monitor.sh

在 Windows PowerShell 新开窗口执行：

Start-Process cmd.exe -WorkingDirectory C:\\ -ArgumentList '/k','wsl.exe -d <DISTRO> -- bash /tmp/run_monitor.sh'

说明：

使用 cmd.exe -WorkingDirectory C:\\ 可以避免 \\\\wsl.localhost\\... UNC 路径导致工作目录掉到 C:\\Windows。
退出 monitor：Ctrl+]。

### Workflow decision tree

If the user has no project yet → create from example/template; confirm target chip and IDF version.
If build fails → collect the first error lines; identify missing deps/toolchain/cmake/python packages; confirm IDF env.
If flash fails → confirm PORT permissions/WSL USB passthrough, baud rate, boot mode, correct chip target.
If monitor is gibberish → wrong baud (monitor uses app baud), wrong serial adapter settings, or wrong console encoding.
If boot loop / panic → request panic backtrace; decode with addr2line (or idf.py monitor built-in) and check partition/sdkconfig.
If [Errno 11] Could not exclusively lock port <PORT> → serial port is occupied by another process; force release it with:
sudo fuser -k <PORT>

### What to ask the user for (minimal)

Chip target: e.g. esp32, esp32s2, esp32s3, esp32c3, esp32p4.
ESP-IDF version + how it’s installed/activated (IDF Tools installer vs git clone; IDF_PATH / ESPIDF_ROOT).
Project path + whether it’s an ESP-IDF project (has CMakeLists.txt, main/, sdkconfig).
Serial port path: use <PORT> (e.g. /dev/ttyUSB0, /dev/ttyACM*, or WSL mapped /dev/ttyS*).
Exact failing command + the first error block in output.

### 串口设备获取（Windows + WSL2）

先在 Windows PowerShell 找到串口号，再在 WSL2 里映射 USB 设备。

### 安装 usbipd-win（Windows，推荐）

在 管理员模式 PowerShell 中执行：

winget install dorssel.usbipd-win

然后查看并映射设备：

# Windows PowerShell：查看 USB 设备与 BUSID
usbipd list

# 将设备挂载到 WSL（每次重新插拔 USB 后都要重新执行）
usbipd attach --wsl --busid=<BUSID>

### 串口自动映射（推荐）

可直接使用脚本自动选择并挂载串口设备（优先选择 Connected 区域中的 serial 设备，且优先 STATE=Shared）：

bash {baseDir}/scripts/usbipd_attach_serial.sh

常用参数：

# 指定 BUSID
bash {baseDir}/scripts/usbipd_attach_serial.sh --busid <BUSID>

# 指定发行版
bash {baseDir}/scripts/usbipd_attach_serial.sh --distro <DISTRO>

# 按关键词筛选设备（如 ESP32 / COMxx / CP210x）
bash {baseDir}/scripts/usbipd_attach_serial.sh --keyword "ESP32"

# 仅预览，不执行
bash {baseDir}/scripts/usbipd_attach_serial.sh --dry-run

说明：

每次 USB 设备重新插拔后，BUSID 可能变化，需要重新 usbipd list 或重新运行自动映射脚本。
重新插拔 USB 后，通常都要再执行一次 usbipd attach --wsl --busid=<BUSID>（脚本会自动执行）。
在 WSL2 内可用 ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null 确认串口节点。

### 首次需要手动加载内核模块（WSL 2.3.11+）

在较新的 WSL 版本中，内核采用模块化设计，vhci_hcd（虚拟主机控制器接口）驱动可能不会自动加载。

在 WSL 终端执行：

sudo modprobe vhci_hcd

### New Feature: Create ESP-IDF Projects

Description: Create a new ESP-IDF project or create a project from an example in the ESP Component Registry.
Usage:
idf.py create-project <project_name> <project_path>
idf.py create-project-from-example <example_name> <project_path>

### Flash Encryption Support (加密烧录)

直接使用 idf.py 执行加密/非加密应用烧录：

# 加密烧录整个固件 (bootloader + partition table + app)
idf.py -p <PORT> encrypted-flash

# 加密烧录 app 分区
idf.py -p <PORT> encrypted-app-flash

# 非加密烧录 app 分区
idf.py -p <PORT> app-flash

# 非加密烧录整个固件 (bootloader + partition table + app)
idf.py -p <PORT> flash

### references/

references/esp-idf-cli.md — concise command patterns + what to paste back when reporting errors.
references/idf-py-help.txt — captured idf.py --help output for quick lookup/search.

To refresh the help text for your installed ESP-IDF version, run:

scripts/capture_idf_help.sh

### assets/

Not used by default.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: 547895019
- Version: 1.0.0
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-04-30T16:55:25.780Z
- Expires at: 2026-05-07T16:55:25.780Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/esp-idf-helper)
- [Send to Agent page](https://openagent3.xyz/skills/esp-idf-helper/agent)
- [JSON manifest](https://openagent3.xyz/skills/esp-idf-helper/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/esp-idf-helper/agent.md)
- [Download page](https://openagent3.xyz/downloads/esp-idf-helper)