facebookincubator/muse-gadget-sdk 是 Meta 官方在 GitHub 上以 Apache 2.0 协议开源的”硬件外设 SDK”，专门用于为 Meta 旗下的 AI 助理 Muse 自制配套设备。仓库目前已收获 1.7k+ Star / 342 Fork，主语言是 C（C 占 9.1 MB，Python 636 KB、C++ 431 KB），支持从一块 30 元的 ESP32-C5 到 7.5 寸墨水屏再到 Raspberry Pi 5 的几乎所有”工位上能找到的开发板”。

一句话总结它的定位：Muse 主管”动脑”，你的板子主管”动手”——手机 App 里开口说一句”Hey Muse，帮我关掉客厅灯”，指令就能落到你焊在面包板上的 ESP32 上。

Muse Gadgets 设备全家福：Waveshare 圆形 AMOLED、M5Stack StickS3、Muse Home Link、树莓派与 Seeed reTerminal 墨水屏

一、Muse 是什么？为什么要给它做外设？

Muse 是 Meta 在 2026 年力推的 AI 助理/Agent 应用，与 OpenAI ChatGPT、Anthropic Claude、xAI Grok 同台竞技。它把 Llama 系列模型落到 C 端，主打”替你做事”而不是”陪你聊天”，免费、跨端（iPhone → iPad → Mac）。

Muse 在 AI Daily · 2026-10-08 的《Meta Muse 拓展到 iPad》一条里已经做过介绍：The Verge 将它和 OpenClaw、ChatGPT Dots、Grok Bot 并列，归为”agentic AI 工具”。它的下一步战略大概率是开放第三方插件生态，直接和 OpenAI 的 Apps SDK、Anthropic 的 MCP 生态正面碰撞。

问题来了：Agent 需要”手脚”。问 Muse”今天天气怎么样”它能调 API，但问 Muse”把咖啡机打开”、”把树莓派上的备份跑一下”、”把车库门状态推到我手机上”——这些 “环境里的物理操作” 就需要硬件外设来执行。Muse Gadget SDK 正是为这层”最后一公里”准备的：把任意 ESP32/Linux 设备接入 Muse 的命令系统，让它能跑 shell、读文件、控 GPIO、发消息。

二、仓库结构：双子 SDK 设计

仓库根目录只放了 LICENSE、README 和两个子目录，结构非常克制：

1
2
3
4
5
muse-gadget-sdk/
├── esp32/      # ESP32 设备 SDK（C/C++，基于 ESP-IDF v6.0.1）
├── linux/      # Linux 设备 SDK（Python，可装在树莓派）
├── skills/     # 给代码 Agent 用的辅助说明
└── .github/    # README 用图、Issue 模板

两个 SDK 走完全独立的技术栈：ESP32 走 Espressif 官方 ESP-IDF v6.0.1（CMake 编译，idf.py 烧录），Linux 走 Python + uv + systemd（/opt/musegadget 安装路径），但对外暴露的接口语义一致——都能注册 system.run、file.read、file.write、device.health 这类”命令”，Muse 调度时无差别。

三、ESP32 SDK：固件、组件、模拟器三层

esp32/ 目录下又分成三块：

子目录 作用
components/muse/ Muse 协议核心：BLE 配对、Chat 链路、Audio、Avatar、Board 抽象、Camera、电池、按键、ADPCM、Pixel Font、minimp3 解码器
devices/ 27 款开发板的 sdkconfig 适配，从最简的”只有状态灯”到带完整触控 UI 的 7 寸屏
simulator/ 桌面端 SDL+LVGL 模拟器，412×412 窗口运行生产 UI，无需板卡就能开发头像/UI

3.1 已适配的 27 款开发板

