小智AIチャットボット文書センター | 小智AI.Dev
開発説明
ESP-IDF 開発環境構築と小智コンパイル

ESP-IDF 開発環境構築と小智コンパイル

このガイドでは、ESP-IDF 開発環境を構築して小智ファームウェアをビルドする方法を説明します。例は Windows が中心ですが、コマンドラインの手順は Linux でも同じです。

バージョン要件（xiaozhi-esp32 の README より、v2.5.x 対応）

  • 最低要件は ESP-IDF v6.0.1 で、release/v6.1 ブランチが推奨されています。
  • ESP-IDF 5.x はサポート対象外です。5.x ではビルドが依存関係の解決段階で失敗します。
  • release/v6.1 ブランチを使用し、v6.1 リリースタグは避けてください。このタグは ESP32-C3 で Wi-Fi の初期化に失敗するという報告があります。詳細は issue #2344 を参照してください。

開発環境の選び方

  • エディタ：Cursor または VSCode に ESP-IDF 拡張機能を入れ、SDK は v6.0.1 以降を選択します。
  • OS：プロジェクトとしては Linux を推奨しています（ビルドが速く、シリアルドライバの問題もありません）。Windows でも利用できます。
  • コードスタイル：Google C++ スタイルを採用しています。コードを提出する前に コードスタイルガイド を参照してください。

ESP-IDF のインストール

1. インストーラのダウンロード

Windows では、次の場所から ESP-IDF インストーラを入手できます。

v6.0.1 以降を選択してください。推奨の release/v6.1 ブランチを使う場合は Git で取得します。

git clone -b release/v6.1 --recursive https://github.com/espressif/esp-idf.git

2. インストール手順

  1. ダウンロードしたインストーラを実行します
  2. ライセンス契約に同意します
  3. インストール先を選びます（C ドライブは避け、パスに日本語や中国語を含めないでください）
  4. ウィザードに従って完了します

3. インストールの確認

  1. インストーラが作成した ESP-IDF PowerShell ショートカットを開きます（名称は選択したバージョンによって多少異なります）
  2. ターミナルが自動的に IDF 環境を読み込みます
  3. バージョンが 6.0.1 以上であることを確認します。
idf.py --version
  1. サンプルプロジェクトをビルドします。
cd examples/get-started/hello_world/
idf.py build

小智ファームウェアのビルド

1. ソースコードの取得 

# Git でクローン（推奨）
git clone https://github.com/78/xiaozhi-esp32

# または GitHub から ZIP をダウンロード

2. ボードの設定

  1. ターゲットチップを設定します。
# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3
  1. ボードを選択します。
idf.py menuconfig
# Xiaozhi Assistant -> Target Board に進みます
ボードのディレクトリに config.json がある場合は、同梱のスクリプトでターゲットチップとボードを一度に設定できます：python scripts/build.py <ボードのディレクトリ名>。言語とウェイクワードは --language、--wake-word で指定します。詳細は カスタムボードガイド を参照してください。

3. ビルドと書き込み

基本コマンド：

# ビルドのみ
idf.py build

# ビルドして書き込み
idf.py build flash monitor

# より高速な書き込み速度を使用
idf.py -b 2000000 build flash monitor

# シリアルポートを指定
idf.py -p COM5 build flash monitor

4. よく使う設定の変更

ウェイクワードの変更 

idf.py menuconfig
# ESP Speech Recognition -> Wake Word に進みます

WebSocket API の変更 

idf.py menuconfig
# Xiaozhi Assistant -> Websocket -> Websocket URL に進みます

ESP-IDF バージョン切り替え後の必須手順

5.x（または別のバージョン）から v6.0.1 以降に切り替えた後は、依存関係とキャッシュを新しい SDK に合わせます。

# ESP-IDF ディレクトリでサブモジュールを更新
cd <esp-idf ディレクトリ>
git submodule update --init --recursive

続いて、そのディレクトリの export.sh を再読み込みし（Windows では対応する ESP-IDF PowerShell 環境を使用）、小智プロジェクトのディレクトリに戻って次を実行します。

idf.py fullclean
idf.py build

よくある問題

1. ビルドを速くする

  • ウイルス対策ソフト（Windows Defender を含む）を無効にします
  • build フォルダを削除して再ビルドします

2. シリアルドライバの問題

シリアルポートが認識されない場合は、チップに対応する USB ドライバをインストールしてください。

3. I2C の競合

I2C の競合が発生した場合：

  1. idf.py menuconfig を実行します
  2. Component config -> Audio Codec Device Configuration を選択します
  3. 最初のオプションを無効にします
  4. 再ビルドします

4. エラー：project depends on idf (>=6.0.1)

次のようなエラーが出た場合：

ERROR: Because project depends on idf (>=6.0.1) which doesn't match any versions, version solving failed.

現在の環境の ESP-IDF が古すぎます（例：5.x）。プロジェクトは main/idf_component.yml で idf: '>=6.0.1' を宣言しています。ESP-IDF v6.0.1 以降（release/v6.1 ブランチ推奨）をインストールし、ターミナルが新しい環境を読み込んでいることを確認してから再実行してください。

idf.py set-target esp32s3
idf.py build

5. ESP32-C3 で Wi-Fi の初期化に失敗する

v6.1 リリースタグを使用していて ESP32-C3 で Wi-Fi の初期化に失敗する場合は、release/v6.1 ブランチに切り替えてください。issue #2344 を参照してください。

6. Windows：コマンドラインが長すぎる

Ninja が CreateProcess エラー（コンパイラのコマンドが 32,767 文字の上限を超える）を報告する場合は、同じプロジェクトディレクトリ・同じ ESP-IDF ターミナルで次を実行します。

idf.py -D CMAKE_NINJA_FORCE_RESPONSE_FILE=ON reconfigure
idf.py build

idf.py fullclean や CMake キャッシュの削除後は、reconfigure を再度実行する必要があります。プロジェクトを短いパス（例：E:\xz）に移動すると改善することもあります。issue #2340 の回避策 を参照してください。

注意事項

  1. プロジェクトのパスに日本語や中国語を含めないでください
  2. プロジェクトを移動するときは build フォルダを削除してください
  3. 正しいチップ型番が設定されていることを確認してください
  4. ビルドの問題を避けるため、build ディレクトリを定期的に整理してください

関連ドキュメント

WebSocket通信プロトコル