xiao-esp32s3

arduino-cli を使用した XIAO ESP32S3（Windows）

以下はすべて、実機（esp32 core 3.3.10、2026-07）で検証済みです。 記載どおりに進めれば、トラブルシューティングは不要です。

以下のパスは、このスキルのフォルダーからの相対パスです。<PORT> はボードの COM ポート、<SKETCH_DIR> はユーザーのワークスペース内のスケッチフォルダーです。

初回セットアップ（すでに満たしている手順はスキップしてください）

arduino-cli version                          # confirm arduino-cli exists
arduino-cli core list                        # is esp32:esp32 3.x installed?
# if not (this downloads ~1 GB and can take several minutes — use a long timeout):
arduino-cli core update-index
arduino-cli core install esp32:esp32

ボードの確認

arduino-cli board list

XIAO は通常、識別されていない「Serial Port (USB)」として表示されます。その行のポート（例：COM4）が <PORT> です。ポートが表示されない場合、ボードがディープスリープ状態にある可能性があります（ポートは起動中のみ存在します。落とし穴 2 を参照）。または、ブートローダーモードにする必要があります（USB を接続する間、BOOT ボタンを押したままにします。ポート番号が変わることがあります）。

標準的なワークフロー

# sketch layout rule: folder name and .ino name must match:  my_sketch\my_sketch.ino

# compile (first compile of a session takes 1-3 min; cached after)
arduino-cli compile --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>

# upload
arduino-cli upload -p <PORT> --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>

# read serial for 10 s (NEVER `arduino-cli monitor` — it blocks forever)
powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10

# optional: send a line to the board and read the response
powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10 -Send "hello"

PowerShell 5.1 では && を使用できません。; または if ($?) { ... } で連結してください。

検証済みのサンプルスケッチ

assets/sketches/ には、実機でコンパイル、アップロード、実行できたスケッチが 11 個あります。ゼロから作成するのではなく、最も近いものをユーザーのワークスペースにコピーして、出発点として使用してください。各スケッチで確認できる内容と想定される出力については、references/examples.md を参照してください。

バグを防ぐスケッチのルール

• 最初の出力の前に Serial.begin(115200); を実行し、その後 delay(3000); を入れてください。USB CDC の列挙には時間が必要です。そうしないと、初期の出力が気づかれないまま失われます。
• ユーザー LED は LED_BUILTIN（GPIO21）で、反転されています。LOW = オン、HIGH = オフです。analogWrite(LED_BUILTIN, 0) = 最大輝度です。
• ADC：analogReadResolution(12) を呼び出してください。生の値は analogRead(A0)、ミリボルト値は analogReadMilliVolts(A0) で読み取ります。未接続のピンでは、生の値として 60～160 程度のノイズが読み取られます。これは正常であり、バグではありません。
• タッチ：touchRead(T2)（T2 = GPIO2 = ピン D1）。基準値は約 17,500 です。タッチすると、値は 40,000 を大きく超えて上昇します（従来の ESP32 とは逆です）。
• WiFi.macAddress() は、WiFi.mode(WIFI_STA) で WiFi を開始するまで 00:00:00:00:00:00 を返します。これはエラーではありません。
• core 3.x でのネットワーク通信には、NetworkClient / NetworkServer を使用してください（従来の WiFiClient / WiFiServer という名前は存在しない場合があります）。

ピン配置（XIAO ESP32S3）

ラベル	GPIO	備考
D0	1	A0、タッチ T1
D1	2	A1、タッチ T2
D2	3	A2、タッチ T3
D3	4	A3、タッチ T4
D4	5	SDA、タッチ T5
D5	6	SCL、タッチ T6
D6	43	UART TX（Serial1）
D7	44	UART RX（Serial1）
D8	7	SPI SCK
D9	8	SPI MISO
D10	9	SPI MOSI
ユーザー LED	21	反転（LOW = オン）

既知の落とし穴 — 「デバッグ」する前にお読みください

