esp-idf-setup

ESP-IDF プロジェクトのセットアップガイド

このスキルを使用するタイミング

次のような場合にこのスキルを適用します。

• 初めてビルド環境をセットアップしたい（setup）
• 新しい ESP32 プロジェクトを作成したい（new <name> <platform>）
• 開発環境を確認したい（check）
• CMakeLists.txt またはコンポーネントの依存関係を設定したい
• sdkconfig または menuconfig についてサポートが必要
• モノレポにプロジェクトを追加したい

$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）

対話型コンテナシェル

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 がない → 「ESP-IDF プロジェクトをビルドするには Docker をインストールしてください」
• シリアルポートがない → 「ESP32 デバイスを USB で接続してください」
• ツールが不足している → 「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

モノレポへの追加

1. プロジェクトを packages/<domain>/<name>/ に配置します
2. import '../../../tools/esp32.just' を含む justfile を作成します
3. ルートの justfile にモジュールとして登録します：mod name 'packages/<domain>/<name>'
4. テストします：just name::build

コンポーネントの管理

IDF Component Manager

コンポーネントディレクトリに idf_component.yml を作成します。

dependencies:
  espressif/led_strip: "^2.0.0"

ローカルコンポーネント

プロジェクトの components/ ディレクトリに配置します。

よくある設定タスク

Menuconfig（コンテナ内で実行）

just webserver::menuconfig
just xbox::menuconfig

新しいプロジェクトの手順

1. 指定されたプラットフォーム用のディレクトリ構成を作成します
2. 適切なボイラープレートを含むテンプレートファイルを生成します
3. ルートの justfile に mod としてプロジェクトを追加します
4. ユーザー向けに次の手順を表示します

ベストプラクティス

1. sdkconfig.defaults を使用する — 生成された sdkconfig はコミットしないでください
2. tools/esp32.just をインポートする — container_cmd、require-port などを重複して定義しないでください
3. 依存関係は最小限にする — 実際に使用する REQUIRES のみを含めてください
4. GPIO の使用方法を文書化する — /wiring-doc を使って WIRING.md を作成してください