联犀开发者文档

MQTT 认证、Topic 与基础报文

约 1213 字大约 4 分钟

2026-10-17

本篇回答“设备连哪里、订阅什么、请求和应答怎样关联”。完成后，再选 MQTT＋UDP 或 MQTT＋WebRTC。纯文字改走 首个文字会话，不创建媒体。

连接前准备

平台提供 MQTT 地址、TLS 端口与可信 CA，产品下创建设备并取得 productID、deviceName 和设备密钥。真实地址与密钥由部署方安全下发；这里不提供可连接环境。设备不保存模型供应商密钥。

沿用设备 MQTT 认证：clientID 为 productID&deviceName；username 为 clientID;12010126;connid;expiry（connid 为本次连接随机标识，expiry 为过期 Unix 秒）。将平台保存的 Base64 设备密钥解码为原始字节，用它对整个 username 做 HMAC-SHA256，取十六进制结果；password 为 signature;hmacsha256。TLS 校验和系统时钟应先准备好，禁止把设备密钥或完整认证串写进日志。认证字段不是下面的业务 JSON。具体通用设备接入见 设备连接协议。

第一步：订阅后再发请求

通道设备发布设备订阅用途
signaling$thing/up/signaling/{productID}/{deviceName}$thing/down/signaling/{productID}/{deviceName}能力、会话、媒体和输入控制
message$thing/up/message/{productID}/{deviceName}$thing/down/message/{productID}/{deviceName}识别、回复、工具结果、异步消息
action$thing/up/action/{productID}/{deviceName}$thing/down/action/{productID}/{deviceName}设备物模型动作与执行回执

先确认订阅成功，再发布 capabilityReport。控制按 QoS 1、retained=false；重复投递是正常情况。身份取已认证 Topic，正文不得另指定设备身份。signaling/message 的信封没有 version 字段。使用 /ai 入口的设备按 AI 交互命令 独立完成流程，不将两套控制字段混入一个会话。

第二步：区分请求、应答和事件

下面是同一个能力请求及其应答。字段完整定义见 信封与关联规则、capabilityReport。

{
  "msgToken": "cap-S02",
  "method": "capabilityReport",
  "params": {
    "revision": 1,
    "purposes": [
      "aiConversation"
    ],
    "transports": [
      "udp"
    ],
    "supportedInteractionModes": [
      "halfDuplex"
    ],
    "aecMode": "none",
    "audio": {
      "format": "opus",
      "sampleRate": 16000,
      "channels": 1,
      "frameDuration": 20
    },
    "cameras": [],
    "features": [
      "audio",
      "udpReplyStartReceipt"
    ]
  }
}
{
  "msgToken": "cap-S02",
  "method": "requestAck",
  "code": 200,
  "data": {
    "requestMethod": "capabilityReport",
    "result": {
      "acceptedRevision": 1
    }
  }
}
你现在处理什么看什么下一步
请求msgToken、method、params保存等待项；会话内还要带顶层 sessionId
对应应答原 msgToken、应答 method、code、data200 才进入下一步，失败显示 data.reason；不能仅凭收到 MQTT 包认为成功
会话信令事件新 msgToken、sessionId、eventSeq、data按会话和接收端去重；不拿它抵消别人的等待项
内容事件sessionId、messageSeq、data.respId 等独立维护内容水位；最终文本替换增量，不重复拼接

普通请求10秒超时，最多原 token 重试2次；邀请30秒且不得超过 expiresAt，SDP/连通15秒，以命令契约为准。相同 token 不得换正文；超时只代表结果未知，不代表远端没执行。详细错误见 应答、幂等与顺序。

第三步：建立会话，而不是收到创建应答就开麦

图中每个控制箭头均对应 能力／会话命令、mediaState 或 requestAck，实际音频不在 MQTT 包里。平台邀请路径及接听规则见 公共主体流程。

怎么确认接入完成

同时记录“MQTT 认证及订阅成功、能力被接受、创建成功、媒体实际连通、sessionEstablished、实际收发”六项。结束时关闭本地采集和输出、撤销等待项并清理会话密钥；重连重新认证和上报能力，不能重放旧输入。浏览器／App 使用 已鉴权应用接口，不借用设备密钥连接这些 Topic。

更新日志

2026/10/17 03:27
查看所有更新日志
  • d04e1-docs(AI与音视频): 按公共主线与场景分支整合接入手册于