esp-idf

ESP-IDF ファームウェアエンジニアリング

使用する場面

• ESP-IDF ファームウェアアプリケーションを開発または設定するとき。
• ESP-IDF プロジェクトのコンパイルエラーや依存関係の問題をトラブルシューティングするとき。
• 許可されたハードウェアに書き込み、実行時の動作を検証するとき。
• デコードされたモニター出力を使用して、実行時のクラッシュをデバッグするとき。

プロジェクトと環境

1. 最上位の CMakeLists.txt があるプロジェクトルートを特定します。 複数のアプリケーションを含むリポジトリでは、影響を受けるすべてのプロジェクトルートを特定します。
2. README、CI 設定、sdkconfig.defaults*、マニフェスト、ビルドスクリプトを確認し、必要な ESP-IDF のバージョン、ターゲット、検証方法を特定します。
3. プロジェクトを作成する場合は、スキャフォールドファイルを手動で生成せず、idf.py create-project <PROJECT_NAME> を使用します。
4. idf.py --version で環境を確認します。リポジトリで指定されているセットアップを優先し、指定がない場合は EIM を使用します。
   • eim --version
   • eim list でインストール済みバージョン、選択中のバージョン、絶対パスを確認します
   • eim select <ESP_IDF_VERSION>
   • eim run "idf.py --version" <ESP_IDF_VERSION>
   • eim run "idf.py <command>" <ESP_IDF_VERSION>
   • インストールが許可されている場合に限り、eim install -i <ESP_IDF_VERSION> を実行します
   • 対話形式でのインストールを求められた場合に限り、eim wizard を実行します
5. EIM が利用できなくても、必要な ESP-IDF 環境がすでに有効であれば、その環境で作業を続けます。EIM のインストールだけを理由に作業を止めないでください。
6. バージョンに対応した ESP-IDF ドキュメントと移行ガイドを使用します。

ターゲットとハードウェアの特定

• ハードウェアを調査する前に、設定とビルド出力からプロジェクトのターゲットを特定します。
• idf.py set-target <TARGET> を実行する前に確認を求めます。このコマンドは build/ を削除し、sdkconfig を sdkconfig.old に移動してプロジェクトを再設定するため、その後に重複して fullclean を実行しないでください。
• タスクで必要かつポートが確認できている場合に限り、ハードウェアを調査します。インストール済みの esptool のヘルプを確認し、次の例のように、対応している構文を使用します。
  • 現行：esptool --port <PORT> chip-id
  • レガシー：esptool.py --port <PORT> chip_id
• ブートローダーへの自動移行に失敗した場合は、再試行する前にデバイスをダウンロードモードにするようユーザーに依頼します。
• 設定されたターゲットを、実際のチップ、起動時のフラッシュ設定、アプリケーションのメタデータと照合します。必要がない限り、デバイスの MAC アドレスを報告しないでください。

ビルドと設定

• 通常のインクリメンタルビルドには idf.py build を使用します。ビルドに失敗した場合は、最初に該当するエラーと、参照されているログを確認します。
• sdkconfig は生成ファイルとして扱います。意図したデフォルト値は sdkconfig.defaults* に設定します。ターゲット固有のデフォルトファイルを使用するには、ベースとなる sdkconfig.defaults が必要です。ベースファイルが空でも必要です。
• Kconfig または Kconfig.projbuild を変更した後は、idf.py reconfigure を実行するか確認を求めます。通常、ビルド時に Kconfig 定義の変更は検出されますが、変更されたデフォルト値は、すでに sdkconfig に保存されている値を上書きしない場合があります。
• build/、managed_components/、dependencies.lock を手動で編集しないでください。
• idf.py fullclean は、ビルドの古い状態による問題が実証され、ユーザーの承認を得た場合に限り使用します。

フラッシュ、モニター、診断

• ボードが接続されているという理由だけでフラッシュしてはいけません。フラッシュは、要求された場合、またはポートとターゲットを確認し、デバイスを上書きしても安全であることを確認したうえで明示的に許可された場合に限ります。
• idf.py -p <PORT> flash でフラッシュします。実行時の検証が許可されている場合は、idf.py -p <PORT> flash monitor を使用します。
• クラッシュを分析する場合は idf.py -p <PORT> monitor を使用し、バックトレース内のアドレスがソースの位置にデコードされるようにします。
• 要求された動作またはクラッシュが発生するまで出力を取得し、モニターを正常に停止して、関連する証拠を要約します。
• ファームウェアがコンソールを公開しており、ターミナルが入力に対応している場合に限り、対話型の入力を送信します。
• サポートされていないエスケープシーケンスに関する linenoise の警告は無害なものとして扱います。この警告はファームウェアの動作ではなく、行編集と履歴を無効にするものです。
• メモリ破損またはメモリリークが疑われる場合は、まず利用可能な証拠を調べます。その後、適切なヒープトレースまたはデバッグ設定を提案し、設定を変更する前に許可を得ます。

ESP-IDF のコード規約

• エントリーポイントは void app_main(void) のままにします。
• 場当たり的なプラットフォームコードよりも ESP-IDF の API とインクルードを優先します。
• 必要な場合を除き、過度な printf の代わりに ESP_LOGI/W/E を使用します。
• idf_component_register(...) でコンポーネントを登録し、REQUIRES または PRIV_REQUIRES で依存関係を宣言します。
• esp_err_t の結果を明示的に処理し、適切な場合は、譲歩せずに長時間ブロックする処理を避けます。

コンポーネントレジストリ

• 依存関係をローカルで実装する前に、ESP Component Registry を検索します。
• 利用可能な場合は Registry MCP ツールを優先し、代替手段として公開 REST API を使用します。
• プロジェクトのルートから idf.py add-dependency "namespace/component^<VERSION>" で依存関係を追加します。依存関係が main 以外のコンポーネントに属する場合は、--component=<NAME> または --path=<PATH> を使用します。
• 要求を満たす候補が複数ある場合は、互換性、メンテナンス状況、ライセンス、API との適合性を比較します。選択が重要な点で決まらない場合に限り、ユーザーに確認します。
• REST エンドポイントと例については、component_registry.md を参照してください。

引き継ぎ

• 実行したコマンド、ESP-IDF のバージョン、ターゲット、テスト、使用したハードウェアを報告します。
• 設定変更を要約し、検証されていない項目があれば明確に示します。