esp32-development

ESP32 開発

ボード、接続された回路、ファームウェア、ホストのツールチェーンを一つのシステムとして扱います。ESP32 のタスクは、コンパイルや書き込みが成功しただけでなく、ハードウェアの境界で意図した動作が確認できたときにのみ完了です。

運用上の取り決め

1. 正確なボード、SoC ファミリー、モジュール、フラッシュ／PSRAM の容量、USB の通信方式、電源、ボードのリビジョンを特定します。ESP32、S2、S3、C2、C3、C5、C6、H2、P4 の各バリアント間でピン配置を流用しないでください。
2. ピンや電圧レベルを選ぶ前に、ボードの回路図またはピン配置、該当する SoC／モジュールのデータシート、接続するすべてのコンポーネントのデータシートを確認します。
3. ホストと USB の読み取り専用の検出から始めます。シリアルモニターを開くと DTR／RTS が切り替わり、ターゲットがリセットされることがあります。実行中の状態が重要な場合は、リセットしないオプションを使用します。
4. 製品の制約に基づいてフレームワークを一つ選びます。ラッパーを書く前に、そのフレームワークのプロジェクトジェネレーター、サンプル、ドライバー、ビルドシステム、フラッシャー、モニター、デバッガーを活用します。
5. 電源と起動、シリアルログ、単一の GPIO、単一のバス、バススキャンまたはループバック、デバイスの識別レジスター、生の読み取り値、キャリブレーション、アプリケーションの動作の順に、一度に一つのレイヤーを立ち上げます。
6. 操作の前に、ターゲット、作業範囲、ロールバック手順を確認します。読み取り専用の検出は確認なしで進めてもかまいません。最初の書き込みまたはハードウェアの変更の前に、ターゲットのポート、チップファミリー、イメージ／パーティションのレイアウト、ロールバックまたは再書き込みの手順、電気的安全性を確認します。フラッシュオフセットを推測してはいけません。
7. 実際のセンサー、クロック、ADC、PWM デバイス、アクチュエーターについては、キャリブレーションの調整手段を維持します。物理的なばらつきは想定されるものです。

回答前のエビデンス確認

実質的な計画や推奨事項の作成前に、次の確認を完了します。

1. 重要な肯定的主張、否定的主張、コマンド、数値による設計上の選択ごとに、主張台帳を作成します。source-index.md 内の URL はナビゲーション情報であり、エビデンスではありません。該当するチップまたは現行バージョンのページを取得するか、主張を UNKNOWN と記録します。
2. コマンドのヘルプで確認できるのは構文だけです。必要なターゲットの状態に加え、リセット、DTR／RTS、ダウンロードモード、RAM スタブ、ポート、変更による影響を、現行ドキュメントに基づいて記録します。操作上の前提条件が未検証の場合、そのコマンドを実行可能なものとして提示してはいけません。
3. 欠落しているハードウェア資料は、欠落したまま扱います。類型、例、「通常は」「典型的には」「一部のモジュールでは」といった言葉で補ってはいけません。確認できたラベルから何が特定できないのかを明記します。
4. しきい値、マージン、間隔、期間、測定点数、割合、モデル形式を捏造してはいけません。権威ある情報源または測定基準に基づいて導き出します。そうでない場合は UNKNOWN のままにします。
5. 最終回答を主張台帳と照合します。必要なエビデンスがない重要な主張はすべて削除するか、断定の度合いを下げます。

最初の読み取り専用検出

python3 scripts/esp32-preflight.py
python3 scripts/esp32-preflight.py --json
pio device list --json-output       # when PlatformIO is installed
mpremote connect list               # when mpremote is installed

プリフライトスクリプトはシリアルポートを開きません。USB ディスクリプターからブリッジやボードのファミリーを特定できる場合はありますが、チップがダウンロードモードであることや、ファームウェア固有のプロトコルが有効であることは確認できません。不明なボードを調べる前に、判断とプリフライトをお読みください。

パスを選択する

必要な情報	最初に読む資料
ボード、ホスト、ポート、トランスポート、またはフレームワークを特定する	判断事項と事前確認
安全なピン、電源、保護、プルアップ、またはレベルシフトを選ぶ	ハードウェアと電気的安全性
ESP-IDF、Arduino、MicroPython、CircuitPython、ESPHome、Zephyr、Rust、またはNuttXを選ぶ	ファームウェアフレームワーク
ネイティブCLIを使って作成、ビルド、書き込み、監視、テスト、またはデバッグする	ネイティブツールのワークフロー
GPIO、ADC、DAC、PWM、タッチ、I2C、SPI、UART、I2S、RMT、PCNT、TWAI/CAN、またはUSBを使う	ペリフェラルとバス
センサー、ディスプレイ、LED、リレー、モーター、サーボ、ソレノイド、またはその他の負荷を接続する	センサー、アクチュエーター、キャリブレーション
Wi-Fi、BLE、ESP-NOW、Zigbee/Thread、スリープ、OTA、または量産時の電源動作を追加する	接続性、電源、OTA
起動、書き込み、クラッシュ、ブラウンアウト、バス、ネットワーク、またはセキュリティ状態を診断する	デバッグ、復旧、セキュリティ
ターゲットテストを自動化する、テストベンチをセットアップする、障害を注入する、または制限付きフィードバックループを実行する	ハードウェアテストの自動化
コマンドやバージョンに依存する記述を更新する	ソースインデックス

最小限の初期セットアップ手順

