【Mind+2.0加载测试扩展】让行空板 M10 变身小智AI语音助手
本项目已发布 Mind+ 2.0 Python 积木扩展,打开 Mind+ 就能拼积木使用。基于开源小智生态(感谢虾哥的 xiaozhi-esp32 与 py-xiaozhi),协议对照官方 v2.6.0 文档实现。
源码仓库:https://gitee.com/yuntian365/m10-voice-wakeword (
xiaozhi/目录下为扩展源码与使用说明)

一、项目简介
先看效果:
- 按住行空板 A 键说话:"打开 P21 上的灯" → 板上 LED 点亮,AI 回复"好嘞,P21 上的灯已经打开啦~"
- 换个说法:"10 秒后关闭 P21" → AI 创建定时任务,10 秒后引脚自动执行
- "每隔 5 秒闪一下 P1,闪 3 次" → 周期任务,闪 3 次自动停止
- "屏幕上显示你好" → M10 屏幕即时显示文字
- 连接蓝牙音箱后,AI 的声音从音箱里放出来
这一切不需要写 AI 代码、不需要配置任何 token:把 M10 连上小智官方云,设备绑定一次,之后开口说话即可。整个项目封装成了一个 Mind+ 积木扩展「小智AI 语音助手」,十几块积木就能搭出完整的语音交互应用,也支持脱离 Mind+ 用纯 Python 独立运行。

