ESP32 開発トラブルシューティング

このページは、症状別に調査の入口を整理したものです。どの提案も、ファームウェアのソース、上流のドキュメント、またはサイト内で確認済みのページに基づいています。根拠のない経験則は載せていません。使い方に関する問題（ネットワーク設定、アクティベーション、バインド）は、まず初回起動とよくある質問を参照してください。

1. ビルドと環境

症状	確認すること	対処
ESP-IDF 関連のエラーでビルドが失敗する	`idf.py --version`	ファームウェアは ESP-IDF v6.0.1 以上が必須で、v6.1 を推奨します。IDF 5.x には対応していません。ESP-IDF 開発環境のセットアップを参照
ESP32-S31 のバリアントがビルドできない	IDF のバージョン	このチップのバリアントには ESP-IDF 6.1 以上が必要です。自分でビルドする場合は `release/v6.1` ブランチを推奨します
ボード名またはバリアント名が見つからない	名前のつづり	まず `python3 scripts/build.py --list-boards` で正確なボードディレクトリとバリアント名を確認し、`python3 scripts/build.py <ボードディレクトリ> --name <バリアント名>` でビルドします
ボード切り替え後に設定がおかしい	ローカルのビルド状態	`scripts/build.py` は `sdkconfig` とビルド状態を書き換えます。古いビルドディレクトリが以前のターゲットに対応していると考えず、スクリプトで再ビルドしてください
ボード定義が重複または不足している	`DECLARE_BOARD`	1 回のビルドでエクスポートする `DECLARE_BOARD(...)` はちょうど 1 つです。カスタムボードガイドを参照
生成ファイルを手で編集してから挙動がおかしい	`build/`、`managed_components/`、`sdkconfig*`、`main/assets/lang_config.h`	これらは生成物またはサードパーティ出力なので手で編集しないでください。元に戻して再ビルドします

2. 書き込み

ビルド済みファームウェアは、結合イメージをアドレス 0x0 に書き込みます。手順はファームウェアのダウンロードとインストールを参照してください。
書き込みや消去に失敗する場合は、ボードをブレッドボードから外し、単独でパソコンに接続してからやり直してください。
シリアルポート名は OS によって異なります。Linux では /dev/ttyACM0 または /dev/ttyUSB0、macOS では /dev/cu.usbmodem*、Windows では COMx が一般的です。必要に応じて -p <ポート> で指定してください。
一部のボードには専用のフラッシュパラメータの説明があります。上流リポジトリの、そのボードのディレクトリにある README を参照してください。

3. 音が出ない、録音できない

次の順に確認してください。

配線：ハードウェア構築ガイドのピン表と 1 本ずつ照合し、電源を入れる前にテスターで GND と 3.3V の間がショートしていないことを確認します。
ボードの宣言：ボードの config.h にあるマイクのチャンネル宣言（M または MR）は、コーデックが返すインターリーブ PCM と一致している必要があります。R チャンネルは再生リファレンスにだけ使え、2 本目のマイクとしては使えません（上流の main/audio/README.md を参照）。
I2S モード：Simplex と Duplex ではピンが異なります。どちらかに切り替えるときは、config.h のピン定義も合わせて変更してください。
サンプルレート：多くのボード設定は入力 16 kHz、出力 24 kHz です。カスタムボードはコーデックに合わせる必要があります。

Audio Debugger で音声を取得する

ファームウェアは、収音したオーディオを UDP でパソコンに送れます。問題が収音にあるのか、その後の段階にあるのかを切り分けられます。

menuconfig で USE_AUDIO_DEBUGGER を有効にし（既定ではオフ）、AUDIO_DEBUG_UDP_SERVER をパソコンの IP:ポート に設定します（既定は 192.168.2.100:8000）。
パソコンで上流のスクリプトを実行します。UDP の 8000 番ポートで待ち受け、WAV ファイルに書き出します。

python3 scripts/audio_debug_server.py --samplerate 16000 --channels 2

--samplerate の既定は 16000、--channels の既定は 2 です。取得するデータの形式と一致させてください。

4. ウェイクしない

PSRAM のないボード：ローカルのウェイクワードは既定で無効です。ボタンで会話するか、外付けのウェイクアップモジュールを使います。ESP32 エコノミー版を参照してください。
チップが合っていない：AFE ウェイクワードと MultiNet のカスタムウェイクワードは、PSRAM 付きの ESP32-S3 / P4 / S31 だけが対象です。C3、C5、C6、PSRAM 付きの ESP32 は AFE なしの WakeNet を使います。チップ対応とストレージ仕様を参照してください。
カスタムウェイクワードの感度が低い：CUSTOM_WAKE_WORD_THRESHOLD の範囲は 1〜99 で、値が小さいほど敏感になります（既定 20）。中国語のウェイクワードは、スペース区切りのピンインで書く必要があります。
Assets のウェイクワードモデル：カスタム Assets ガイドのチェックサムとバージョンに関する注意を参照してください。

5. ネットワーク、アクティベーション、アップグレード

ネットワーク設定とアクティベーションの問題は、初回起動とネットワーク設定を参照してください。/activate が 202 を返したとき、デバイスは待機して再試行します。これは故障ではありません。
バージョン確認に失敗した場合、デバイスは再試行間隔の後にもう一度確認します。手動で再起動する必要はありません。
自前でサーバーを運用している場合は、WebSocket 通信プロトコルと MQTT + UDP ハイブリッドプロトコルに照らして、ハンドシェイクとメッセージ形式を確認してください。

6. assets リソースの問題

ログ	意味
`No assets partition found` / `Assets partition is disabled`	パーティションテーブルに `assets` パーティションがない
チェックサム不一致	`assets.bin` が壊れている、または書き込みオフセットが違う
`The assets version N is not supported, please upgrade the firmware`	インデックスのバージョンが、ファームウェアの対応バージョンより新しい
`Assets file size ... is larger than partition size`	ファイルがパーティションサイズを超えている

対処方法はカスタム Assets ガイドを参照してください。

7. 問題を報告するときに記載する内容

ファームウェアのバージョン、ボードディレクトリとバリアント名（例：bread-compact-wifi）、チップの型番
ESP-IDF のバージョン（idf.py --version の出力）
起動からエラーまでの完全なシリアルログ
再現手順と、実機で検証したかどうか

ファームウェアの問題は、上流の GitHub Issues に報告してください。