# 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` 字段。 通用请求格式: ```json {"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),可选热重启 | 示例 —— 下发 frpc 配置并立即生效: ```json {"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} ``` 示例 —— 状态查询响应: ```json {"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: ```json {"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: ```json {"jsonrpc":"2.0","method":"ctr_cam","params":{"ExporseTime":8000},"id":7} ``` 未知 method 回错误响应 `"unknown method: xxx"`。 ### 2.2 cmd/ext 风格 判定条件:存在 `cmd` 字段。 ```json {"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` | - | (预留,当前空实现) | 示例 —— 拍照: ```json {"cmd":"ctrl","ext":{"type":"takephoto"}} ``` --- ## 3. 上行协议(设备 → 服务器) 发布主题均为 `{mqtt_main_pub}{imei}`。 ### 3.1 上线通知 MQTT 连接成功后立即发布纯文本(非 JSON): ``` turnon ``` ### 3.2 告警/状态通知(warn) 由 `JsonFunc::MakeJsonWarn(status, type)` 构造: ```json {"cmd":"warn","ext":{"status":"<状态描述>","type":"<类型/补充信息>"}} ``` 典型场景:IMEI 变更通知、缓存数量回报、APK 下载开始等。 另有一类固定文本:`{"cmd":"warn","ext":{"status":"App DownLoad Start!"}}`(mqtthandler.cpp 内联构造)。 ### 3.3 心跳/同步上报(synchronization) 由 STM32 主板经串口触发(`BoardMessage()` 构造后走串口/MQTT 链路): ```json {"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 请求的应答: 成功: ```json {"jsonrpc":"2.0","id":42,"result":"mqtt1 config updated"} ``` 失败(统一错误码 -32603): ```json {"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":}` 发往**串口**(不经 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 遗嘱报文 ```json {"cmd":"offline","ext":{"imei":"<设备IMEI>"}} ``` QoS=1,retain=false,发布在 `{mqtt_main_offline}{imei}`。