已收录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 或其他支持低功耗蓝牙的 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 或拉取请求：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+ 的 Linux 计算机。

问：没有硬件也能预览 UI 吗？
答：可以，请使用 esp32/simulator 中的桌面模拟器。

问：在我的主力机上运行安全吗？
答：Linux SDK 可以以安装用户的权限运行 shell 命令并访问文件。建议使用专用设备，并先阅读 README。

11. 快速链接

12. 总结

Muse Gadget SDK 为创客和开发者提供了一条切实可行的路径，将廉价的 ESP32 开发板和 Linux 设备转变为可与手机连接的小工具。它适合硬件爱好者、智能家居搭建者，以及任何希望在宽松的 Apache-2.0 许可证下进行 AI 辅助固件开发的人。