说到先说个大前提，一条连接，两类消息

设备跟服务器之间。从头到尾只维持一条 WebSocket 连接。老实说，这条连接上跑着两种完全不同的东西：

• 文本消息长得像 {"type": "listen"。...} 这种 JSON，负责“打招呼”“说开始”“说结束”这类控制动作；
• 二进制消息一坨一坨的音频数据。毫秒一帧，听上去很碎，但拼起来就是一句完整的话。

有人会问的观点是。为什么不干脆开两条连接，一条发指令一条传音频？因为语音这件事最怕乱序——你总不能“开始播放”还没到，音频帧先到了吧？共用一条连接，服务器内部再走同一个发送队列。就能保证“先下指令、再发声音、最终说结束”这个顺序铁打不乱。

对了还有个细节：设备怎么自报家门？靠 WebSocket 握手时带的一个请求头 Device-Id。没带的话服务器也不翻脸，自动给你编一个 anon-xxxx只是以后想精确找到这台设备就费劲了。

传输层总览

项	值	说明
协议WebSocket单条长连接承载全部控制与音频服务端方法/xiaohong/v1可在 ws_path-修改文本帧JSON 控制消息握手/状态/控制二进制帧opus 音频帧每帧一个独立 WS 二进制消息。默认 40ms/帧设备标识HTTP Header Device-Id/device-id-缺失时服务端自动生成anon--连接方向设备主动连 ServerServer 不反向连设备下发)
所有消息本质上都是在三种状态之间推来推去：说句话，从空闲跳到播报中；说起来，听完话，从监听中跳回空闲；你插一句嘴，从播报中又跳回播报中。理解了这个状态机后很多现象就解释得通了。
如果你也在做差不多语音硬件，希望这篇能帮你少踩几个坑。踩坑清单已经帮你排好队了拿走不谢。话说回来，

连接建立与握手

设备侧发起连接

设备通过 mg_ws_connect 连接wss:///xiaohong/v1 。WebSocket 握手时携带：

• Device-Id / device-id : 如 MAC 地址形式 01:23:45:67:89:AB;
• Authorization / Protocol-Version 等附加头.;老实说，
• ⚠ N.B. 仅支持 ws:// 或 wss://；误填 http:// 会导致握手异常甚至崩溃。

再看见面先握手，你一句我一句。谁也不用等谁

步骤概览:.

1. 设备把 WebSocket 连上，并携带自己的 Device‑Id；
2. 服务器立刻丢过来一个 hello；按理说，
3. 当固件收到服务器 hello 后立即把自己的 hello 发出去；
4. 服务器收到后把该设备登记进在线列表。按理说，
   4. >> 两边谁都不用等谁 ——省掉来回延迟。使实时交互更流畅，

在这里可以看到两个最主要的数据字段：

• session_id: <- 一次会话的“身份证号”，每次发送都必须携带； 每个请求里都有这个字段，否则服务器无法定位对应的设备与上下文。

audio_params: 告诉对方当前本地声学参数。例如：

json

{ “format”: “opus”,“samplerate”: 24000,“channels”: 1,“frameduration”: 40 }

​  ​        ​​

第一步先叫“唤醒”：检测到关键词后即刻上报文字片段并开启监听模式。

`listen` 的三阶段流程如下：

• 检测 : 当麦克风捕获到唤醒词后即刻报告给服务器： json { 至于"type"。"listen","state":"detect","session_id":"uuid-xxxx","text":"你好" } 此时服务器将该通道切换为 Listening 状态，并清除之前任何残留的语音缓冲。

启动 : AI 主动发起 voice_listen 时服务器向设备下发 listen/start json { "type"的观点是。"listen","state":"start","session_id":"uuid-xxxx","mode":"auto" } 从此处开始，将连续上传 opus 帧。

停止 : 当检测到静音或使用者主动停止时上报： json { "type"的观点是。"listen","state":"stop","session_id":"uuid-xxxx" } 接下来把累计的完整语句交给后台 ASR 并返回结果给等待中的 AI 或广播给所有 AI。若无 AI 在等待，则按广播方式传播。注意: 若
中出现多余
或换行符。会导致解析错误，请保持 JSON 格式严格正确。使用者痛点: • 格式要如实上报 — 否则会出现“我传的是 opus，却是 PCM”的尴尬情况。• 别一听 stop 就闭嘴 — 必须让缓冲中的尾声完成播放才能真正关闭声音通道。这些细节往往是新接入者最容易踩掉的坑。

---

接下来叫“开始”：AI 调起 Listen 接口后开启实时录音流。

"当 AI 调用 `voice_listen` 后我方通过 `listen/start` 把录制功能打开，并以每秒约25~30 帧 opus 数据持续上传至云端。" 如果此时机器已经处于 Listening 状态，它将继续收集数据；否则，它会忽略旧任务并立即响应新任务。

至于半路想插话，打断这件事靠计数器实现精准抢占。

在同一个物理串口上，一个时间只能有一种声音正在播放或录取。当程序需要立即插播通知时它会执行以下流程：

• Abort 信号： 若正在监听，则直接抛弃那段未完成识别并发送 abort 命令；若正在播放，则立刻停止旧 TTS 而且关闭相关缓冲区。这样可以避免旧内容继续占用网络和 CPU 资源。

PlaySeq 编号机制：The server 为每一次新的 TTS 开始分配递增编号 play_seq。每个接收端在写入任何 OPUS 帧前都会检查当前有效编号是否与自身相同。如果不一致，则说明已有新的播报请求抢占优先级——此时立即停止写入剩余帧。不再产生混叠或重叠现象，

使用者痛点: • 老任务不能自行挂起 — 若旧任务未及时终止，你可能得到杂乱无章的混响效果。• 新任务必须优先 — 程序设计保证新播报始终抢占旧任务，无需额外逻辑判断。这些细节决定了多路流控是否平稳运行，也是大多数开发者遇到卡顿和延迟问题的根源。

---

至于屏幕上的字，让小 LCD 显示更多信息。话说回来，

`display` 消息让 AI 能直接在小 LCD 上写字或调整图标，包括：

json { 从"type"来看，"display","session_id": "","payload": { 再看"text"，"<文字内容>","status": "<顶部提示>"。"emoji": "<表情>","volume": "<电平值>",// 实际调音量，而非仅绘图形 // 可选 flag: // clear:true - 清屏后再写入新内容 // brightness:"high"/"low" } }

使用技巧:{text} 可以是任意长度，但建议短句可读性更好；{emoji} 必须为 Unicode emoji 字符。其 UTF‑8 长度 ≤4 字节，否则可能截断显示；{volume} 若不传则保持原始扬声器电平，但如果需要动态调节请务必确保硬件支持 PWM 调节。

---

设备心情三种状态汇总表格 – 一目了然！不过，

# 空闲 #	# 待命。可随时被唤醒或接受 TTS #	# 无 #	# none #	# 启动唤醒词 → listen/detect #

。

---