ESP32 ファームウェア（PlatformIO：Arduino 優先、必要に応じて ESP-IDF）

コード規約、アーキテクチャ、単体テスト、一般的なデバッグについては embedded-c-cpp も併せて読み込んでください。このスキルは ESP32 固有の部分を担当します。

最初に、プロジェクトを特定する

確認項目	確認場所	重要な理由
正確なチップとモジュール（ESP32-WROOM-32E、ESP32-S3-WROOM-1-N16R8、ESP32-C3-MINI-1...）	`platformio.ini` の `board =`、ユーザー、基板シルクスクリーン	コア、ピン、PSRAM、USB、ADC はバリアント間で大きく異なります
フレームワーク	`framework = arduino`、`espidf`、または `arduino, espidf`	API と設定モデル
Arduino core バージョン（2.x または 3.x）	ビルドログの行 `framework-arduinoespressif32 @ x.y.z`、`platform =` 行、または `ESP_ARDUINO_VERSION_MAJOR`	いくつかの API が 3.x で変更されました（LEDC、タイマー） — 間違ったバージョン向けに書かれたコードはコンパイルできません
フラッシュ / PSRAM サイズ	モジュール名（N16R8 = 16 MB フラッシュ、8 MB オクタル PSRAM）、`board_upload.flash_size`	パーティション、メモリ配置
基板配線	ユーザー/回路図	ストラップピン、フラッシュ/PSRAM/USB/LED で使用されるピンを避ける

バリアントが不明で、タスクがピン、ペリフェラル、電源、メモリに影響する場合は、コードを書く前に確認してください — S3 で問題ないピンでも、クラシック ESP32 では起動しなくなる可能性があります。

Arduino か、ESP-IDF か？

Arduino（デフォルト）に留める	ESP-IDF（PlatformIO では `framework = espidf`）または Arduino + IDF（`framework = arduino, espidf`）に移行する
プロトタイプとほとんどの製品	Arduino のプリコンパイル済みコアが公開しない `sdkconfig` オプション（ロールバック OTA、セキュアブート、フラッシュ暗号化、PM 自動ライトスリープ、コアダンプ-to-フラッシュ、FreeRTOS 設定）を変更する必要がある場合
多くのライブラリが利用可能	最新の IDF 機能、メモリ/パフォーマンスの厳密な制御
高速なイテレーション	プロダクションの堅牢化

ESP32 上の Arduino は既に FreeRTOS + ESP-IDF 上で動作しているため、IDF API（esp_*、xTaskCreatePinnedToCore、nvs_*、esp_sleep_*、heap_caps_*）は Arduino コードから使用できます。「Arduino as IDF component」（arduino, espidf）は Arduino ライブラリを維持しつつ sdkconfig の制御を追加します — これが一般的な移行パスです。

セットアップ、platformio.ini テンプレート、2.x と 3.x の API 変更点：references/platformio-setup.md を参照してください。

典型的な ESP32 の失敗を防ぐルール

