MQTT_Protocol.md 9.0 KB

Q6 物联网终端 MQTT 协议文档

版本对应:APP 2.5.8 | 整理日期:2026-08-21 代码来源:src/mqtthandler.cpp(收发与分发)、src/m_json.cpp(报文构造)、src/main.cpp(信号接线)

1. 连接管理

项目 值 代码位置
Broker 地址/端口 数据库 table_mqtt 配置(param::mqtt_main_ip/port) mqtthandler.cpp L127-128
ClientID AndroidClient + IMEI mqtthandler.cpp L130
用户名/密码 数据库配置 mqtthandler.cpp L132-133
CleanSession false(会话保持) mqtthandler.cpp L137
KeepAlive 数据库配置,默认 60s mqtthandler.cpp L128
遗嘱(LWT) 见 §4.3,QoS=1,retain=false mqtthandler.cpp L138-142
断线重连 断开后 10 秒自动重连 mqtthandler.cpp L238
发布 QoS 0(所有上行消息) mqtthandler.cpp L172

1.1 主题(Topic)规则

所有主题 = 数据库配置前缀 + 设备 IMEI:

方向 主题 说明
订阅(下行) {mqtt_main_sub}{imei} 接收服务器指令
发布(上行) {mqtt_main_pub}{imei} 上报数据/响应
遗嘱(离线) {mqtt_main_offline}{imei} 异常掉线时由 Broker 代发

1.2 离线缓存与重传

  • JSON 上报失败 → SQLite 缓存(OfflineStorage),连接恢复后按批重传(批量大小=1)
  • 图片走 FTP 上传(不经 MQTT),失败同样入库缓存,60 秒定时器触发重传;文件已不存在的记录自动清除
  • 可通过 cache_enable/cache_read 指令远程查询/开关缓存

2. 下行协议(服务器 → 设备)

订阅主题收到消息后按两种风格解析,两者互斥:

2.1 JSON-RPC 2.0 风格(优先判定)

判定条件:同时含非空 jsonrpc + method(string) + id 字段。

通用请求格式:

{"jsonrpc":"2.0","method":"<方法名>","params":{...},"id":1}

方法列表

method params 必填 功能
setserver_mqtt1 ip,port,uid,pwd,pub,sub,lastwill,keepalive,qos,clientid ip, port 更新主通道 MQTT 配置 → 写数据库 → 触发重连
setserver_mqtt2 同上 ip, port 更新备通道 MQTT 配置
setserver_ftp1 ip,port,uid,pwd,dir ip, port 更新主通道 FTP(图片上传目标)
setserver_ftp2 同上 ip, port 更新备通道 FTP
upload_log filename 是 复制日志到临时目录并触发 FTP 上传
ctr_cam ExporseTime(int,微秒) 是 远程设置相机曝光时间
frpc_start toml(可选,内联配置) 否 启动 frpc 内网穿透;带 toml 时先保存再启动。result 为状态 JSON
frpc_stop -(params 可省略) 否 停止 frpc(SIGTERM→3s 后 SIGKILL)。result 为状态 JSON
frpc_status -(params 可省略) 否 查询 frpc 状态,result 为 JSON 字符串:running,pid,uptime_sec,last_exit_code,last_exit_crashed,config_exists,log_tail[]
frpc_config toml,restart(1=保存后重启) 是 保存 TOML 配置到设备(AppData/frpc.toml),可选热重启
fusion_sw enable(1=开 0=关) 否 景深(多焦点)融合开关:默认开。enable=0 时录制视频只分析最清晰帧并上传,跳过景深融合;省略 enable 为查询当前状态。参数持久化到 SQLite config.fusion_enable,重启保持

示例 —— 下发 frpc 配置并立即生效:

{"jsonrpc":"2.0","method":"frpc_config",
 "params":{"toml":"serverAddr = \"frps.example.com\"\nserverPort = 7000\nauth.token = \"xxx\"\n\n[[proxies]]\nname = \"ssh\"\ntype = \"tcp\"\nlocalIP = \"127.0.0.1\"\nlocalPort = 22\nremotePort = 6022",
           "restart":1},
 "id":9}

示例 —— 状态查询响应:

{"jsonrpc":"2.0","id":3,"result":"{\"running\":true,\"pid\":12345,\"uptime_sec\":120,
 \"last_exit_code\":0,\"last_exit_crashed\":false,\"config_exists\":true,
 \"log_tail\":[\"[I] [ssh] start proxy success\"]}"}

示例 —— 设置主通道 MQTT:

{"jsonrpc":"2.0","method":"setserver_mqtt1",
 "params":{"ip":"mqtt.example.com","port":1883,"uid":"u","pwd":"p",
           "pub":"/yfkj/s2c/","sub":"/yfkj/c2s/","lastwill":"/yfkj/offline/",
           "keepalive":60,"qos":0,"clientid":"dev001"},
 "id":42}

示例 —— 设置相机曝光 8000μs:

{"jsonrpc":"2.0","method":"ctr_cam","params":{"ExporseTime":8000},"id":7}