1. templates/hardware-bringup.md に記入し、すべてのピンと電圧に関する判断の正確な出典を記録します。
2. scripts/esp32-preflight.py を実行してから、選択したフレームワーク独自のボード一覧とプロジェクトジェネレーターを使用します。
3. ハードウェアを接続せずにビルドします。ピン、パーティション、フラッシュ、またはセキュリティの動作に影響する警告をすべて解消します。
4. 電源とUSBだけを接続します。ペリフェラルを接続する前に、起動ログを取得します。
5. フレームワークが生成したオフセットとイメージメタデータを使用して、フレームワークのサンプルまたは生成した最小プロジェクトを書き込みます。
6. シリアル出力、リセット動作、チップの識別情報を確認します。その後、ペリフェラルまたは負荷を一つずつ追加します。
7. バスでは、ドライバーを導入する前に電気的アイドルレベルを確認し、スキャンまたはループバックを実行します。アクチュエーターでは、負荷を接続せずに制御信号をテストしてから、外部ドライバーと電源を使用します。
8. 要求された動作を、リセットと電源再投入のテストを繰り返して確認します。OTAが対象範囲に含まれる場合は、OTAに依存する前にロールバックまたはシリアル経由の復旧を実証します。

ハードウェア自動フィードバックループ

自動化が対象範囲に含まれる場合は、references/hardware-test-automation.md を読み、templates/hardware-test-plan.md に記入します。要件を独立した観測結果に結び付け、共有ハードウェアを確保し、ファームウェアを変更する前にテストフィクスチャをセットアップして、受け入れテストケースを確定します。ネイティブのテストフィクスチャは、セットアップ中にデバイスへの書き込みやリセットを行う場合があります。製品の不具合、フィクスチャのエラー、証拠の不足、合格を分けて記録し、すべての試行を保存します。危険な状態、識別情報または所有権の喪失、未確認のクリーンアップ、あるいは記録済みの予算上限に達した場合は停止します。ログやホスト側のテストスイートが成功しても、物理的な動作が実証されたことにはなりません。

テンプレートとヘルパー

• templates/hardware-bringup.md — ボード、電源、ピン、コンポーネント、復旧のためのワークシートです。
• templates/hardware-test-plan.md — 要件とテストの対応付け、試運転、故障注入、エビデンス、クリーンアップの記録です。
• templates/component-contract.md — データシートに基づくセンサーまたはアクチュエーターの統合記録です。
• templates/esp-idf-main.c — ピンを明示的に設定可能な、小規模な ESP-IDF GPIO タスクです。
• templates/platformio.ini — ボードとフレームワークを明示し、バージョン固定用のプレースホルダーを含む、最小限の PlatformIO 環境です。
• templates/micropython-i2c-scan.py — 設定可能な I2C の電気特性／識別プローブです。
• templates/esphome-device.yaml と templates/esphome-secrets.yaml.example — 外部シークレットと明示的なフレームワーク選択を使用する、安全な ESPHome の初期動作確認用設定です。
• templates/zephyr-esp32.overlay — 最小限のデバイスツリー GPIO／I2C オーバーレイのパターンです。
• scripts/esp32-preflight.py — 依存関係がなく、状態を変更しないホスト／ツール／ポート分類ツールです。決定的なチェックを実行するには --self-test を指定します。

厳守事項

• ESP32 の GPIO は、一般に 5 V 耐性がありません。正確なデータシート上の制限に従い、必要に応じてレベルシフターまたはドライバーを使用してください。
• モーター、リレー、ソレノイド、サーボ、大電流 LED、大容量負荷に GPIO から給電しないでください。定格に合ったドライバーと外部電源を使用し、必要に応じて共通基準を設け、誘導性負荷にはフライバック保護を施してください。
• GPIO 番号が常に安全だと考えないでください。ストラップ、フラッシュ／PSRAM、USB／JTAG、入力専用、ADC、ウェイクアップの制約は、チップ、モジュール、ボード、ブートモードによって異なります。
• トラブルシューティングの最初の手段として、一般的にフラッシュを消去しないでください。まず、ブートログ、イメージのメタデータ、パーティション、キャリブレーション／NVS への影響、復旧用アーティファクトを記録してください。
• セキュアブート、フラッシュ暗号化、eFuse、ダウンロードモードの制限は、元に戻せない場合があります。該当する SoC と ESP-IDF のセキュリティドキュメントを読み、本番環境へのプロビジョニング前に使い捨てのハードウェアで復旧手順を検証してください。
• Wi-Fi、API、OTA、署名に関するシークレットを、公開テンプレートやソース管理に決して含めないでください。

使用しない場合

このスキルだけを、PCB レイアウト認証、RF／アンテナ設計、商用電源電圧を扱う作業、機能安全認証、医療機器、または信頼できるデータシートが入手できないコンポーネントに使用しないでください。これらの作業は、適切な電気、RF、安全、またはコンプライアンスの専門分野に引き継いでください。ESP32 以外を対象とする場合は、そのプラットフォーム固有のスキルとツールを使用してください。

完了条件

対象と情報源が正確に記録されていること、電気的制限とピンの選択に根拠が示されていること、ネイティブのビルドツールとフラッシュツールが説明のつかないエラーなく完了すること、意図したイメージが起動したことをログで確認できること、各バスまたはデバイスの識別レベルのチェックに合格すること、物理的な境界でキャリブレーション済みの動作が確認されること、そしてリセット、電源再投入、復旧の動作が要求されたデプロイモードに一致すること。