按 README 列表，开发板分为两类——“只显示状态”的轻量级（呼吸灯、LED 环），以及”完整 UI”的重量级（动画头像、push-to-talk、设置、图像显示）：

  • 极简派：ESP32-C5 DevKitC-1、ESP32-C6 无 PSRAM、Espressif ESP32-S3-DevKitC-1、ideaspark 1.9” 屏、Waveshare C6-LCD-1.47、Seeed reTerminal E1001/E1002（墨水屏）、Home Assistant Voice Preview Edition
  • 完整 UI 派：Waveshare ESP32-S3-Touch-AMOLED-1.75 / 2.16、ESP32-S3-BOX-3、AIPI Lite、M5Stack Cardputer ADV / StickS3 / StopWatch / CoreS3 / Core2 / StickC Plus2、Seeed SenseCAP Watcher、Guition JC3248W535、Waveshare ESP32-S3-Touch-LCD-7、Freenove FNK0104B、VN 1.83” NV3023、FoloToy AI Passport

3.2 状态灯”七色呼吸”协议

设备没配对时是 橙色呼吸，提示等待设置；按下 BOOT 键后是 蓝色呼吸 等待物理确认；连上 Muse 是 绿色常亮；重连是 黄色闪烁；未配对是 紫色；出错是 红色闪烁。这套”灯语”和米家、Aqara 的”找队友”逻辑异曲工，是它开箱即用体验的核心。

3.3 三步烧录：ESP-IDF + idf.py

仓库不绑死 Muse Code，可以纯手工：

1
2
3
4
5
6
7
8
git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6
~/esp/esp-idf-v6/install.sh esp32c5,esp32s3,esp32c6,esp32
. ~/esp/esp-idf-v6/export.sh

cd muse-gadget-sdk/esp32
idf.py menuconfig    # ESP32 Device SDK > Muse Gadgets SDK token
idf.py build         # 默认 ESP32-C5 DevKitC-1
idf.py -p /dev/cu.usbmodem1101 flash monitor

切到别的板子：

1
2
tools/board.sh waveshare-c6-lcd-147 build
tools/board.sh m5stack-stickc-plus2 build

四、Linux SDK：把树莓派变成 Muse 的”运维代理”

linux/ 是纯 Python 写的服务端 SDK，安装体验接近”装一个 Node Agent”：

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

它做三件事：

  1. 检查系统（Raspberry Pi OS Bullseye+/Debian 11+/Ubuntu 22.04+，32/64-bit 均可）
  2. 安装到 /opt/musegadget，注册 systemd 服务 musegadget
  3. 通过 BLE 打开配对窗口（10 分钟），这时手机端 Muse App 进 Settings > Devices > Developer mode > Add Device 就能搜到 MuseGadgetXXXXXX

配对成功后，Muse 就能在这个 Linux 账号下执行 4 个内建命令：

命令 行为
system.run 跑 shell 命令，返回 stdout 和 exit code
file.read 按 64 KB 分片读文件
file.write 写文件，完整写完才替换原文件
device.health 上报 uptime、load、内存、磁盘、温度

权限等于这个账号本身——你 sudo 就能 sudo，你读得了 /etc/shadow 就能读，账号即权限。README 反复提醒”Proceed at your own risk”。

4.1 让 Muse 反向推消息：send-user-msg

最有意思的是反向通道——板子主动给 Muse 发消息，不用任何凭据：

1
2
musegadget send-user-msg "The garage door has been open for an hour."
musegadget send-user-msg --session-id 6f1c2d4e-0b7a-4c3e-9f5d-2a8b1e0c7d93 "Posted to a side chat"

仓库自带 examples/pebble_ring_bridge.py，演示把 Pebble 智能戒指的轻点动作转成 Muse 的侧栏聊天。任何”事件 → 文本”的桥 都可以这样搭——PIR 触发、PM2.5 超标、OpenWrt 重启、心跳丢失……

五、最黑客友好的设计：AGENTS.md + 模拟器