ピン：フラッシュピン（ESP32 の GPIO6–11）、PSRAM ピン（WROVER の 16/17、S3 オクタル PSRAM モジュールの 33–37）、USB 使用時の USB ピンは決して使用しないでください。ストラップピン（ESP32：0、2、5、12、15）は「注意して使用」として扱ってください — 起動時に GPIO12 がハイになっていると、3.3V フラッシュモジュールは起動に失敗します。ADC2 は Wi-Fi オン時には動作しません（クラシック ESP32）：ADC1 ピンを使用してください。各バリアントの完全なテーブル：references/pins-and-variants.md。
loop() やタスクを永久にブロックしない：delay() / vTaskDelay() なしの長い while ループはタスクウォッチドッグをトリガーします。while (WiFi.status() != WL_CONNECTED) にはタイムアウトが必要です。
ISR：IRAM_ATTR を付け、極めて小さく保ち、Serial.print、delay、Wi-Fi 呼び出しを行わないでください。処理はタスクに委譲してください（キュー / タスク通知 / フラグ）。共有変数には volatile + クリティカルセクション（portENTER_CRITICAL_ISR スピンロック — ESP32 はデュアルコアです）。
タスクスタックはバイト単位（ESP-IDF/Arduino では、標準 FreeRTOS のワード単位とは異なります）。uxTaskGetStackHighWaterMark(NULL)（バイト単位）で測定します。Arduino の loop() はデフォルトで 8 KB です（変更するには SET_LOOP_TASK_STACK_SIZE(16 * 1024);）。
電源供給：Wi-Fi TX は約 300～500 mA のピーク電流を消費します。「ブラウンアウト検出器がトリガーされました」は電源（レギュレーター、バルクコンデンサ、ケーブル）を修正する必要があることを意味します — ブラウンアウト検出器を無効にしないでください。
ヒープ：ループ内での String 連結、頻繁な new / malloc（時間経過による断片化）を避け、事前割り当てを行ってください。ESP.getFreeHeap() / heap_caps_get_minimum_free_size(MALLOC_CAP_8BIT) を時間経過で確認してください。
NVS/フラッシュの摩耗：Preferences / NVS への書き込みをループイテレーションごとに行わないでください。変更時、レート制限付きで書き込んでください。
不可逆操作：eFuse の焼き付け、セキュアブート、リリースモードでのフラッシュ暗号化は永続的です。明示的なユーザー確認なしに、espefuse.py burn_* の実行、sdkconfig でのこれらオプションの有効化、データが存在するデバイスへの erase_flash を絶対に行わないでください。

ビルド、アップロード、モニター（PlatformIO）

pio run -e <env>                       # ビルド
pio run -e <env> -t upload             # USB/シリアル経由でフラッシュ
pio device monitor -e <env>            # シリアルモニター（monitor_speed / monitor_filters を使用）
pio run -e <env> -t upload -t monitor  # 両方
pio run -e <env> -t uploadfs           # data/ フォルダを LittleFS/SPIFFS イメージとしてアップロード
pio run -e <env> -t erase              # フラッシュ全体を消去（最初に確認：NVS/WiFi 認証情報が消去されます）
pio run -e <env> -t menuconfig         # ESP-IDF / arduino+espidf のみ
pio test -e native                     # ホスト単体テスト（embedded-c-cpp を参照）

アップロードに失敗し「Failed to connect / Wrong boot mode detected」と表示された場合 → BOOT（GPIO0 / C3 では GPIO9）を押しながら EN/RST をタップし、BOOT を離します。ケーブルがデータ転送に対応しているか確認し、ポートを占有している他のシリアルモニターを閉じてください。アップロード前に基板が接続され、ポートが正しいことを確認してください（pio device list）。

クラッシュまたはリセットが発生した場合

貼り付け可能なシリアル出力が重要な証拠です。monitor_filters = esp32_exception_decoder と build_type = debug を有効にして、バックトレースがファイル:行にデコードされるようにしてください。その後、references/panics-and-debug.md を参照してください：Guru Meditation の種類（LoadProhibited、StoreProhibited、IllegalInstruction、RISC-V の Load/Store アクセスフォルト）、スタックカナリア、タスク/割り込みウォッチドッグ、rst: コード、ブラウンアウト、ブートループ、JTAG デバッグ（S3/C3/C6 では debug_tool = esp-builtin）について。

リファレンスファイル

ファイル	いつ読むか
`references/platformio-setup.md`	`platformio.ini` の作成/修正、プラットフォーム/core バージョンの選択、Arduino 2.x→3.x API 変更点、PSRAM、USB-CDC シリアル、パーティションとファイルシステム、PlatformIO での ESP-IDF 使用、sdkconfig
`references/pins-and-variants.md`	ピンの選択またはレビュー、ESP32/S2/S3/C3/C6 の比較、ADC、タッチ、ディープスリープ起床ピン
`references/rtos-memory-power.md`	タスク、コア、ISR、キュー、ウォッチドッグ、スタック/ヒープ/PSRAM、IRAM、ディープ/ライトスリープ、バッテリー
`references/panics-and-debug.md`	クラッシュ、リセット、ウォッチドッグ、ブラウンアウト、ブートループ、アップロード失敗、JTAG デバッグ、コアダンプ、リセット理由
`references/connectivity-ota-security.md`	Wi-Fi/BLE の堅牢性、NVS/Preferences、OTA アップデートとロールバック、セキュアブート / フラッシュ暗号化の判断

ESP32 ファームウェア