🚀 セットアップガイド（複数端末対応）

新しい端末（Mac Studio / MacBook など）で実機デバッグ環境を 30 分で立ち上げる ためのフルセットアップ。

対象端末

• macOS Apple Silicon (M1/M2/M3/M4 / Apple Silicon Mac)
• Homebrew 導入済
• 同一 LAN 上の Wi-Fi に CoreS3 と Mac が繋がる前提

全体像

Mac (Mac Studio or MacBook)
  ├─ VOICEVOX engine (port 50021)            ← 日本語音声合成
  ├─ stackchan-bridge (port 7780)            ← WSS + Backend Router
  │   └─ Claude Agent SDK (サブスクモード)
  └─ PlatformIO (firmware ビルド・書き込み)

  USB-C ─→ M5Stack CoreS3 (StackChan K151)
                ├─ Module-LLM (KWS / STT 用)
                └─ I2S スピーカー (顔から声)

STEP 1 — リポジトリ & 開発ツール（5 分）

git clone https://github.com/aieo-product/aieo-stack-chan.git
cd aieo-stack-chan
brew install platformio sevenzip

macOS Tahoe での python@3.14 / libexpat 問題

PlatformIO 初回ビルド時に pyexpat: Symbol not found で失敗する場合があります。回避策:

echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib' >> ~/.zshrc
source ~/.zshrc

詳細は knowledge/troubleshooting/macos-libexpat を参照（過去対応済）。

STEP 2 — VOICEVOX エンジン（10 分・初回のみ）

満別花丸（Donack のボイス担当）を使うために VOICEVOX エンジンをインストール:

mkdir -p ~/Library/Application\ Support/voicevox-engine
cd ~/Library/Application\ Support/voicevox-engine

# 最新の macOS arm64 を取得 (0.25.2 時点・約 1.7GB)
curl -L "https://github.com/VOICEVOX/voicevox_engine/releases/download/0.25.2/voicevox_engine-macos-arm64-0.25.2.7z.001" -o engine.7z.001
7zz x engine.7z.001 -y

# 起動 (バックグラウンド常駐)
nohup ./macos-arm64/run --host 127.0.0.1 --port 50021 > /tmp/voicevox.log 2>&1 &
disown

起動確認:

curl -s http://127.0.0.1:50021/speakers | python3 -c "import json,sys; d=json.load(sys.stdin); print([s['name'] for s in d if '満別' in s['name']])"
# 期待: ['満別花丸']

自動起動 (option)

毎回手動で立てたくない場合、launchd plist を ~/Library/LaunchAgents/ に置く。 今後 mac-studio/launchd/com.voicevox.engine.plist として供給予定。

STEP 3 — Mac Studio bridge（5 分）

cd path/to/aieo-stack-chan/mac-studio/bridge
npm install --legacy-peer-deps

cp .env.example .env
# .env を編集:
#   PORT=7780
#   MCP_PORT=8787
#   STACKCHAN_PSK=               # LAN 開発なら空
#   DEFAULT_BACKEND=claude
#   VOICEVOX_BASE_URL=http://127.0.0.1:50021
#   VOICEVOX_SPEAKER_ID=69       # 満別花丸 ノーマル

# Claude Code サブスクモード使うなら ANTHROPIC_API_KEY は **設定しない**
# API キーを使うなら: ANTHROPIC_API_KEY=sk-ant-...

npm run start
# > [bridge] WSS listening on :7780/ws
# > [mcp] HTTP listening on :8787/mcp

別ターミナルで bridge の生存確認:

cd path/to/aieo-stack-chan/mac-studio/bridge
node test_ws.mjs    # Claude → VOICEVOX → PCM 一連を内側でテスト
afplay /tmp/test_tts.wav    # 生成された音声を再生

STEP 4 — firmware 書き込み（10 分）

CoreS3 を USB-C で Mac に接続:

ls /dev/cu.usbmodem*    # 例: /dev/cu.usbmodem83301

端末ごとの LAN IP を build flag で渡してビルド (firmware/include/stackchan_config.h は触らない):

cd path/to/aieo-stack-chan
MAC_IP=$(ipconfig getifaddr en0)   # Wi-Fi が en1 の端末は en1 に変更
echo "Mac IP: $MAC_IP"

DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib \
  PLATFORMIO_BUILD_FLAGS="-DSTACKCHAN_SERVER_URL=\"ws://${MAC_IP}:7780/ws\"" \
  pio run -d firmware -t upload --upload-port /dev/cu.usbmodemXXXX

端末別の Mac IP 確認

