MQTT 设备通信协议

tags: [IoT, MQTT, 协议, 嵌入式]
created: 2026-04-12
updated: 2026-05-15
sources: [raw/snippets/iot-docs/ref-mqtt.md, raw/snippets/iot-docs/guide-device.md, raw/snippets/iot-docs/architecture.md, raw/snippets/bk7258-build/iot-architecture-onboarding.md, raw/notes/2026-05-15-iot-agent-capability-decision-memo-v5-final.md]

定义¶

Sentino IoT 平台中设备与云端的信令通信协议，基于 MQTT 5.0。负责设备认证、绑定、状态上报、指令下发和获取 RTC 参数，不承载音频流。

关键要点¶

连接鉴权：Client ID 为 rlink_${uuid}_V2，Password 通过 HMAC-SHA256 签名 uuid=${uuid},ts=${ts} 计算
4 个 Topic：report（设备上报）、report_response（云端回复）、issue（云端下发）、issue_response（设备回复指令）
消息格式：JSON，通过 code 字段区分协议类型（bind、info、time、property_report、ota_progress、agora_agent_device_access 等）
9 种上报事件：bind、info、reset、time、model、property_report、ota_progress、agora_agent_device_access、agora_agent_nfc_report
4 种云端下发指令：reset、ota、ping、property_set
ack 机制：ack=1 时云端回复，ack=0 时不回复
断线重连：指数退避（1s → 2s → 4s → ... → 60s），重连后必须重新订阅 Topic 并上报 info
消息 ID 必须唯一，重复 ID 的消息被云端忽略
Broker 地址不在固件——mqtt-iot.sentino.jp:8883 由蓝牙配网时 APP 下发到设备 Flash，详见 iot-device-bootstrap
Keepalive 60s 是 WiFi 设计值。切换到 4G 形态时必须拉长到 ≤ 300s 但 < 运营商 NAT 超时（通常 5~10 分钟），同时省流量

业务链路示例（设备 ↔ 云完整调用链）¶

三条核心链路展示 MQTT 协议如何穿过 embedded-firmware-layering 业务/适配/SDK 三层：

链路 ①：APP 改音量 → 喇叭变音量（云 → 设备）¶

APP → HTTP → 云平台 → MQTT publish: {"code":"property_set","value":{"volume_set":7}}
→ rino_iot_sdk/rino_mqtt 解码 → 丢消息队列 → cmd_parse
→ Cmd_Property_Set_Parse_Cb (注入的 callback)
→ rino_interface/rino_mqtt_import_interface.c:161 Rino_Mqtt_Cmd_Property_Set_Parse_Import_Callback(dp)
→ projects/{产品}/main/rino_iot_process.c:262 case DPID_VOLUME_SET: Volume_Set_Abs(7,0); DP_Volume_Set_Report(7);
→ MQTT publish: $thing/.../property_report → 云平台更新 shadow → APP 看到音量已变

链路 ②：开机自动上报状态¶

rino_mqtt_app.c:108 Rino_Mqtt_Connected_Callback() → Rino_Mqtt_App_Ready_Cb()
→ 适配层启动时注入的 Device_Power_On_Report_Info()
→ DP_Bright_Value_Report(...) / DP_Switch_Status_Report(...)

→ SDK 暴露抽象 hook，业务函数叫什么名字 SDK 不知。

链路 ③：长按按键 → AI 对话启动（设备 → 云）¶

按键事件 → Rino_Device_Access_Export_Interface() → Mqtt_Event_Agora_Agent_Device_Access_Report(1)
→ rino_iot_sdk/ MQTT publish event payload
→ 云平台调 AI Agent → 申请 Agora RTC token → 应答推回设备
→ rino_mqtt_import_interface.c:95 Rino_Mqtt_Event_Respone_Agora_Agent_Device_Access_Parse_Import_Callback
   ├─ result==0 → set_agora_config(rtcToken, channelName, appId, uid)
   └─ result!=0 → app_event_send_msg(APP_EVT_ASR_WAKEUP_FAIL, 0)
→ app_agora_session_process.c 加入声网频道 → 开音视频对话

→ 完整链路展示了 MQTT 信令通道（agora_agent_device_access event）如何与 agora-rtc-voice 音频通道协作：MQTT 出 RTC 凭证，RTC 出音频流。

Capability 字段（Layer 2 方案 X，2026-05-15 v5 决策）¶

agora_agent_device_access 上报体可携带 data.capability: string[] 字段（设备实例当前支持的 executor 列表），IoT 平台收到后映射到 Sentino API /api/v1/conversations 请求的 device_info.supported_executors，由 Sentino API 在 chat 回调时跟 DragonFlow product.capability_config 做交集 → 注入 LLM tool calling schema。

→ 这是 iot-agent-capability-bridging Layer 2 方案 X（MQTT-on-start 透传）在 MQTT 协议层的体现。Layer 2 方案 Y（独立 capability_report code）/ 方案 Z（X+Y hybrid）也可叠加，由 IoT 团队自决。