📚 ナレッジ集（M5Stack / 電子制御）
スタックちゃん（M5Stack CoreS3）の 電子制御に関する基礎・調べたこと・詰まったポイント を、後で見返して理解できる形で残していくページ群。
開発環境のセットアップやデプロイ手順など、電子制御以外のトピックはここには含めない。
読む順番（電子工作はじめての人向け）
- 01-hardware-basics.md — CoreS3 / スタックちゃんの中身、USB-C を繋ぐと何が起きるか
- 02-platformio-setup.md — マイコンへのビルド・書き込みの仕組み
- 03-serial-monitor.md — シリアル通信、リセット、起動ログの読み方
応用ナレッジ
- 04-module-llm-adb.md — Module-LLM Linux に ADB で入って apt パッケージ追加
- 05-voicevox-setup.md — VOICEVOX (満別花丸) を macOS に headless install
- 06-claude-sdk-subscribe.md — Claude Agent SDK のサブスクモード活用
- 07-mcp-stdio-server.md — カスタム MCP stdio server を自前で書く
トラブル事典（ハマったら引く）
| 症状 | ページ |
|---|---|
avr/interrupt.h: No such file でビルド失敗（サーボライブラリが ESP32 で動かない） | troubleshooting/varspeedservo-esp32.md |
| MeloTTS が中国語の発音で読み上げる | troubleshooting/melotts-default-language.md |
| KWS wake は検出するが VAD/Whisper が一切発火しない（Module-LLM に日本語 ASR モデル不在） | troubleshooting/whisper-japanese-not-supported.md |
| Module-LLM 単体で日本語対話を完結させたい（オフライン install で Whisper + TinySwallow + MeloTTS-ja-jp） | troubleshooting/module-llm-japanese-pipeline.md |
| Module-LLM の LLM が遅い／MeloTTS と同居できない → ハイブリッド構成 (ASR だけオンデバイス、LLM/TTS は bridge) で 7 秒応答 | troubleshooting/hybrid-asr-claude-voicevox.md |
用語辞典
| 用語 | 一言で |
|---|---|
| ESP32-S3 | スタックちゃんの「脳みそ」のCPUチップ。Wi-Fi/Bluetooth 内蔵。 |
| CoreS3 | M5Stack 社が ESP32-S3 を載せて作ったモジュール製品名（K151のベース）。 |
| Module-LLM | CoreS3 の背面に積む LLM 推論モジュール。AX630C + 3.2 TOPS NPU。 |
| AX630C | Module-LLM の中で動く SoC。RISC-V + Cortex-A55 + NPU。 |
| Unit | M5Stack 社の周辺機器シリーズ。GROVE ケーブル1本で繋ぐ。 |
| Bottom3 | CoreS3 の底面に積む GROVE 拡張ベース + バッテリー。 |
| GROVE | 4ピンの統一コネクタ規格。Unit はだいたい GROVE で繋ぐ。 |
| PlatformIO | マイコン用の「ビルド・書き込みツールキット」。Mac で書いたコードをスタックちゃんに送る道具。 |
| ファームウェア (firmware) | マイコンに書き込む「OS兼アプリ」のこと。電源を入れたら勝手に動き出すプログラム。 |
| フラッシュ書き込み | ファームウェアをマイコンの不揮発メモリに焼く操作。USB経由でやる。 |
| シリアル | マイコンと PC が1本のケーブルで会話する古典的な通信方式。printfデバッグはこれ経由で見る。 |
| UART | シリアル通信の電気的な規格名。USBの内側で UART に変換されて CoreS3 と話している。Module-LLM も UART で繋がる。 |
| I2C | アイ・スクエア・シー。マイコンと周辺チップを2本の線で繋ぐ通信規格。サーボボード・センサー類はだいたいこれ。 |
| GPIO | General Purpose I/O。マイコンから出ている「自由に使える線」。HIGH/LOW を出したり読んだり。 |
| PSRAM | Pseudo Static RAM。CPU 内蔵 RAM だけでは足りないときに増設する外付けメモリ。 |
| サーボ | 角度指定で動くモーター。スタックちゃんの首振りに使う。 |
| LCD | 液晶ディスプレイ。CoreS3 は 2インチ・320×240 ピクセル。 |
| PIR | 焦電型赤外線センサー。動きを検知する。 |
| TMOS | サーモパイル MEMS センサー。動いてない人も検知できる新世代の人感センサー。 |
| ToF | Time-of-Flight。光の往復時間で距離を測るセンサー。 |
| Tailscale | WireGuard ベースの VPN／オーバーレイネットワーク。Mac Studio を世界中から固定URLで叩けるようにする。 |
| Funnel | Tailscale の機能。tailnet 内のサービスを公開 HTTPS で外部に出せる。証明書も自動。 |
| Backend Router | Mac Studio 側に置く「深い思考」のバックエンド切替層。Claude / Codex / Local LLM のいずれにも投げ分けられる。 |
| Degraded Mode | Mac Studio に繋がらない／Wi-Fi が無いときに Module-LLM だけで動く縮退モード。雑談・IR 家電は動く。 |
書き込みルール
- ハマったら 症状 → 原因 → 対処 の3点セットで
troubleshooting/にファイルを追加する - 専門用語は初出時に必ず1行で説明する
- 「なぜそうなるのか」を書く。コピペで動いても理解は進まない
- 電子制御以外（環境構築・ホスティング・CIなど）は別の場所に書く