esp-idf-setup

ESP-IDF 项目设置指南

何时使用此技能

在用户出现以下情况时使用此技能：

• 想要首次设置构建环境（setup）
• 需要创建新的 ESP32 项目（new <name> <platform>）
• 想要验证开发环境（check）
• 想要配置 CMakeLists.txt 或组件依赖项
• 需要有关 sdkconfig 或 menuconfig 的帮助
• 想要将项目添加到 monorepo

根据 $ARGUMENTS：

• 为空或为 setup → 设置环境
• new <name> <platform> → 创建新项目
• check → 验证环境

环境设置（基于 Docker）

所有 ESP-IDF 构建都在 Docker 容器中运行。无需在本地安装 ESP-IDF。

快速设置

# Full environment: Docker images + dev tools
just setup-all

# Or individually:
just docker-build        # Build ESP-IDF container image
just install-dev-tools   # Install host-side linters/formatters

主机端工具

这些工具在本机运行（不在容器中）：

• esptool — 用于烧录固件（pip install esptool）
• clang-format — C/C++ 格式化（brew install clang-format）
• cppcheck — C/C++ 检查（brew install cppcheck）
• ruff — Python 检查（pip install ruff）
• pre-commit — git 钩子（pip install pre-commit）

交互式容器 Shell

just docker-dev          # Root-level interactive shell
just webserver::shell    # Project-specific shell

验证环境

运行环境检查：

just check-environment

还需检查：

1. 可用串口：

   ls -la /dev/cu.usbserial-* /dev/ttyUSB* 2>/dev/null || echo "No USB serial devices found"
   

2. Docker 是否可用：

   docker --version
   

3. 项目结构：

   just --list
   

提供摘要：Docker 状态、串口、找到的项目、缺失的依赖项。

如果发现问题：

• 缺少 Docker →“安装 Docker 以构建 ESP-IDF 项目”
• 没有串口 →“通过 USB 连接 ESP32 设备”
• 缺少工具 →“运行 just install-dev-tools”

创建新项目

支持的平台

• esp32 — 基于 ESP-IDF 的 ESP32 项目
• esp32-cam — ESP32-CAM 专用项目
• arduino — Arduino 平台项目
• stm32 — STM32 平台项目

ESP32/ESP32-CAM 结构

packages/<domain>/$name/
├── justfile
├── CMakeLists.txt
├── sdkconfig.defaults
├── version.txt
├── main/
│   ├── CMakeLists.txt
│   └── main.c
└── README.md

Justfile（导入共享配置）

# Project Name
# Run `just --list` to see available recipes

import '../../../tools/esp32.just'

project_dir := "packages/<domain>/project-name"
port := env("PORT", _detected_serial)  # or _detected_s3 for ESP32-S3
target := "esp32"                       # or "esp32s3"

default:
    @just --list

[group: "build"]
build:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Building project-name..."
    {{container_cmd}} compose -f {{compose_file}} run --rm \
        -w /workspace/{{project_dir}} \
        esp-idf \
        bash -c "idf.py set-target {{target}} && idf.py build"

根目录 CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(project-name)

主组件 CMakeLists.txt

idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES driver nvs_flash esp_wifi
)

sdkconfig.defaults

CONFIG_IDF_TARGET="esp32"
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
CONFIG_PARTITION_TABLE_SINGLE_APP=y
CONFIG_LOG_DEFAULT_LEVEL_INFO=y

Arduino 结构

packages/arduino-projects/$name/
├── src/
│   └── main.cpp
├── include/
├── lib/
├── platformio.ini
└── README.md

STM32 结构

packages/stm32-projects/$name/
├── src/
│   └── main.c
├── include/
├── Makefile
└── README.md

添加到 monorepo

1. 将项目放在 packages/<domain>/<name>/
2. 创建 justfile，并加入 import '../../../tools/esp32.just'
3. 在根目录 justfile 中注册为模块：mod name 'packages/<domain>/<name>'
4. 测试：just name::build

组件管理

IDF 组件管理器

在组件目录中创建 idf_component.yml：

dependencies:
  espressif/led_strip: "^2.0.0"

本地组件

放在项目的 components/ 目录中。

常见配置任务

Menuconfig（在容器中运行）

just webserver::menuconfig
just xbox::menuconfig

新项目步骤

1. 为指定平台创建目录结构
2. 生成包含适当样板代码的模板文件
3. 将项目作为 mod 添加到根目录 justfile
4. 向用户打印后续步骤

最佳实践

1. 使用 sdkconfig.defaults — 不要提交生成的 sdkconfig
2. 导入 tools/esp32.just — 不要重复定义 container_cmd、require-port 等内容
3. 尽量减少依赖项 — 仅包含实际使用的 REQUIRES
4. 记录 GPIO 用法 — 使用 /wiring-doc 创建 WIRING.md