示例 —— 关闭景深融合(只出最清晰帧,缩短处理耗时):

{"jsonrpc":"2.0","method":"fusion_sw","params":{"enable":0},"id":1}

响应:"fusion disabled";开启回 "fusion enabled";查询(不带 enable)回 "fusion_enable=1"。 写库失败时仍即时生效,但响应为错误 "fusion set, but db save failed",需排查数据库。

未知 method 回错误响应 "unknown method: xxx"。

2.2 cmd/ext 风格

判定条件:存在 cmd 字段。

{"cmd":"<命令>","ext":{...}}
cmd ext 功能
reboot - 转发串口 → 主板重启
dtu_reboot - 设备(Android)系统重启
update - 下载主板 rbl 固件并升级(转发串口)
dtu_update - 下载新版本 APK(先回 warn "App DownLoad Start!")
app_update - 安装已下载的 APK(延时 5s 执行)
ctrl type:"auto_takephoto" 启动自动拍照流程(多图采集)
ctrl type:"takephoto" 延时 10s 拍单张照并上传
setimei imei:"xxx" 修改设备 IMEI 并回发 warn 通知
paramconf / read / ledon / ledoff / windon / windoff / translate / takephoto / slide / sensor 各异 原样转发串口给 STM32 主板处理
cache_read type:"data"\|"photo" 查询缓存条数,回 warn
cache_enable type:"data"\|"photo", enable:0\|1 开关离线缓存,回 warn
cache_restore - (预留,当前空实现)

示例 —— 拍照:

{"cmd":"ctrl","ext":{"type":"takephoto"}}

3. 上行协议(设备 → 服务器)

发布主题均为 {mqtt_main_pub}{imei}。

3.1 上线通知

MQTT 连接成功后立即发布纯文本(非 JSON):

turnon

3.2 告警/状态通知(warn)

由 JsonFunc::MakeJsonWarn(status, type) 构造:

{"cmd":"warn","ext":{"status":"<状态描述>","type":"<类型/补充信息>"}}

典型场景:IMEI 变更通知、缓存数量回报、APK 下载开始等。 另有一类固定文本:{"cmd":"warn","ext":{"status":"App DownLoad Start!"}}(mqtthandler.cpp 内联构造)。

3.3 心跳/同步上报(synchronization)

由 STM32 主板经串口触发(BoardMessage() 构造后走串口/MQTT 链路):

{"cmd":"synchronization","ext":{
    "proj":"Android11",       // 平台标识
    "dver":"2.5.8",           // APP 版本(APP_VERSION)
    "gps":"1",                // GPS 状态
    "lat":"31.2304",          // 纬度
    "lng":"121.4737",         // 经度
    "net":"0",                // 网络:0=在线 1=离线
    "iccid":"...",            // SIM ICCID
    "datetime":"20260821161210",
    "imei":"862289057468809",
    "csq":"良好"              // LTE RSRP 档位:优秀/良好/一般/差/NoSignal
}}

3.4 JSON-RPC 2.0 响应

对 §2.1 请求的应答:

成功:

{"jsonrpc":"2.0","id":42,"result":"mqtt1 config updated"}

失败(统一错误码 -32603):

{"jsonrpc":"2.0","id":42,"error":{"code":-32603,"message":"ip and port are required"}}

3.5 数据透传

  • 主板 → 云:SerialThread::dataUpload 直通 publish_m(传感器等板载数据)
  • 相机模块 → 云:Frames::dataUpload 直通 publish_m
  • 相机模块 → 主板:清晰度结果 {"focus":<Tenengrad值>} 发往串口(不经 MQTT)

4. 附录

4.1 完整交互时序

Server                          Device (Android)
  |---- turnon ----------------->|  (设备上线, 纯文本)
  |<--- synchronization ---------|  (周期状态上报)
  |---- {"method":"ctr_cam"} --->|  (JSON-RPC 设置曝光)
  |<--- {"result":"exposure..."}-|  (同步响应)
  |---- {"cmd":"ctrl",...} ----->|  (拍照指令)
  |     (图片经 FTP 上传,不走 MQTT)
  |<--- warn --------------------|  (各环节状态通知)
  |  x  设备异常掉线
  |<--- offline(遗嘱) -----------|  (Broker 代发)

4.2 注意事项

  1. 下行指令判重:CleanSession=false + QoS0 订阅,断线期间的指令不会补发;需要可靠送达的指令建议服务端自行重试或改用 RPC 带 id 的方式轮询
  2. cache_restore 为空实现,下发无效果
  3. 遗嘱消息在连接时被追加 IMEI:param::mqtt_main_offline += imei(L134),重复调用 connectToBroker() 会多次拼接——当前仅启动时连接一次不受影响,但远程切换 MQTT 后重连需留意
  4. 图片/日志均走 FTP 上传,MQTT 仅传控制流与轻量状态

4.3 遗嘱报文

{"cmd":"offline","ext":{"imei":"<设备IMEI>"}}

QoS=1,retain=false,发布在 {mqtt_main_offline}{imei}。