StackChan
StackChan 是一个 ESP32 机器人
AI Agent 的对话链路
这里聚焦 MQTT + UDP 路径:MQTT 通过主题传递控制和文字,UDP 通道双向传递音频。图中将 MQTT Broker 与对话服务分开,便于看清消息转发和音频流向;它们在官方服务端如何部署,仓库没有公开。
各个环节处理什么
| 环节 | 输入 | 输出 | 源码可确认的范围 |
|---|---|---|---|
| 本地唤醒检测 | 连续音频 | 唤醒事件 | 在 StackChan 上运行 |
| 语音处理与编码 | 采集的音频 | Opus 音频帧 | 在 StackChan 上运行 |
| MQTT | JSON 控制与文字消息 | 会话配置、聆听控制、文字和状态等 | 客户端收发与处理逻辑 |
| UDP | 压缩音频帧 | 另一端收到的音频 | 客户端加密发送、接收解密逻辑 |
| 显示与播放 | 文字、情绪、回复音频 | 屏幕内容与声音 | 在 StackChan 上运行 |
OTA:获取更新信息和对话连接配置
StackChan 启动后,先向 OTA 接口报告设备信息和固件版本,再从响应中获取更新信息、激活信息,以及 MQTT 或 WebSocket 的连接配置。它在对话链路中的作用,是让设备知道接下来连接哪里、使用什么凭据。
OTA 全称是 Over-the-Air,指通过网络更新固件。这里的接口同时承担启动配置的职责;即使没有新固件,设备也可以继续使用返回的连接配置。
设备发送什么
默认请求地址是:
POST https://api.tenclass.net/xiaozhi/ota/请求头携带设备标识,请求体携带系统信息。下面只保留理解链路需要的字段,标识使用占位值:
Content-Type: application/json
Device-Id: <设备 MAC 地址>
Client-Id: <设备 UUID>{
"version": 2,
"application": {
"name": "stack-chan",
"version": "1.6.2"
},
"board": {
"type": "m5stack-stack-chan"
}
}这份请求告诉接口:“我是 StackChan,当前运行的固件是 1.6.2。”其中 application.version 是固件版本,顶层 version: 2 是请求数据的格式版本。1.6.2 来自本文阅读的 StackChan 构建配置。
接口返回什么
客户端收到 HTTP 200 后解析 JSON。下面是 MQTT 分支的结构示例,地址和凭据使用占位值,不是官方接口的实际返回:
{
"firmware": {
"version": "1.6.2",
"url": "https://firmware.example.com/stack-chan.bin"
},
"mqtt": {
"endpoint": "mqtt.example.com:8883",
"client_id": "<客户端 ID>",
"username": "<用户名>",
"password": "<密码>",
"publish_topic": "<发布主题>",
"keepalive": 240
}
}设备用 firmware.version 判断是否需要更新,用 firmware.url 获取固件下载地址;把 mqtt 配置保存到 NVS,随后用其中的地址与凭据建立 MQTT 连接。
如果接口提供 WebSocket 配置,对应部分长这样:
{
"websocket": {
"url": "wss://voice.example.com/dialogue",
"token": "<认证 token>",
"version": 1
}
}客户端同样保存这组配置。协议选择时,先检查 mqtt,没有它才检查 websocket,所以同时返回两者时会优先使用 MQTT。