仓库有两个细节能看出 Meta 给”硬核玩家”留的入口：

  1. 每个子目录都有 AGENTS.md：给 Muse Code / Claude Code / Codex 这类 AI Agent 当工作指令。Agent 一进仓库就能自己挑板子、装工具链、烧录、读日志。README 里给的 prompt 模板直接可拷：

    Watch the serial log and tell me when it’s ready to pair.

    I have a Waveshare ESP32-S3 AMOLED board. Build the UI for it.

    Add support for my board. It’s an ESP32-S3 with 16 MB flash, a button on GPIO 0 and no PSRAM.

  2. simulator/ 桌面模拟器：在 macOS/Linux 上直接 ./simulator 起一个 412×412 的 SDL 窗口，运行的是生产 UI 和头像渲染器，鼠标键盘模拟输入，还能无头跑截图脚本——做头像、做皮肤、调试字体，再也不用蹲在板子边看串口了。

六、动手门槛与安全注意

  • 烧录可能砖：固件签的是仓库自带的开发 key，没开 Secure Boot，可以随便重刷；但刷别的固件确实会”砖化”原厂功能。
  • SDK token 等同设备身份：它被编进固件里，所以要当标识符而不是密码。泄露就在 gadgets.muse.ai 撤销重发。
  • NVS 加密强烈建议开：Wi-Fi 凭据和设备 token 默认存 flash，开 CONFIG_HOMEHUB_NVS_ENCRYPTION 后会用 eFuse 派生密钥。
  • OTA 默认关：只对跑完整 UI 的板卡默认开。商用前要自己设 CONFIG_HOMEHUB_OTA_ENABLED 和 PROJECT_VER。
  • 配对无厂商验证：Muse 端只校验”按下 BOOT 键”这一物理动作，没有证书链，理论上有源中间人仍可劫持。在受信网络里配对。

七、和 Rabbit r1 / Humane Pin 的本质区别

Rabbit r1 和 Humane AI Pin 走的是”专用硬件 + 闭源 OS + 云端 Agent”路线，烧死了所有可玩性；Muse Gadget SDK 走的是 “云端 Agent + 开源外设 SDK” 路线——板子随便换、固件随便改、命令随便加。两者的”AI 助理”心智模型一样，但 Muse 把”硬件”这层做成了 乐高，而不是 整机。

这意味着：家里堆着的 ESP32 模组、吃灰的树莓派、柜子里落灰的 M5Stack 都能再就业，不必再花 $199 买一个”功能更少的手机”。

八、值得抄走的工程实践

  • 每块板子一个 sdkconfig.<board>，叠在 sdkconfig.defaults 之上，加新板成本极低
  • tools/board.sh 统一 build 入口，每个板子跑独立 build-<board> 目录，互不污染
  • version.txt + PROJECT_VER 控制 OTA，签名固件用开发 key 兜底
  • 测试双轨：Python 单元测试在主机跑，crypto 测试在装了 mbedtls 的环境跑
  • Apache 2.0 + 第三方组件保留上游 License（minimp3 是 CC0，glcdfont 是 BSD-2）

九、总结与上手建议

如果你是 Maker / IoT 玩家，手里有 ESP32 板子又想试试 Agent 硬件——直接 git clone，配好 ESP-IDF v6.0.1，按 AGENTS.md 一路走，半小时内能在你手机上的 Muse App 里看到自己的设备呼吸橙光。

如果你是 DevOps / 树莓派用户，linux/install.sh 跑一下，Muse 立刻获得一个 sudo 级别的”运维代理”——这在 2026 年还属于新鲜事，OpenAI 和 Anthropic 都没把”任意 Linux 主机作为 Agent 节点”做到这种开箱即用度。

如果你是 AI 行业观察者，Muse Gadget SDK 揭示了 Meta 的一个明确信号：Agent 不会止于 App Store，要落地到工位上的每一块屏幕、每一个传感器。这是 2026 年下半年 AI 公司从”对话窗口”走向”行动网络”的标志性开源。

仓库地址：github.com/facebookincubator/muse-gadget-sdk
配对需要 SDK Token：https://gadgets.muse.ai/settings/sdk-tokens
社区 Discord：https://discord.gg/3bhjCkZdd6

延伸阅读：

觉得这篇解读有用？欢迎在下方留言，告诉我你打算用哪块板子接入 Muse——也许下一篇就是它的踩坑记录。