为什么做这个项目?
我之前做过一版"本地唤醒词识别"的语音助手:自己录音、自己训练 KWS 模型,跑在 M10 上。做下来发现两个问题——一是 M10 板载麦克风有直流偏置和底噪,唤醒词误触发很难根治;二是本地跑不了大模型,对话能力有限。
所以这一版换了思路:识别和大模型全部交给云端,设备只做"采集声音 + 播放声音 + 执行动作"。误触发问题顺手就解决了——按住 A 键才录音,触发完全由人控制;对话能力则直接继承小智云的大模型。
二、硬件与准备
| 材料 | 说明 |
|---|---|
| 行空板 M10 × 1 | 自带麦克风、喇叭、屏幕、A/B 键、Wi-Fi |
| LED / 风扇等执行器 | 接M10引脚 P21/P22/P23/P24(可选) |
| 蓝牙音箱(可选) | A2DP 音箱,连接后语音自动从音箱播放 |
| Mind+ 2.0 | Python 积木模式 |
| 小智账号 | xiaozhi.me 免费注册 |
软件依赖只有 4 个 Python 包(websocket-client / sounddevice / numpy / pinpong),M10 上均已预装。
三、实现原理
整个系统一条链路讲清楚:
① 绑定(只需一次)
M10 ──POST 设备MAC──> 小智 OTA 服务
<── WSS 凭证 + 6位验证码 ──
未绑定 → 验证码自动显示在 M10 屏幕 → 手机扫码/输码绑定
② 对话(核心链路)
麦克风(16kHz PCM) → Opus 编码(60ms/帧) → WebSocket 二进制流
→ 小智云:ASR 识别 → 大模型对话 → TTS 合成
→ Opus 解码 → 喇叭播放
↘ AI 决策调用工具时:MCP tools/call (JSON-RPC)
→ M10 执行 GPIO / PWM / 定时任务 / 屏幕显示 → 结果回传云端
③ 对话内容实时上屏:「我:」蓝色 /「智:」绿色,保留最近 6 轮
小智云约 60 秒空闲会主动断开连接,库里实现了断线自动重连(自动重新取凭证,2~4 秒恢复),用户完全无感。
四、实现过程
第 1 步:OTA 自动获取凭证,免去 token 配置
小智提供了 OTA 接口:设备把自己的 MAC 地址 POST 过去,就能拿到两样东西——WebSocket 接入地址和通信凭证。设备未绑定时还会返回一个 6 位激活码。
这是"开箱即用"的关键:程序启动时自动调 OTA,用户从头到尾不用碰控制台、不用复制 token。未绑定时把验证码和绑定二维码画到 M10 屏幕上,手机扫码绑定一次,之后凭证自动下发、自动刷新。
# OTA 核心:MAC 换凭证 + 激活码
class XiaoZhiOTA:
def fetch(self):
payload = {"mac": self.mac, "application": {"version": "1.0.0"}}
r = requests.post(OTA_URL, json=payload, timeout=10)
data = r.json()
self._ws_url = data["websocket"]["url"]
self._token = data["websocket"]["token"]
self._code = data.get("activation_code") # 未绑定时非空
第 2 步:打通语音链路(录音 → Opus → WSS → 解码播放)
音频是小智协议的核心。M10 上用 sounddevice 以 16kHz 采集 PCM,用 ctypes 直接调用系统自带的 libopus 编码成 60ms 一帧(960 采样)的 Opus 包,通过 WebSocket 二进制消息推给云端;云端返回的 TTS 音频同样按帧解码后送喇叭播放。
对话状态由服务端控制:发送 listen start 后推流,云端 VAD 判断"一句说完",再下发 TTS 播放事件。AI 说话时自动暂停收音,避免麦克风拾到喇叭声造成自激。
第 3 步:三种监听模式,适配不同使用场景
| 模式 | 操作 | 适合场景 |
|---|---|---|
manual(默认) |
按住 A 键说话,松开发送 | 稳妥、零误触发 |
b_toggle |
按一下 B 键开启连续对话,再按一下结束唤醒 | 长时间多轮聊天,按键最省事 |
auto |
免按键,直接说话 | 双手占用的场景 |
b_toggle 是后来加的:给按键监听加了边沿检测(按一下算一次,带去抖),B 键按下开麦推流、再按关麦回待机。它比 auto 更省流量——只有对话开启时才推流,平时麦克风是关闭的。
第 4 步:注册 MCP 工具,让 AI "看得见"这块板子
这是本项目最有意思的部分。小智协议里的 MCP 工具调用走 JSON-RPC 2.0:云端大模型决定调用哪个工具,下发 tools/call,设备执行后把结果回传,AI 再据此继续对话。
设备端要做的事是在 tools/list 里"自我介绍"——告诉大模型这块板子能干什么。我按官方 MCP 文档的规范注册了 9 个工具,每个参数都带中文描述和取值约束(JSON Schema),让大模型能准确填参:
self.add_tool("self.gpio.write",
"设置行空板引脚输出电平。pin 为引脚编号如 P21;value 为电平,0=低电平/关闭,1=高电平/打开",
{"pin": {"type": "string", "description": "引脚编号,如 P21", "minLength": 1},
"value": {"type": "integer", "description": "电平:0=低/关,1=高/开", "enum": [0, 1]}},
self._tool_gpio_write)
self.add_tool("self.schedule.every",
"创建周期定时任务:每隔 seconds 秒把引脚 pin 设为 value。repeat 可选,控制重复次数,-1 表示一直重复",
{"seconds": {"type": "integer", "minimum": 1, "maximum": 86400},
"pin": ..., "value": ...,
"repeat": {"type": "integer", "description": "重复次数,-1=无限", "default": -1}}, # 可选参数
self._tool_schedule_every)
参数约束的价值立刻就能看到:对 AI 说"每隔 5 秒闪一下 P21,闪 3 次",它会正确调用 self.schedule.every,参数为 {"seconds":5,"pin":"P21","value":1,"repeat":3}——repeat 次数一到,任务自动停止。
工具名遵循官方推荐的 self.<模块>.<功能> 命名:self.gpio.write/read/pwm、self.schedule.after/every/cancel/list、self.display.show、self.get_device_status。
小技巧:在 xiaozhi.me 控制台的智能体系统提示词里补一句"你可以控制一块行空板 M10……用户说开灯/关灯时操作对应引脚",工具调用的准确率会明显提高。
更进一步:用「标注引脚上接的设备」积木(或 xz.set_device('P21','风扇'))把接线直接写进工具描述——tools/list 会返回"当前接线:P21=风扇,P1=台灯"。这样连系统提示词都不用配,AI 听到"帮我把 P21 上的风扇打开"就知道操作 P21;甚至对话里告诉它"P22 接了舵机",AI 会调用 self.device.set 自己完成标注。
第 5 步:蓝牙音箱积木(扫描 → 连接 → 声音自动切换)
M10 的 Debian 系统自带 bluez 和 pulseaudio,蓝牙功能不需要任何新的 Python 依赖,用 subprocess 调 bluetoothctl 和 pactl 即可:
- 扫描:运行
bluetoothctl scan on若干秒,用正则从输出里提取[NEW] Device MAC 名称,得到实时广播中的设备列表,同时把1. MAC 设备名显示到屏幕供用户挑选; - 连接:先注册配对代理(
default-agent),再依次向目标 MAC 发送trust → pair → connect。pair负责建立配对(交换链路密钥),所以从未配对过的全新音箱也能直接连,不需要提前用命令行手动配对;已配对过的设备执行pair会提示 Already exists,不影响流程。连接建立后 bluez 会自动注册一个名为bluez_sink.<MAC>.a2dp_sink的音频输出设备; - 切换声音:
pactl set-default-sink bluez_sink.XX_XX_...把默认输出切到蓝牙音箱——之后小智的 TTS 语音就自然从音箱播放,代码里不用改任何音频逻辑;断开时再切回板载alsa_output即可。
实测从"扫描"到"AI 声音从音箱出来"全程十几秒,体验很顺。
第 6 步:封装成 Mind+ 积木扩展
最后把上面的全部能力封装为 Mind+ 2.0 Python 积木扩展,约 30 块积木,分 6 类:
- 连接:初始化(自动取凭证)、连接/断开、验证码上屏、刷新绑定
- 对话:监听模式切换、运行主循环、读取最后听到/回复的话
- GPIO:输出电平、读取电平、PWM 占空比
- 定时:延时执行、周期执行、取消/清空/任务列表
- 蓝牙:扫描(结果上屏)、MAC 列表、连接音箱、断开、音频路由切换
- 状态:屏幕显示文字/对话记录、对话历史读取
扩展分三层实现:index.js 定义积木外观与输入项,func.js 负责把积木翻译成 Python 代码,核心逻辑全部在单文件库 xiaozhi_kit.py(OTA/协议/音频/GPIO/定时/蓝牙各一个类)里。
积木块功能列表
| 分类 | 积木块 | 功能 |
|---|---|---|
| 连接 | 初始化小智 实例名(自动取凭证) | 创建实例,无需 token,自动 OTA 获取凭证 |
| 连接 | 连接小智云 / 断开连接 / 已连接? | 连接状态管理 |
| 连接 | 刷新绑定状态(绑定后调用) | 绑定完成后重新获取凭证 |
| 连接 | 已绑定设备? / 激活验证码 / 显示验证码到屏幕 | 绑定状态查询与验证码上屏 |
| 对话 | 监听模式设为 manual / b_toggle / auto | 按键说话 / B键切换连续对话 / 免按键持续收音 |
| 对话 | 当前监听模式 | 返回当前模式 |
| 对话 | 说一次(按住A键说话)最多 T 秒 | 单轮语音对话 |
| 对话 | 运行主循环 | 按当前模式持续对话 + 驱动定时任务(推荐) |
| 对话 | 最后听到的话 / 最后回复的话 | 读取最近一轮对话文本 |
| GPIO | 引脚 Pin 输出电平 VALUE | 数字输出(P21/P22/P23/P24,值 0/1) |
| GPIO | 读取引脚 Pin 电平 | 数字输入 |
| GPIO | 引脚 Pin PWM 占空比 DUTY% | PWM 输出(0~100) |
| GPIO | 标注引脚 Pin 上接的设备为 DEVICE | 告诉 AI 接线(如 P21=风扇),语音说"打开风扇"即可控制 |
| 蓝牙 | 扫描蓝牙设备 T 秒(结果上屏) | 扫描附近设备,MAC 列表显示在屏幕并缓存 |
| 蓝牙 | 蓝牙设备 MAC 列表(扫描后) | 返回扫描到的 MAC 字符串列表 |
| 蓝牙 | 连接蓝牙音箱 MAC | 连接音箱并自动把语音切换到音箱播放 |
| 蓝牙 | 断开蓝牙音箱(切回板载喇叭) | 断开连接并恢复板载音频 |
| 蓝牙 | 蓝牙音箱已连接? | 返回 True/False |
| 蓝牙 | 音频输出切到 蓝牙音箱/板载喇叭 | 手动切换音频路由 |
| 蓝牙 | 蓝牙状态信息 | 返回连接状态、MAC、音频 sink 等信息 |
| 定时 | S 秒后 引脚 Pin 设为 VALUE | 一次性定时任务 |
| 定时 | 每隔 S 秒 引脚 Pin 设为 VALUE | 周期定时任务 |
| 定时 | 取消定时任务 编号 ID / 清空所有 / 任务列表 | 任务管理 |
| 定时 | 检查执行到期任务 | 在自定义循环里手动驱动任务 |
| 状态 | 运行状态 / 屏幕显示 TEXT | 状态查询与文字显示 |
| 状态 | 屏幕显示对话记录 | 把最近对话以「我:/智:」形式画到屏幕 |
| 状态 | 对话记录(列表) | 返回 [(角色, 文本), …] 列表 |
| 状态 | 清空对话记录 | 清空记录并恢复待机界面 |
这样积木生成的 Python 代码非常简洁:
from xiaozhi_kit import XiaoZhi
xz = XiaoZhi() # 初始化小智(自动取凭证)
xz.connect() # 连接小智云
xz.set_listen_mode('b_toggle') # B 键切换连续对话
xz.schedule_after(10, 'P21', 0) # 10 秒后关闭 P21
xz.run_forever() # 主循环:对话 + 定时任务
五块积木,就是一个能语音对话、能定时控制引脚的完整作品。
加载扩展



