定义¶

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 出音频流。

相关概念¶

• iot-platform-fundamentals — MQTT 在 IoT 协议栈中的位置（vs CoAP/LwM2M/HTTP/Modbus）
• iot-device-bootstrap — Broker 地址来源（WiFi 蓝牙下发 vs 4G 5 种方案）
• embedded-firmware-layering — 业务链路示例展示的 SDK ↔ 适配 ↔ 业务三层穿透
• sentino-iot
• device-lifecycle
• agora-rtc-voice
• ble-provisioning