02. PlatformIO のセットアップとビルド・書き込みの仕組み

PlatformIO ってなに

• マイコン用の開発ツールキット。VS Code 拡張や CLI として使える
• やってくれることをざっくり3つ：
  1. ライブラリの自動ダウンロード（npm の package.json みたいなもの）
  2. クロスコンパイル（Mac の CPU 用ではなく、ESP32-S3 用の機械語を作る）
  3. 書き込み（できた .bin を USB 経由で CoreS3 のフラッシュに焼く）

代わりになるものとして「Arduino IDE」「ESP-IDF」があるが、PlatformIO は CI/CD やバージョン管理と相性が良いのでこのプロジェクトでは PlatformIO を採用。

---

インストール

brew install platformio

成功すると pio コマンドが使えるようになる。

pio --version
# PlatformIO Core, version 6.x.x

---

プロジェクト構成（このリポジトリの firmware/）

firmware/
├── platformio.ini    # 設定ファイル（ボード種類・ライブラリ依存）
├── src/
│   └── main.cpp      # エントリポイント（setup() と loop()）
├── include/          # ヘッダファイル置き場
├── lib/              # プロジェクトローカルなライブラリ
└── test/             # PlatformIO Unity テスト

platformio.ini の主要項目

[env:m5stack-cores3]
platform = espressif32@^6.7.0   # ← ESP32 ファミリーのビルド環境
board = m5stack-cores3          # ← ターゲットボード（型番）
framework = arduino             # ← Arduino API を使う

monitor_speed = 115200          # ← シリアル通信のボーレート
upload_speed = 921600           # ← 書き込み時の通信速度

lib_deps =                      # ← 依存ライブラリ
  m5stack/M5Unified@^0.2.5      # ← レジストリ名@バージョン
  https://github.com/...        # ← GitHub から直接でも可

---

ビルド・書き込みの全体像

[src/main.cpp]
      │
      │ ① コンパイル (PlatformIO → xtensa-esp32s3-gcc)
      ▼
[firmware.elf] ← ESP32-S3 向け機械語
      │
      │ ② esptool が .bin 形式に変換
      ▼
[firmware.bin]
      │
      │ ③ USB 経由で CoreS3 のフラッシュメモリに書き込み
      ▼
[CoreS3 のフラッシュ 0x10000 番地〜]
      │
      │ ④ リセット
      ▼
  プログラム起動

コマンド対応表

やりたいこと	コマンド
依存ライブラリだけインストール	pio pkg install
ビルドのみ	pio run
ビルド＋書き込み	pio run -t upload
書き込み先ポート指定	pio run -t upload --upload-port /dev/cu.usbmodem83301
シリアル出力を見る	pio device monitor
ビルド成果物の掃除	pio run -t clean

---

このリポジトリ特有の注意

⚠️ macOS では DYLD_LIBRARY_PATH の workaround が必要

詳しくは troubleshooting/macos-libexpat.md を参照。

簡易版：

export DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib
pio run -t upload

を .zshrc に入れておくか、Makefile を作る。

サーボライブラリは ESP32 対応のものを使う

元の platformio.ini には netlabtoolkit/VarSpeedServo が書いてあったが、これは Arduino Uno 等の AVR チップ専用 で ESP32 ではビルドできない。

詳しくは troubleshooting/varspeedservo-esp32.md。

候補：

• madhephaestus/ESP32Servo（標準的、簡単）
• ArminJo/ServoEasing（イージング付き、表現力豊か）

---

トラブル時の最初の3手

1. .pio/ ディレクトリを削除して pio run を再実行（ビルドキャッシュ汚染の解消）
2. pio pkg update でライブラリ更新
3. pio device list でシリアルポートが認識されているか確認