已收錄429 則資訊/102 款 AI 工具/413 個開源專案/75 個學習資源
首頁資訊開源排行榜模型排行AI 工具學習資源
首頁 / 開源排行榜 / muse-gadget-sdk

muse-gadget-sdk

開源 SDK，可將 ESP32 開發板以及 Raspberry Pi 或 Linux 機器變成能與 Muse 行動應用程式配對的自訂小工具。

CApache-2.0Framework
⭐ GitHubhttps://github.com/facebookincubator/muse-gadget-sdk
250
Star 數
+0
Star 增速
2026年10月3日
最後更新
8
點擊數

1. 專案概覽

Muse Gadget SDK 是一套開源 SDK，能將現成的硬體（例如 ESP32 開發板、Raspberry Pi 或其他 Linux 機器）轉變為可與 iOS 及 Android 上的 Muse 行動應用程式配對的「小工具」，讓開發者無需從零設計硬體，即可打造自訂的連網裝置。

2. 背景與定位

為何而生

Muse Gadgets 讓創客能以自己的裝置擴充 Muse 應用程式的功能：顯示器、感測器、按鈕、麥克風、喇叭與致動器。此 SDK 提供負責處理配對與通訊的韌體及用戶端程式碼，讓你專注於小工具本身的功能。

與類似專案的差異

  • 以配套應用程式為導向：裝置透過「開發者模式」流程與 Muse 行動應用程式配對，而非使用通用的雲端儀表板。
  • 單一儲存庫涵蓋兩大裝置系列：適用於微控制器的 C 語言 ESP32 韌體，以及適用於完整 Linux 系統的 Python SDK。
  • 對 AI 代理友善：每個 SDK 皆內附 AGENTS.md，讓 AI 程式編寫代理（包括 Muse Code）能協助建構、燒錄與擴充小工具。
  • 天生適合駭客：本專案自述為「由駭客打造、為駭客而生，純粹為了好玩」，因此自訂韌體帶有風險，須自行承擔使用責任。

3. 功能分類

🔌 ESP32 裝置 SDK

專為 ESP32 開發板提供的韌體與元件，README 中記載了五個開發板系列。範例：

  • ESP32-C5 DevKitC-1（狀態燈號與按鈕）
  • ideaspark ESP32（1.9 吋顯示器）
  • Seeed SenseCAP Indicator（4 吋螢幕）
  • Waveshare AMOLED 開發板（完整 UI、按鍵通話）
  • Home Assistant Voice Preview（LED 環、語音）

用途：在低成本的微控制器上打造具備螢幕、音訊與感測器的小工具。

🐧 Linux 裝置 SDK

一個 Python 套件（musegadget），可讓 Raspberry Pi 或其他支援藍牙低功耗（Bluetooth LE）的 Linux 電腦化身為 Muse 小工具。範例：

  • system.run 用於執行 Shell 指令
  • file.read / file.write 以 64 KB 為單位存取檔案
  • 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，無需不斷重新燒錄。
  • 智慧家庭愛好者：打造以 Home Assistant 為導向的小工具，例如語音或 LED 環裝置。

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）或拉取請求（pull request）：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. 常見問題

問：我需要使用權杖才能使用此 SDK 嗎？
答：是的。請在燒錄或配對小工具之前，先至 gadgets.muse.ai/settings/sdk-tokens 取得 SDK 權杖。

問：我應該使用哪個 ESP-IDF 版本？
答：ESP32 的 README 指定使用 ESP-IDF v6.0.1。

問：支援哪些 Linux 系統？
答：Raspberry Pi 3B+、4、5 與 Zero 2 W，或任何執行 Raspberry Pi OS Bullseye 以上版本、Debian 11 以上版本或 Ubuntu 22.04 以上版本且支援藍牙低功耗（Bluetooth LE）的 Linux 電腦。

問：沒有硬體也能預覽 UI 嗎？
答：可以，請使用 esp32/simulator 中的桌面模擬器。

問：在我的主力電腦上執行安全嗎？
答：Linux SDK 能以安裝使用者的權限執行 Shell 指令並存取檔案。建議使用專用裝置，並先閱讀 README。

11. 快速連結

12. 總結

Muse Gadget SDK 為創客與開發者提供了一條實用的途徑，能將價格低廉的 ESP32 開發板與 Linux 機器轉變為可與手機連線的小工具。它適合硬體玩家、智慧家庭建置者，以及任何希望在寬鬆的 Apache-2.0 授權下進行 AI 輔助韌體開發的人。