firmware-build

name	firmware-build
description	arduino-cli でファームをビルド／書き込みする。ボード設定、ライブラリのバージョン固定、書き込み時の注意をまとめてある。ファームを触ったあと、実機で確かめる前に使う。

ファームのビルドと書き込み

このプロジェクトは arduino-cli で開発する（Arduino IDE の GUI は使わない）。

ビルド

uv run python tools/check.py compile

中身は次のコマンド。--build-path を固定しているのでキャッシュが効く （初回 ~110 秒、以降 ~10 秒）。

arduino-cli compile --fqbn m5stack:esp32:m5stack_core2 \
  --build-path build/arduino firmware/core2-deck

• スケッチは firmware/core2-deck/core2-deck.ino。 arduino-cli はフォルダ名と .ino 名の一致を要求するのでこの構成になっている。
• src/ 配下は再帰的にコンパイルされる。src/ 以外のサブフォルダは コンパイルされない。新しいソースは必ず src/core/ か src/platform/ に置く。
• ボードオプションは既定のまま使う（PSRAM=enabled, FlashSize=16M, PartitionScheme=default, CPUFreq=240）。変える場合は --fqbn に :PSRAM=enabled,PartitionScheme=... の形で付け、README にも記録する。

書き込み

書き込みは勝手にやらない。 ポートを占有し、実機の状態を変える。 ユーザーが明示的に頼んだときだけ実行する。

# ポートは環境依存。まず uv run python tools/deck.py list で確認する
#   Windows: COM9 など / macOS: /dev/cu.usbserial-XXXX / Linux: /dev/ttyUSB0
arduino-cli upload -p "$PORT" --fqbn m5stack:esp32:m5stack_core2 \
  --input-dir build/arduino firmware/core2-deck

ポート番号は uv run python tools/deck.py list で確認する（CP210x = VID 10C4 が Core2）。書き込み中は deck.py も arduino-cli monitor も使えない。

シリアルモニタ

arduino-cli monitor -p "$PORT" -c baudrate=115200

対話的でブロックするので、エージェントから使うときは注意。tools/deck.py と ポートを取り合うので、両方を同時に開かないこと。プロトコルの確認は モニタではなく deck.py を使うほうが確実。

ライブラリ

インストール済みのバージョンは arduino-cli lib list で確認できる。 バージョンを上げたら必ずビルドと実機動作を確認し、README に記録する （仕様 §8/§14）。特に BLE HID 系のライブラリは ESP32 コアのバージョンに敏感で、 「たぶん動く」で決めてはいけない組み合わせが実在する。

新しいライブラリを入れるとき:

arduino-cli lib search <name>
arduino-cli lib install "<name>@<version>"   # バージョンを明示して入れる

入れたら README の表を更新する。

失敗したとき

• undefined reference — src/ の外にソースを置いていないか確認する。
• ヘッダが見つからない — ライブラリ未インストール。arduino-cli lib list を見る。
• 挙動が変なのにビルドは通る — build/ を消してクリーンビルドを試す。
• コンパイル自体が謎に壊れた — arduino-cli cache clean。