1. COM ポートを開くとボードがリセットされます（DTR の切り替え → rst:0x15 USB_UART_CHIP_RESET）。シリアルを読み取るたびに、新しいブートから始まります。 これにより RTC_DATA_ATTR 変数も消去されるため、シリアルモニターでは ディープスリープのブート回数を確認できません。クラッシュではありません。
2. ディープスリープ中は COM ポートが消えます。 スリープ中は USB CDC の電源が 切れるため、ポートが消え、Windows ではサイクルごとに切断・接続音が鳴ります。 これは正常で、スリープが機能している正しい証拠です。 ポートを開く代わりに、scripts\watch_port.ps1 -Port <PORT> を使ってサイクルを 確認してください（出現・消失のタイムスタンプが記録されます）。スリープ中の ボードに再書き込みするには、短い起動時間を捉えるか、USB を接続する際に BOOT ボタンを押し続けてください（ブートローダーモード。ポート番号が変わる 場合があります）。
3. arduino-cli monitor は終了しません。 自動化されたセッションではシェルが ハングします。必ず、タイムアウトが設定された scripts\read_serial.ps1 を 使用してください。
4. デフォルトでは PSRAM の読み取り値は 0 バイトです。 デフォルトのビルドでは PSRAM が無効になっています。スケッチで PSRAM が必要な場合（カメラ、大きな バッファー）は、コンパイルとアップロードの両方のコマンドに --board-options PSRAM=opi を追加してください。
5. netsh wlan show networks はキャッシュされた情報を表示するため、 ボードが 作成したばかりの SoftAP が表示されない場合があります。ボードのシリアル出力 （「AP IP address: 192.168.4.1」）を信頼し、代わりにスマートフォンから AP を テストしてください。
6. アップロードに失敗する／ポートが使用中の場合：シリアル読み取りプロセスが まだ実行されていないことを確認してください（ポートを保持できるプロセスは 1 つだけです）。ボードがブリックしたように見える場合は、ブートローダーモードを 使用してください（落とし穴 2）。
7. 初回のコンパイルには時間がかかります（キャッシュが空で、ツールチェーンが 大規模です）。約 3 分が経過する前に終了させず、十分に長いタイムアウトを 設定してください。
8. シリアルセッション後、ボードがリセット状態から復帰できなくなる場合が あります（ROM のバナー ESP-ROM:esp32s3-... だけが表示され、アプリが 起動せず、SoftAP／サーバーが停止します）。 原因は、ポートを閉じたときに PC が DTR／RTS の信号状態を残すことです。 arduino-cli upload で復旧してください（esptool のリセットシーケンスで 解決します）。ヘッドレスのデモ（Web サーバーなど）を動作させ続ける必要が ある場合は、シリアルポートを開かないでください。シリアルで IP アドレスを 読み取る代わりに、mDNS またはルーターの DHCP テーブルでボードを 確認してください。
9. 同じ名前の Edge Impulse ライブラリーを置き換える場合は --clean が 必要です。 <project>_inferencing ライブラリーを再ビルドしたコピー （同じバージョン）で置き換えても、arduino-cli のキャッシュに古いオブジェクトが 残ります。症状として、リンク時に objs.a ... is not an object エラーが発生したり、編集が反映されなかったりします。ライブラリーを 置き換えた後の初回コンパイルでは、必ず --clean を渡してください。

人の目を使わずに検証する

• LED／PWM：動作をログで証明できるよう、各サイクルで状態もシリアルに出力します。
• WiFi スキャン／BLE スキャン：成功すると、ネットワーク／デバイスの番号付き リストが表示されます。
• SoftAP：成功すると、シリアルに AP の IP アドレスが出力されます。HTTP の 完全なテストにはスマートフォンが必要です。
• ディープスリープ：成功すると、watch_port.ps1 に、設定したスリープ時間 （＋約 3 秒の起動時間）に一致する安定した消失・再出現サイクルが表示されます。