端末	確認コマンド
有線 + 無線併用	ipconfig getifaddr en0 (有線) or ipconfig getifaddr en1 (Wi-Fi)
Wi-Fi のみ	ipconfig getifaddr en1
全部見る	`ifconfig

LAN 外から繋ぎたい場合 (iPhone テザリング / カフェ Wi-Fi / 出張先)

母艦 Mac Studio を Tailscale Funnel で公開すれば、CoreS3 がインターネット側からでも同じエンドポイントで叩ける。

# 母艦 Mac Studio で 1 回だけ
bash mac-studio/scripts/tailscale-funnel-setup.sh
# → wss://<host>.<tailnet>.ts.net/stackchan/ws が公開される

firmware のビルド flag を WSS URL に切り替える:

DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib \
  PLATFORMIO_BUILD_FLAGS='-DSTACKCHAN_SERVER_URL="wss://<host>.<tailnet>.ts.net/stackchan/ws"' \
  pio run -d firmware -t upload --upload-port /dev/cu.usbmodemXXXX

シナリオ	推奨 URL	理由
母艦と同じ LAN	ws://<MAC_LAN_IP>:7780/ws	TLS 不要・最短レイテンシ
iPhone テザリング / 外出先	wss://<host>.<tailnet>.ts.net/stackchan/ws	LAN 外でも到達できる

既存 Funnel ルート (/ → 別サービス) を潰さないよう --set-path=/stackchan/ws で path 分岐する仕様。スクリプトは冪等に再実行できる。

STEP 5 — シリアルモニタで動作確認

pio device monitor -p /dev/cu.usbmodemXXXX -b 115200

初回 Wi-Fi 設定

シリアルに直接入力 (NVS に保存され再起動後も維持):

wifi:あなたのSSID:あなたのパスワード:home

タグ :home / :tether / :other で LCD ステータスアイコン (🏠/📱/☁️) が変わります。

Claude → VOICEVOX 経路テスト

claude:自己紹介して

期待ログ:

[claude] -> 自己紹介して
[claude] <- はじめまして、ぼくはドナック…
[wss] agent.done backend=claude
[wss] tts.start sr=24000 bps=16 ch=1 total=NNNNNN
[wss] tts.end received=NNNNNN bytes
[tts] playRaw samples=NNNNN sr=24000 ok=1

→ CoreS3 顔のスピーカーから満別花丸の声で日本語発話 🦆🎉

ほかに使えるコマンド

コマンド	用途
help	コマンド一覧
wifi-status	現在の Wi-Fi 接続状態
ws-status	WSS (bridge) 接続状態
claude:質問	Claude 経由で対話 (オンライン必須)
ask:質問	Module-LLM 内蔵 0.5B (オフライン可)
expr:happy|sad|sleepy|doubt|neutral	Avatar 表情強制
reset-llm	Module-LLM をリセット
wifi-clear	Wi-Fi 設定クリア & 再起動

端末別の運用イメージ

Mac Studio (神田オフィス) — 据え置きメイン

• 24/7 起動、bridge と VOICEVOX を常駐させる
• CoreS3 を据え置き、開発ブランチをここで安定運用
• 将来: launchd で bridge / VOICEVOX を自動起動

MacBook — 持ち運び・出先

• 必要に応じて bridge と VOICEVOX を立ち上げる（コマンド一発）
• 自宅 / カフェの Wi-Fi に CoreS3 と一緒に繋ぐ
• MAC_IP は端末ごとに変わるので build flag で都度上書き
• Claude Code サブスクは Mac 単位（複数台ログイン OK）

トラブルシュート

症状	原因 / 対処
pio run が pyexpat: Symbol not found で失敗	DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib を環境変数に
port 7780 is already in use	pkill -f "node --import tsx src/server.ts" で旧プロセス殺す
port 50021 listen failed	VOICEVOX 二重起動。pgrep -af voicevox で確認・kill
/dev/cu.usbmodem* not found	USB-C ケーブルがデータ通信非対応の可能性。別ケーブルへ
Could not exclusively lock port で flash 失敗	pio device monitor を別タブで開いたまま → Ctrl+C で閉じる
firmware が [wss] disconnected 連発	bridge 起動忘れ or MAC_IP 違い → ws-status で確認
firmware が [wifi] all profiles failed	SSID/PSK 不一致 or 5GHz 接続 → 2.4GHz / 互換性モード推奨
[tts] playRaw ok=0	PSRAM 不足 (希) or サンプルレート不一致。firmware/src/main.cpp の M5.Speaker.playRaw 呼出
Claude 応答が中国語	system prompt が弱い or 1.5B モデル不在 → 一時的に claude: を使ってバイパス
Module-LLM が無反応	reset-llm 実行 or USB-C 再接続

関連

• 組み立て手順
• パーツ管理
• プロトコル仕様
• Donack キャラ設定
• JCARVIS 連携
• mac-studio/bridge/SETUP.md (bridge 単体の詳細)