名称: esp-idf-助手描述: 帮助在Linux/WSL上使用乐鑫ESP-IDF开发、构建、烧录和调试ESP32/ESP8266固件。当用户询问ESP-IDF项目设置、配置目标、menuconfig、构建、通过esptool/idf.py烧录、串口监视器、分区表、sdkconfig、故障排除构建/烧录/监视器错误，或从命令行自动化常见idf.py工作流时使用。

esp-idf-助手

目标

为Linux/WSL上的ESP-IDF开发提供一个可重复的、命令行优先的工作流：配置 → 构建 → 烧录 → 监视 → 调试/故障排除。

快速开始（典型循环）

方法1：首先激活ESP-IDF环境（推荐）

# 1) 激活ESP-IDF环境（每个终端会话一次）
cd /path/to/esp-idf
. ./export.sh

# 1.1) 启用ccache以加速编译（推荐）
export IDF_CCACHE_ENABLE=1

# 2) 进入你的项目并构建
cd /path/to/your/project
idf.py set-target <target>    # 设置目标芯片（每个项目一次）
idf.py build                 # 编译
idf.py -p <PORT> -b <BAUD> flash  # 烧录到设备（可选）

常用命令

idf.py set-target <target> — 设置芯片目标：esp32, esp32s2, esp32s3, esp32c3, esp32p4
idf.py menuconfig — 配置项目设置（必须在新的终端窗口中运行）
idf.py build — 构建项目
idf.py update-dependencies — 更新项目组件依赖
idf.py partition-table — 构建分区表并打印分区条目
idf.py partition-table-flash — 将分区表烧录到设备
idf.py storage-flash — 烧录存储文件系统分区
idf.py size — 显示固件大小信息
idf.py -p <PORT> -b <BAUD> flash — 烧录固件（默认波特率：1152000）
idf.py -p <PORT> monitor — 打开串口监视器
idf.py -p <PORT> -b <BAUD> monitor — 使用特定波特率打开串口监视器（例如1152000）
idf.py -p <PORT> -b <BAUD> flash monitor — 先烧录然后监视
bash {baseDir}/scripts/monitor_auto_attach.sh --project <PROJECT_DIR> --idf <IDF_DIR> --port <PORT> --baud <BAUD> — 自动附加串口（usbipd）并在打开失败时重试监视器
bash {baseDir}/scripts/flash_with_progress.sh --project <PROJECT_DIR> --idf <IDF_DIR> --port <PORT> --mode <MODE> — 带实时进度输出的烧录（支持自动usbipd附加重试、错误摘要和第二次重试）

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 — 清理构建目录

在新窗口打开监视器（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。
退出监视器：Ctrl+]。

工作流决策树

如果用户还没有项目 → 从示例/模板创建；确认目标芯片和IDF版本。
如果构建失败 → 收集第一个错误行；识别缺失的依赖/工具链/cmake/python包；确认IDF环境。
如果烧录失败 → 确认端口权限/WSL USB直通、波特率、启动模式、正确的芯片目标。
如果监视器显示乱码 → 波特率错误（监视器使用应用波特率）、串口适配器设置错误或控制台编码错误。
如果启动循环/崩溃 → 请求崩溃回溯；使用addr2line（或idf.py monitor内置功能）解码并检查分区/sdkconfig。
如果**[Errno 11] Could not exclusively lock port <PORT>** → 串口被另一个进程占用；强制释放它：
```
sudo fuser -k <PORT>
```

需要向用户询问什么（最少信息）

芯片目标：例如esp32、esp32s2、esp32s3、esp32c3、esp32p4。
ESP-IDF版本 + 如何安装/激活（IDF Tools安装程序 vs git克隆；IDF_PATH / ESPIDF_ROOT）。
项目路径 + 是否为ESP-IDF项目（有CMakeLists.txt、main/、sdkconfig）。
串口路径：使用<PORT>（例如/dev/ttyUSB0、/dev/ttyACM*，或WSL映射的/dev/ttyS*）。
确切的失败命令 + 输出中的第一个错误块。

串口设备获取（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

新功能：创建ESP-IDF项目

描述：创建一个新的ESP-IDF项目或从ESP组件注册表中的示例创建项目。

用法：

idf.py create-project <project_name> <project_path>
idf.py create-project-from-example <example_name> <project_path>

闪存加密支持（加密烧录）

直接使用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 — 简洁的命令模式 + 报告错误时要粘贴的内容。
references/idf-py-help.txt — 捕获的idf.py --help输出，用于快速查找/搜索。

要刷新已安装ESP-IDF版本的帮助文本，请运行：

scripts/capture_idf_help.sh

assets/

默认未使用。