Skip to content
0
/ Source/StackChan
11/19/2026
5.5m

StackChan
​

StackChan 是一个 ESP32 机器人

AI Agent 的对话链路 ​

这里聚焦 MQTT + UDP 路径:MQTT 通过主题传递控制和文字,UDP 通道双向传递音频。图中将 MQTT Broker 与对话服务分开,便于看清消息转发和音频流向;它们在官方服务端如何部署,仓库没有公开。

各个环节处理什么 ​

环节输入输出源码可确认的范围
本地唤醒检测连续音频唤醒事件在 StackChan 上运行
语音处理与编码采集的音频Opus 音频帧在 StackChan 上运行
MQTTJSON 控制与文字消息会话配置、聆听控制、文字和状态等客户端收发与处理逻辑
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。

Released under the MIT License.