Muse Gadget SDK: ESP32 および Linux デバイス向け SDK

1. プロジェクト概要

Muse Gadget SDK は、ESP32 ボードや Raspberry Pi などの Linux マシンといった市販のハードウェアを、iOS および Android の Muse モバイルアプリとペアリングできる「ガジェット」に変換するオープンソース SDK です。開発者はハードウェアをゼロから設計することなく、独自のコネクテッドデバイスを構築できます。

2. 背景と位置づけ

存在する理由

Muse Gadgets を使うと、メイカーはディスプレイ、センサー、ボタン、マイク、スピーカー、アクチュエーターといった自作デバイスで Muse アプリを拡張できます。SDK がペアリングと通信を処理するファームウェアおよびクライアントコードを提供するため、ガジェットの機能そのものに集中できます。

類似プロジェクトとの違い

コンパニオンアプリ指向: デバイスは一般的なクラウドダッシュボードではなく、開発者モードのフローを通じて Muse モバイルアプリとペアリングします。
1 つのリポジトリに 2 つのデバイスファミリー: マイコン向けの C 言語ベースの ESP32 ファームウェアと、フル Linux システム向けの Python ベースの SDK を収録しています。
エージェントフレンドリー: 各 SDK に AGENTS.md が同梱されており、AI コーディングエージェント（Muse Code を含む）がガジェットのビルド、書き込み、拡張を支援できます。
設計思想としてハッカー向け: 本プロジェクトは「ハッカーがハッカーのために、ただ楽しむために作った」と謳っており、カスタムファームウェアにはリスクが伴い、自己責任での使用となります。

3. 機能カテゴリ

🔌 ESP32 デバイス SDK

ESP32 ボード向けのファームウェアとコンポーネントで、README には 5 つのボードファミリーが記載されています。例:

ESP32-C5 DevKitC-1（ステータスライトとボタン）
ideaspark ESP32（1.9 インチディスプレイ）
Seeed SenseCAP Indicator（4 インチ画面）
Waveshare AMOLED ボード（フル UI、プッシュトゥトーク）
Home Assistant Voice Preview（LED リング、音声）

目的: 低コストのマイコン上で、画面・音声・センサー搭載のガジェットを構築すること。

🐧 Linux デバイス SDK

Raspberry Pi やその他の Bluetooth LE 対応 Linux コンピューターを Muse ガジェットとして認識させる Python パッケージ（musegadget）です。例:

シェルコマンドを実行する system.run
64 KB 単位でファイルにアクセスする file.read / file.write
稼働時間、負荷、メモリ、ディスク、温度を取得する device.health
Home Assistant やシステム管理向けの独自コマンド

目的: スマートフォンから Linux マシンを制御・監視すること。

🖥️ シミュレーターとツール群

esp32/simulator、esp32/tools、esp32/tests に配置されています。例:

画面をプレビューできるデスクトップ UI シミュレーター（SDL ベース）
ボード固有のビルド、書き込み、モニターを行う tools/board.sh
ESP32 コードの単体テスト
esp32/devices 配下のボードごとの設定

目的: 編集・ビルド・書き込みのサイクルを短縮すること。

🧩 スキル

skills/ ディレクトリには、ガジェットやコーディングエージェントの機能を拡張する追加モジュールが含まれています。

目的: エージェント支援型開発向けの再利用可能なアドオン。

4. 主なハイライト

市販ハードウェア: カスタム PCB は不要で、一般的な ESP32 ボードや Raspberry Pi モデルが使えます。
スマートフォンとのペアリング: Muse アプリの開発者モードで、SDK トークンを使ってデバイスを接続します。
豊富なデバイス UI: ESP32 ビルドでは、対応ボードにおいてディスプレイ（LVGL ベースの UI）、アバター、音声入出力、プッシュトゥトークをサポートします。
Linux のリモート制御: アプリからコマンドの実行、ファイル転送、ヘルスメトリクスの取得が可能です。
AI 支援ワークフロー: AGENTS.md ファイルが、セットアップからビルドまでコーディングエージェントを導きます。
寛容なライセンス: メインコードは Apache-2.0 で、サードパーティの例外も明確に記載されています。

5. 役割別のユースケース

一般の開発者／メイカー: ESP32 ボード上で、携帯用ディスプレイ、音声デバイス、センサーガジェットのプロトタイプを作成できます。
DevOps / SRE: ホームラボやエッジ環境の Linux マシンをスマートフォンに公開し、簡単なコマンド実行やヘルスチェックを行えます（後述の権限に関する注意を参照してください）。
組み込みエンジニア: シミュレーターとボード用スクリプトを使い、頻繁な書き込みなしでファームウェア UI の試行錯誤ができます。
スマートホーム愛好家: 音声デバイスや LED リングデバイスなど、Home Assistant 向けのガジェットを構築できます。

6. クイックスタート

必要なものを探す

リポジトリを参照し、各 SDK ディレクトリの README をお読みください:

git clone https://github.com/facebookincubator/muse-gadget-sdk.git
cd muse-gadget-sdk