五、演示:一句话完成的一切

(内容显示有待完善)


实际对话记录(终端日志摘录):
[小智] 听到: 你好,小智。帮我把 P21 的灯打开
[小智] MCP调用: self.gpio.write {"pin":"P21","value":1}
[小智] MCP结果: 已将 P21 设为 高/开
[小智] 回复: 好嘞,P21 上的灯已经打开啦~
屏幕上同步显示「我: 你好小智…」/「智: 好嘞…」的对话气泡;LED 在真实引脚上点亮。换一句"10 秒后关掉它",定时任务立即创建并在 10 秒后自动执行——用户全程只动了嘴。
六、总结与展望
这个项目的核心思路是:设备做简单的 I/O,智能交给云端。借小智官方云的 ASR + 大模型 + TTS,一块行空板就拥有了高质量的语音交互能力;再通过 MCP 工具机制把板子的 GPIO、定时器、屏幕、蓝牙"注册"给大模型,AI 就从聊天工具变成了真正的硬件控制中枢。
可以继续扩展的方向:
- 更多 MCP 工具:摄像头拍照、读取传感器(温湿度/加速度)、控制舵机,都可以按同样方式注册,AI 能力随硬件一起扩展;
- 接入传感器做主动播报:定时读取传感器,超阈值主动让 AI 说话提醒;
- 配合 PinPong 库扩展更多执行器:电机、继电器、RGB 灯带,全都能用一句话控制。
附:资源下载
- 扩展安装包
ext-WorkBuddy-xiaozhiKit@1.2.0.zip:通过 Mind+「导入扩展」安装 - 独立运行:把
m10_main.py和xiaozhi_kit.py拷到 M10 同一目录,python3 m10_main.py即可 - 参考项目:xiaozhi-esp32(虾哥) / py-xiaozhi / py-xiaozhi 二开版
欢迎在评论区交流,有问题我会及时回复~