ドキュメント: https://gadgets.muse.ai

インストール／連携

まず gadgets.muse.ai/settings/sdk-tokens で SDK トークンを取得し、gadgets.muse.ai/sdk-terms にある Gadget SDK 利用規約を確認してください。

ESP32（ESP-IDF v6.0.1 が必要）:

cd esp32
idf.py menuconfig
idf.py build
idf.py -p /dev/cu.usbmodem1101 flash monitor

# ボード固有のビルド
tools/board.sh ideaspark build

Linux / Raspberry Pi:

curl -fsSL https://raw.githubusercontent.com/facebookincubator/muse-gadget-sdk/main/linux/install.sh -o install.sh
bash install.sh --sdk-token mgst_…

コントリビュート

リポジトリ内の CONTRIBUTING.md を読んだ上で、Issue またはプルリクエストを作成してください: https://github.com/facebookincubator/muse-gadget-sdk

7. プロジェクト構成

muse-gadget-sdk/
├── esp32/
│   ├── avatar/       # アバターのグラフィックスと描画
│   ├── cmake/        # ビルド設定
│   ├── components/   # ファームウェアのコンポーネント
│   ├── devices/      # ボード固有の設定
│   ├── main/         # ファームウェアの中核コード
│   ├── simulator/    # デスクトップ UI プレビュー
│   ├── tests/        # 単体テスト
│   └── tools/        # ビルドおよびユーティリティスクリプト (board.sh)
├── linux/
│   ├── examples/     # サンプル実装
│   ├── src/musegadget/  # 中核となる Python SDK
│   ├── tests/        # テストスイート
│   └── install.sh    # インストーラー
├── skills/           # 追加機能モジュール
└── .github/          # ワークフローとドキュメント用アセット

8. 関連エコシステム

Muse アプリ（iOS および Android）: ガジェットとペアリングするコンパニオンアプリ。
ESP-IDF v6.0.1: Espressif が提供する ESP32 ファームウェア向け開発フレームワーク。
LVGL: ビルド時に取得される組み込み向けグラフィックスライブラリ。
SDL: デスクトップシミュレーターで使用。
Home Assistant: 音声や独自コマンドに対応したガジェットの対象エコシステム。
uv と pytest: Linux SDK の開発とテストに使用。
Muse Code: AGENTS.md を通じてサポートされるコーディングエージェント。

9. ライセンス

✅ Apache License 2.0 の下で、商用利用を含めコードの使用、改変、配布が可能
✅ 再配布時はライセンスおよび著作権表示を保持すること
❌ Jollybot アバターが Apache-2.0 の対象であるとみなさないこと（除外されています）
ℹ️ サードパーティ製コンポーネントはそれぞれのライセンスに従います: minimp3.h は CC0-1.0、pixel_font.c は BSD-2-Clause
ℹ️ Gadget SDK の利用には、gadgets.muse.ai/sdk-terms の Gadget SDK 利用規約も適用されます
ℹ️ カスタムファームウェアおよび Linux SDK は、インストールに使用したアカウントの権限（利用可能であれば sudo を含む）で動作するため、自己責任で使用してください

10. よくある質問

Q: SDK の使用にトークンは必要ですか？
A: はい。ガジェットの書き込みやペアリングの前に、gadgets.muse.ai/settings/sdk-tokens で SDK トークンを取得してください。

Q: どのバージョンの ESP-IDF を使えばよいですか？
A: ESP32 の README に ESP-IDF v6.0.1 と指定されています。

Q: どの Linux システムがサポートされていますか？
A: Raspberry Pi 3B+、4、5、Zero 2 W、または Bluetooth LE に対応し、Raspberry Pi OS Bullseye 以降、Debian 11 以降、Ubuntu 22.04 以降を実行している任意の Linux コンピューターです。

Q: ハードウェアなしで UI をプレビューできますか？
A: はい。esp32/simulator のデスクトップシミュレーターを使用してください。

Q: メインのマシンで実行しても安全ですか？
A: Linux SDK は、インストールを行ったユーザーの権限でシェルコマンドを実行し、ファイルにアクセスできます。専用のデバイスを使用し、事前に README をお読みください。

11. クイックリンク

リポジトリ: https://github.com/facebookincubator/muse-gadget-sdk
ドキュメント: https://gadgets.muse.ai
SDK 利用規約: https://gadgets.muse.ai/sdk-terms
SDK トークン: https://gadgets.muse.ai/settings/sdk-tokens
コントリビューションガイド: リポジトリ内の CONTRIBUTING.md
コミュニティ: Discord（リポジトリの README からリンク）

12. まとめ

Muse Gadget SDK は、メイカーや開発者が安価な ESP32 ボードや Linux マシンをスマートフォン連携ガジェットへと変えるための実践的な手段を提供します。ハードウェアをいじるのが好きな方、スマートホームを構築したい方、そして寛容な Apache-2.0 ライセンスの下で AI 支援によるファームウェア開発を行いたい方に最適です。