# Q6 物联网终端 MQTT 协议手册 > **适用固件**:APP `2.8.26`(见 `header/main.h` 的 `APP_VERSION`) > **修订日期**:2026-10-21 > **代码依据**:`src/mqtthandler.cpp`(连接/收发/分发)、`src/m_json.cpp`(报文构造)、`src/mserial.cpp`(主板串口)、`src/frpcmanager.cpp`(内网穿透)、`src/app_sq_save.cpp`(离线缓存)、`src/main.cpp`(信号接线) > > **编写方式**:**一条指令一节**。每节固定给出「用途 → 属性表 → 参数表 → 请求 JSON → 响应 JSON → 使用说明」,报文示例可直接复制联调。 ## 目录 | 章节 | 内容 | 指令数 | |---|---|---| | 1 | 连接与报文约定(主题、两种风格、应答、缓存重传) | — | | 2 | 下行指令(服务器 → 设备) | 32 条 | | 3 | 上行报文(设备 → 服务器) | 5 类 | | 4 | 速查表与附录(时序、实现差异、串口报文对照) | — | --- ## 1 连接与报文约定 ### 1.1 连接参数 | 项目 | 取值 | 说明 | |---|---|---| | Broker 地址/端口 | 数据库 `table_mqtt` 的 `ip` / `port` | 由 `setserver_mqtt1` 远程下发(§2.1.1) | | ClientID | **固定规则** `AndroidClient` + IMEI | 服务端下发的 `clientid` 只落库,不参与连接 | | 用户名/密码 | `table_mqtt` 的 `uid` / `pwd` | — | | CleanSession | `false` | 会话保持 | | KeepAlive | `table_mqtt` 的 `keepalive`,默认 60 s | — | | 遗嘱(LWT) | 主题 `{offline 前缀}{imei}`,报文见 §3.5 | QoS 1,retain = false | | 断线重连 | 断开后 **10 s** 自动重连(无退避、无限次) | `onDisconnected()` → `reConnect()` | | 订阅 QoS | 0 | 设备订阅下行主题 | | 发布 QoS | **0** | 所有上行,含 JSON-RPC 应答 | | 应用层心跳 | 无 | 在线判定依赖 MQTT KeepAlive + `data` 周期上报 | ### 1.2 主题(Topic) 主题 = 配置前缀 + 设备 IMEI(前缀由 `setserver_mqtt1` 下发)。以 IMEI `862289057468809` 为例: | 方向 | 主题模板 | 示例 | 说明 | |---|---|---|---| | 设备订阅(下行) | `{sub}{imei}` | `/yfkj/bzy/2_1/s2c/862289057468809` | 平台向设备下发指令 | | 设备发布(上行) | `{pub}{imei}` | `/yfkj/bzy/2_1/c2s/862289057468809` | 设备上报数据与应答 | | 遗嘱(离线) | `{lastwill}{imei}` | `/yfkj/bzy/2_1/offline/862289057468809` | 异常掉线时 Broker 代发 | > 命名约定:`sub` 前缀对应云端 **s2c**(server → client),`pub` 前缀对应云端 **c2s**(client → server);配置反了会导致双向都收不到报文。 ### 1.3 下行报文的两种风格 设备按以下顺序判定,**同一条报文不要混用两种风格**: | 顺序 | 风格 | 判定条件 | 是否应答 | 典型用途 | |---|---|---|---|---| | 1 | JSON-RPC 2.0 | 同时含非空 `jsonrpc`、`method`(字符串)、`id` | **是**,同 `id` 回包 | 配置下发、状态查询、运维操作 | | 2 | cmd/ext | 含 `cmd` 字段 | 否(仅可能回 `warn`) | 动作指令、透传主板 | > 实现细节:RPC 分支执行完后**不会**跳过 `cmd` 分支。一条报文若同时带 `method` 和 `cmd`,两个分支都会执行(§4.3 第 7 条),平台侧请勿混发。 ### 1.4 应答与错误 JSON-RPC 指令的应答统一为以下两种形态,`id` 与请求一致: **成功** ```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"}} ``` | 项目 | 说明 | |---|---| | `result` 类型 | 字符串。`frpc_*` 的 `result` 是**JSON 字符串**,平台需二次解析(§2.6.4) | | 未知 method | 回 `error`,`message` 为 `unknown method: xxx` | | 超时建议 | 平台按 10 s 未收到应答即判失败:配置类指令幂等、可重发;动作类(`ctrl`)不要自动重试 | | cmd 风格 | 无 RPC 应答,只能通过后续 `warn` / `data` 观察结果 | ### 1.5 离线缓存与重传 | 数据 | 缓存条件 | 存储与上限 | 重传策略 | |---|---|---|---| | JSON 上报 | 发布失败,或连接断开(`warn` 除外) | SQLite `json_messages`,上限 **1000** 条,默认开启 | 每次成功发布后顺带重传 **1** 条 | | 图片 | FTP 上传失败 | 重命名 `history-*.jpg` 入 `image_messages`,上限 **500** 条,默认开启 | 60 s 定时器,每次传 **1** 张;文件已不存在则清记录 | | `warn` | **不缓存** | — | 连接断开期间直接丢弃 | | 日志 | 不走 MQTT | 复制临时副本后走 FTP | 由 `upload_log` 触发(§2.6.5) | 缓存开关与条数可远程查询/设置,见 §2.7.1、§2.7.2。 ### 1.6 数据通路 ``` c2s 主题(设备发布) ┌──────────┐ ◄────────────────────── ┌───────────────┐ │ MQTT │ │ │──► 相机(拍照/录像/融合) │ Broker │ ──────────────────────► │ MqttHandler │──► 串口(STM32 主板) └──────────┘ s2c 主题(设备订阅) │ │──► QML 界面 └───────────────┘ ``` - 串口收到的 `cmd:data`、部分 `warn` 由 `SerialThread::dataUpload` 直通 MQTT - 相机清晰度结果 `{"focus":}` 只发串口,**不经 MQTT** - 图片、日志文件走 FTP,不经 MQTT --- ## 2 下行指令(服务器 → 设备) ### 2.1 服务器配置 #### 2.1.1 `setserver_mqtt1` — 修改主通道 MQTT 服务器 **用途**:更新设备连接的主 MQTT 服务器地址、账号与主题前缀。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "mqtt1 config updated"` | | 生效方式 | 写入内存 + `table_mqtt`;**不主动断开重连** | | 代码位置 | `mqtthandler.cpp` L279 / `handleMqttConfig()` | **参数(`params`)** | 字段 | 类型 | 必填 | 默认 | 说明 | |---|---|---|---|---| | `ip` | string | **是** | — | Broker 地址 | | `port` | int | **是** | — | Broker 端口 | | `uid` | string | 否 | 空 | 用户名 | | `pwd` | string | 否 | 空 | 密码 | | `pub` | string | 否 | 空 | 上行主题前缀,设备自动追加 IMEI | | `sub` | string | 否 | 空 | 下行主题前缀,设备自动追加 IMEI | | `lastwill` | string | 否 | 空 | 遗嘱主题前缀,设备自动追加 IMEI | | `keepalive` | int | 否 | 60 | 心跳秒数 | | `qos` | int | 否 | 0 | 仅落库;发布始终 QoS 0 | | `clientid` | string | 否 | 空 | 仅落库;连接仍用 `AndroidClient+IMEI` | **请求 JSON** ```json { "jsonrpc": "2.0", "method": "setserver_mqtt1", "params": { "ip": "117.190.40.178", "port": 1883, "uid": "admin", "pwd": "1", "pub": "/yfkj/bzy/2_1/c2s/", "sub": "/yfkj/bzy/2_1/s2c/", "lastwill": "/yfkj/bzy/2_1/offline/", "keepalive": 60, "qos": 0, "clientid": "" }, "id": 42 } ``` **成功响应** ```json {"jsonrpc":"2.0","id":42,"result":"mqtt1 config updated"} ``` **失败响应**(缺 `ip` 或 `port`) ```json {"jsonrpc":"2.0","id":42,"error":{"code":-32603,"message":"ip and port are required"}} ``` **使用说明** - `id` 必须放在**顶层**,写在 `params` 里无效(旧版示例中的 `params.id` 会被忽略)。 - 缺省字段会被**覆盖为空值/默认值**,不是"保持原值"。只改 ip 时也要把 `pub`/`sub` 一并带上。 - 下发后当前连接**不会切换**:设备仍连着旧 Broker,直到断开触发 10 s 自动重连,或重启设备。需要立即生效可紧接着下发 `dtu_reboot`(§2.5.2)。 - 该指令无数据库失败回执:即便写库失败也回 `result`,重启后会回退到旧配置。 #### 2.1.2 `setserver_mqtt2` — 修改备通道 MQTT 服务器 **用途**:保存备用 MQTT 服务器配置(预留通道)。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "mqtt2 config updated"` | | 生效方式 | 写入内存 + `table_mqtt_other`;**当前版本不用于连接** | | 代码位置 | `mqtthandler.cpp` L282 / `handleMqttConfig(channel=2)` | **参数**:与 §2.1.1 完全一致。 **请求 JSON** ```json { "jsonrpc": "2.0", "method": "setserver_mqtt2", "params": { "ip": "117.190.40.179", "port": 1883, "uid": "admin", "pwd": "1", "pub": "/yfkj/bzy/2_1/c2s/", "sub": "/yfkj/bzy/2_1/s2c/", "lastwill": "/yfkj/bzy/2_1/offline/", "keepalive": 60, "qos": 0, "clientid": "" }, "id": 43 } ``` **成功响应** ```json {"jsonrpc":"2.0","id":43,"result":"mqtt2 config updated"} ``` **使用说明** - 备通道目前**只存不用**:代码中没有主备切换逻辑,下发后设备仍只连主通道。 - 平台可把它当作"异地容灾配置暂存区"使用,切换需人工/后续版本支持。 #### 2.1.3 `setserver_ftp1` — 修改主通道 FTP(图片上传目标) **用途**:更新图片/日志上传的 FTP 服务器,**下一条上传即生效**。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "ftp1 config updated"` | | 生效方式 | 写入内存 + `table_ftp`;重传任务同样读取新配置 | | 代码位置 | `mqtthandler.cpp` L285 / `handleFtpConfig()` | **参数(`params`)** | 字段 | 类型 | 必填 | 默认 | 说明 | |---|---|---|---|---| | `ip` | string | **是** | — | FTP 地址 | | `port` | int | **是** | 21 | FTP 端口 | | `uid` | string | 否 | 空 | 账号 | | `pwd` | string | 否 | 空 | 密码 | | `dir` | string | 否 | 空 | 上传根目录前缀,如 `BZYV21/` | **请求 JSON** ```json { "jsonrpc": "2.0", "method": "setserver_ftp1", "params": { "ip": "8.136.98.49", "port": 21, "uid": "bzy_user", "pwd": "YFkj@6O2O", "dir": "BZYV21/" }, "id": 44 } ``` **成功响应** ```json {"jsonrpc":"2.0","id":44,"result":"ftp1 config updated"} ``` **失败响应** ```json {"jsonrpc":"2.0","id":44,"error":{"code":-32603,"message":"ip and port are required"}} ``` **使用说明** - 图片实际路径为 `{dir}/{设备ID}/{采集时间}/xxx.jpg`,`dir` 只作根前缀。 - 改完立即影响新上传与 60 s 重传;**已入库的失败图片会传到新服务器**,切换前请确认新目录可写。 - 端口留空时按 21 处理。 #### 2.1.4 `setserver_ftp2` — 修改备通道 FTP **用途**:保存备用 FTP 配置。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "ftp2 config updated"` | | 生效方式 | 写入内存 + `table_ftp_other`;当前版本不用于上传 | | 代码位置 | `mqtthandler.cpp` L288 / `handleFtpConfig(channel=2)` | **参数**:与 §2.1.3 一致。 **请求 JSON** ```json { "jsonrpc": "2.0", "method": "setserver_ftp2", "params": { "ip": "8.136.98.50", "port": 21, "uid": "bzy_user", "pwd": "YFkj@6O2O", "dir": "BZYV21/" }, "id": 45 } ``` **成功响应** ```json {"jsonrpc":"2.0","id":45,"result":"ftp2 config updated"} ``` **使用说明**:当前无上传失败自动切换备通道的逻辑,仅作配置留存。 --- ### 2.2 相机与图像 #### 2.2.1 `ctr_cam` — 远程设置相机曝光 **用途**:远程调整相机曝光时间,用于现场过曝/欠曝时的快速修正。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "exposure updated"` | | 生效方式 | 立即作用于当前相机 | | 代码位置 | `mqtthandler.cpp` L355 | **参数(`params`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `ExporseTime` | int | **是** | 曝光时间,单位**微秒**。字段名是协议约定,拼写就是 `Exporse`,不能改成 `Exposure` | **请求 JSON** ```json {"jsonrpc":"2.0","method":"ctr_cam","params":{"ExporseTime":8000},"id":7} ``` **成功响应** ```json {"jsonrpc":"2.0","id":7,"result":"exposure updated"} ``` **使用说明** - 8000 ≈ 8 ms,常用区间 3000–20000 μs;超出相机支持范围时由相机 SDK 钳制,应答仍为成功。 - 该接口**不回读**实际生效值。需要确认效果请让设备重拍一张,或在平台侧比对图片亮度。 - 参数缺失时按 0 处理(等价于最短曝光),平台务必显式传值。 #### 2.2.2 `fusion_sw` — 景深(多焦点)融合开关 **用途**:开关景深融合。关闭后录制视频只分析最清晰帧并上传,跳过融合,处理耗时显著缩短。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,文本随动作不同(见下) | | 持久化 | `config.fusion_enable`,重启保持;**默认开启** | | 代码位置 | `mqtthandler.cpp` L365 | **参数(`params`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `enable` | int | 否 | `1` 开启 / `0` 关闭;**省略则为查询当前状态** | **请求 JSON —— 关闭** ```json {"jsonrpc":"2.0","method":"fusion_sw","params":{"enable":0},"id":1} ``` **请求 JSON —— 开启** ```json {"jsonrpc":"2.0","method":"fusion_sw","params":{"enable":1},"id":1} ``` **请求 JSON —— 查询(`params` 可整个省略)** ```json {"jsonrpc":"2.0","method":"fusion_sw","id":1} ``` **响应** | 场景 | 响应 | |---|---| | 关闭 | `{"jsonrpc":"2.0","id":1,"result":"fusion disabled"}` | | 开启 | `{"jsonrpc":"2.0","id":1,"result":"fusion enabled"}` | | 查询 | `{"jsonrpc":"2.0","id":1,"result":"fusion_enable=1"}` | | 写库失败 | `{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"fusion set, but db save failed"}}` | **使用说明** - 写库失败时开关**已即时生效**,只是重启后会回退;收到该错误应排查设备数据库(`config.db`)。 - 任何非 0 值都按开启处理(`2`、`-1` 等价于 `1`)。 - 关闭融合只影响后续录制任务,正在处理的任务不中断。 --- #### 2.2.3 `focus_algo` — 对焦/融合算法选择 **用途**:在「帧清晰度评分」与「景深融合」两条链路上切换算法。两处用的是**同一套**焦点度量,切换后判据始终一致。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,回显生效后的算法(见下) | | 持久化 | `config.focus_algo`,重启保持;**默认 `0`(SLView GFF)** | | 代码位置 | `mqtthandler.cpp` `focus_algo` 分支;算法实现见 `src/slview_focus.cpp` | **参数(`params`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `algo` | int | 否 | `0`=SLView 引导滤波融合 GFF(默认)
`1`=SLView 多尺度金字塔融合 MS
`2`=原程序算法(AGD 多尺度权重 + Laplacian/Tenengrad/Brenner 加权评分)
**省略则为查询当前算法**;越界值直接拒绝,不改动配置 | **算法对照** | algo | 帧评分(选最清晰帧/圈有效对焦区间) | 融合链路 | 特点 | |---|---|---|---| | `0` GFF | `getEdge` 焦点图均值 | 缩图测焦点 → one-hot → 引导滤波软化权重 → 上采样归一化加权 | 边界贴合真实边缘、无半透明鬼影;内存最省 | | `1` MS | `getEdge` 焦点图均值 | 拉普拉斯金字塔逐层「幅值大者胜」,低频取均值后重建 | 细节最锐,耗时与内存最高 | | `2` 旧算法 | Laplacian 方差 + Tenengrad + Brenner 加权 | AGD 多尺度权重 + 大 σ 平滑 + 一致性校验 | 兼容回退用,现象与 2.8.30 及以前一致 | **请求 JSON —— 切到多尺度融合** ```json {"jsonrpc":"2.0","method":"focus_algo","params":{"algo":1},"id":1} ``` **请求 JSON —— 回退旧算法** ```json {"jsonrpc":"2.0","method":"focus_algo","params":{"algo":2},"id":1} ``` **请求 JSON —— 查询(`params` 可整个省略)** ```json {"jsonrpc":"2.0","method":"focus_algo","id":1} ``` **响应** | 场景 | 响应 | |---|---| | 设为 GFF | `{"jsonrpc":"2.0","id":1,"result":"focus_algo=0 (gff)"}` | | 设为 MS | `{"jsonrpc":"2.0","id":1,"result":"focus_algo=1 (ms)"}` | | 设为旧算法 | `{"jsonrpc":"2.0","id":1,"result":"focus_algo=2 (legacy)"}` | | 查询 | `{"jsonrpc":"2.0","id":1,"result":"focus_algo=0 (gff)"}` | | 取值越界 | `{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"invalid algo, expect 0(gff) 1(ms) 2(legacy)"}}` | | 写库失败 | `{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"focus_algo set, but db save failed"}}` | **使用说明** - 写库失败时算法**已即时生效**,只是重启后会回退;收到该错误应排查设备数据库(`config.db`)。 - 切换只影响**后续**的分析/融合任务;正在处理的任务按启动时的算法跑完。 - 算法切换会改变"最清晰帧"的判定结果(评分量纲不同),历史结果无法直接与切换后的评分数值比较。 - `algo=2` 是回退通道:现场若发现新算法对某类样本(如极低对比度涂片)不如旧行为,可整体退回。 - 该指令与 `fusion_sw` 相互独立:`fusion_sw=0` 时整条融合链路跳过,`focus_algo` 只影响最清晰帧的评分方式。 --- ### 2.3 拍照与运动控制 #### 2.3.1 `ctrl` / `auto_takephoto` — 启动自动拍照(多图采集 + 融合) **用途**:让设备自动完成"多焦点采集 → 景深融合 → FTP 上传"整套流程,是常规采集入口。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | cmd/ext | | 设备应答 | 无 RPC 应答,过程用 `warn` 通知 | | 执行内容 | 清空图片列表 → 跳转相机页 → 自动对焦/多位置拍照 → 融合 → 上传 | | 代码位置 | `mqtthandler.cpp` L454 | **参数(`ext`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `type` | string | **是** | 固定 `auto_takephoto`(判定为 `contains`,实际解析用包含匹配) | **请求 JSON** ```json {"cmd":"ctrl","ext":{"type":"auto_takephoto"}} ``` **设备侧后续上行** ```json {"cmd":"warn","ext":{"status":"takephoto_done","type":"auto_takephoto"}} ``` **使用说明** - 采集期间设备会切到相机页,界面不可操作属正常现象。 - 图片不走 MQTT:上传成功后平台在 FTP 目录取图;失败则入离线缓存等重传。 - 该指令**不幂等**:重复下发会中断当前采集并重新开始,采集期间请勿连发。 - 平台可通过 `data` 中的 `tape_used` 观察采集消耗。 #### 2.3.2 `ctrl` / `takephoto` — 单张拍照 **用途**:延时 10 秒拍单张照片并上传,用于远程抽查或补拍。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | cmd/ext | | 设备应答 | 无 RPC 应答 | | 执行时序 | 立即打开相机页 → **10 s 后**触发拍摄 → 上传 | | 代码位置 | `mqtthandler.cpp` L461 | > 与 `auto_takephoto` 的时序差异:本指令先打开相机界面,**固定延时 10 s** 后才触发单张拍摄;拍摄结果经 FTP 上传,MQTT 侧无同步回执。 **参数(`ext`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `type` | string | **是** | 固定 `takephoto`(使用精确相等判定) | **请求 JSON** ```json {"cmd":"ctrl","ext":{"type":"takephoto"}} ``` **使用说明** - 相机打开后约 10 s 完成拍摄,期间请勿重复下发,以免叠加多次触发。 - 与 `auto_takephoto` 的区别:本指令只拍一张,不做多焦点融合。 #### 2.3.3 `slide` — 远程校准 / 滑台运动 **用途**:远程触发相机打开并进入校准界面;同时把整条报文透传给主板执行电机动作。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | cmd/ext | | 设备应答 | 无 | | 设备动作 | `calibrate == "y"` 时跳转相机界面并打开相机;无论是否校准都会转发串口 | | 代码位置 | `mqtthandler.cpp` L488 | **参数(`ext`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `calibrate` | string | 否 | `"y"` 触发相机界面;其他值只做串口透传 | | `speed` | string | 否 | 电机速度,透传给主板 | | `movx` / `movy` / `movz` | string | 否 | 轴运动量,透传给主板 | **请求 JSON —— 远程校准** ```json {"cmd":"slide","ext":{"calibrate":"y","speed":"50"}} ``` **请求 JSON —— 仅轴运动(透传)** ```json {"cmd":"slide","ext":{"movy":"f100","speed":"50"}} ``` **使用说明** - `calibrate` 只认小写 `"y"`,`"Y"`、`true` 均不触发界面跳转。 - 校准会打断当前采集任务,建议在设备空闲时下发。 - 电机运动依赖主板固件解析 `movx/movy/movz`,字段含义见主板协议。 #### 2.3.4 `takephoto` — 主板拍照(透传) **用途**:转发给主板执行其原生拍照流程,兼容老平台指令。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 主题 | `{sub}{imei}` | | 报文风格 | cmd/ext | | 设备应答 | 无,主板执行后可能回 `warn` 或同 `cmd` | | 处理方式 | 原样转发串口,APP 不做业务处理 | | 代码位置 | `mqtthandler.cpp` L508 | **请求 JSON** ```json {"cmd":"takephoto"} ``` **使用说明** - 新平台请优先使用 `ctrl` / `auto_takephoto`(§2.3.1),本指令仅为兼容保留。 - 主板回 `{"cmd":"takephoto"}` 时 APP 只做内部完成通知,**不再上行**;如需可观测,请用 `ctrl` 系列。 --- ### 2.4 板载外设(串口透传) > 本节指令 APP **不解析 `ext`**,只校验 `cmd` 后整条报文转发给 STM32 主板;执行结果通过主板 `data` / `warn` 回传。 #### 2.4.1 `ledon` / `ledoff` — 补光灯开关 **用途**:打开/关闭相机补光灯。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无 | | 处理方式 | 原样转发串口 | | 代码位置 | `mqtthandler.cpp` L501 | **请求 JSON** ```json {"cmd":"ledon"} ``` ```json {"cmd":"ledoff"} ``` **使用说明** - 无需 `ext`,带了也会忽略。 - 补光灯常用于辅助对焦;采集结束后应主动 `ledoff`,避免长期点亮影响孢子活性观察。 #### 2.4.2 `windon` / `windoff` — 采集风机开关 **用途**:控制采集风机启停。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无(风机电流变化体现在 `data.fan_current`) | | 处理方式 | 原样转发串口 | | 代码位置 | `mqtthandler.cpp` L505 | **请求 JSON** ```json {"cmd":"windon"} ``` ```json {"cmd":"windoff"} ``` **使用说明** - 风机是否真的转起来,用下一条 `data` 的 `fan_current` 判断(0 或异常低值说明未启动)。 - 长时间运行建议周期性开关,避免风机过热。 #### 2.4.3 `translate` — 胶带电机走带 **用途**:驱动胶带电机转动(换带、走带测试)。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无(主板回 `warn` status 含 `translate` 时转发) | | 处理方式 | 原样转发串口 | | 代码位置 | `mqtthandler.cpp` L507 | **请求 JSON** ```json {"cmd":"translate"} ``` **使用说明** - 走带量由主板固件决定,APP 不下发步长。 - 走带后 `data.tape_used` 会增加,可用于核对胶带消耗是否正常。 #### 2.4.4 `read` — 请求主板数据(兼容) **用途**:要求主板立即回一帧 `data`。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 间接:主板回 `cmd:data`,APP 转发 MQTT | | 处理方式 | 转发串口,并将下一帧 `data` 标记为需上报 | | 代码位置 | `mqtthandler.cpp` L502 / `mserial.cpp` `mqtttoserial()` | **请求 JSON** ```json {"cmd":"read"} ``` **使用说明** - APP 内部定时轮询已改用 `synchronization`(串口报文,见 §4.4),本指令仅兼容老平台。 - 主板数据默认每 `dat_f` 分钟上报一次(默认 10 分钟);下发 `read` 可立即催一帧。 #### 2.4.5 `paramconf` — 采集参数配置 **用途**:配置三段采集时段、初始坐标、温控阈值,主板保存后生效。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 间接:主板回 `data` 携带新参数 | | 处理方式 | 原样转发串口;APP 收到 `data` 后同步界面与本地库 | | 代码位置 | `mqtthandler.cpp` L501 | **参数(`ext`,4 种形态可分别下发,也可合并)** | 字段 | 类型 | 说明 | 示例 | |---|---|---|---| | `coll_time` | string[3] | 三段采集的**起止小时** | `["8-10","12-14","16-18"]` | | `coll_min` | string[3] | 三段采集的**起止分钟** | `["0-30","0-30","0-30"]` | | `x_init_dis` | int | X 轴初始位置 | `1300` | | `y_init_dis` | int | Y 轴初始位置 | `1600` | | `tpl` | int | 低温保护阈值(℃) | `5` | | `tph` | int | 高温保护阈值(℃) | `70` | **请求 JSON —— 设置采集时段** ```json {"cmd":"paramconf","ext":{"coll_time":["8-10","12-14","16-18"]}} ``` **请求 JSON —— 设置时段分钟** ```json {"cmd":"paramconf","ext":{"coll_min":["0-30","0-30","0-30"]}} ``` **请求 JSON —— 设置初始坐标** ```json {"cmd":"paramconf","ext":{"x_init_dis":1300,"y_init_dis":1600}} ``` **请求 JSON —— 设置温控阈值** ```json {"cmd":"paramconf","ext":{"tpl":5,"tph":70}} ``` **使用说明** - `coll_time` 与 `coll_min` 建议**成对下发**:APP 侧只在两者都存在时才解析显示采集时段(`HomePage.qml`),只改其一会造成界面时间段错位。 - 阈值单位是摄氏度,需保证 `tpl < tph`;写反可能导致主板一直处于温控保护(`data.tps = "1"`)而不采集。 - 参数落到主板后,APP 仅在收到 `data` 时同步;若坐标被读成 0,APP 会自动触发参数恢复(见 §4.4 `recover_param`)。 #### 2.4.6 `sensor` — 传感器透传 **用途**:把平台自定义的传感器指令原样交给主板,由主板固件解释。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 由主板决定(通常回 `data`) | | 处理方式 | 原样转发串口 | | 代码位置 | `mqtthandler.cpp` L509 | **请求 JSON** ```json {"cmd":"sensor","ext":{"type":"env"}} ``` **使用说明** - `ext` 结构**由主板固件定义**,APP 不校验、不改写;平台与主板固件需自行对齐字段。 - 主板返回的数据同样走 `data` 上行,APP 不理解其含义。 --- ### 2.5 系统与升级 #### 2.5.1 `reboot` — 重启主板(MCU) **用途**:让 STM32 主板重启。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无 | | 处理方式 | 原样转发串口 | | 代码位置 | `mqtthandler.cpp` L436 | **请求 JSON** ```json {"cmd":"reboot"} ``` **使用说明** - 只重启主板,Android 侧不断电;重启期间主板约数十秒不可用,`data` 上报会中断。 - 主板重启后参数应从自身 Flash 恢复;若平台发现参数丢失,可下发 `paramconf` 重设。 #### 2.5.2 `dtu_reboot` — 重启设备(Android) **用途**:重启整机(工控机 + 主板)。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无(设备直接重启) | | 处理方式 | 发送系统重启广播 `rebootSystem` | | 代码位置 | `mqtthandler.cpp` L444 / `main.cpp` L578 | **请求 JSON** ```json {"cmd":"dtu_reboot"} ``` **使用说明** - 重启期间设备离线,Broker 可能代发遗嘱 `offline`(§3.5);平台应把随后收到的 `turnon` 视为恢复上线。 - 适合作为"改完 MQTT/FTP 配置立即生效"的手段(配合 §2.1.1)。 - 现场设备重启约 40–60 s,期间不要重复下发。 #### 2.5.3 `update` — 主板固件升级(rbl) **用途**:触发主板固件(`.rbl`)下载与 YMODEM 升级。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无 RPC 应答;结果用 `warn` 上报 | | 下载源 | `ftp://8.136.98.49/_UPDATE_FILE/MCU/BZYV2_1.rbl` | | 本地落盘 | `{AppData}/rtthread.rbl` | | 代码位置 | `mqtthandler.cpp` L446 / `main.cpp` L560 / `ymodem.cpp` | **请求 JSON** ```json {"cmd":"update"} ``` **升级流程** | 步骤 | 动作 | 可观测信号 | |---|---|---| | 1 | APP 从 FTP 下载 rbl 到本地 | 无 MQTT 报文 | | 2 | 主板上报 `{"cmd":"warn","ext":{"status":"update"}}` | 设备回 `warn` | | 3 | APP 启动 YMODEM,串口独占传输 | 期间串口下行被丢弃 | | 4 | 传输结束 | `{"cmd":"warn","ext":{"status":"结果:0","type":"主板固件升级完成"}}` | **结果判定** ```json {"cmd":"warn","ext":{"status":"结果:0","type":"主板固件升级完成"}} ``` - `结果:0` = 成功;非 0 = 失败(`1` 超时、`-8` 文件打不开等) - `type` 文案固定为"主板固件升级完成",**成败只看 `status`** **使用说明** - 升级前确认主板当前空闲(无采集任务),升级中勿断电。 - 升级期间 APP 会丢弃所有串口下行报文,属正常保护,不是通信故障。 - 失败后可直接重发 `update`;APP 每次都会重新下载,不存在脏文件问题。 #### 2.5.4 `dtu_update` — 下载 APP 升级包 **用途**:下载新版 APK 并**自动安装**。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 立即回 `warn`:`App DownLoad Start!` | | 下载源 | `ftp://8.136.98.49/_UPDATE_FILE/APP/app.apk` | | 本地落盘 | `/sdcard/app.apk` | | 代码位置 | `mqtthandler.cpp` L438 / `main.cpp` L568、L600 | **请求 JSON** ```json {"cmd":"dtu_update"} ``` **设备立即上行** ```json {"cmd":"warn","ext":{"status":"App DownLoad Start!"}} ``` **使用说明** - 下载成功后**会自动触发安装**(约 5 s 后弹出系统安装界面),无需再下发 `app_update`。 - 下载失败**不上报**,只能通过"设备版本号未变化"判断,建议 10 分钟后查 `data.dver`。 - 安装需要用户确认(Android 权限限制);无人值守设备需配合悬浮窗自动点击或系统签名。 #### 2.5.5 `app_update` — 安装已下载的 APK **用途**:手动触发安装 `/sdcard/app.apk`。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无 | | 执行延时 | 5 s(等待界面准备) | | 代码位置 | `mqtthandler.cpp` L442、`install_app()` | **请求 JSON** ```json {"cmd":"app_update"} ``` **使用说明** - 用于"已下载但自动安装被取消/失败"的补装场景。 - APK 不存在时无任何提示,安装界面不会弹出。 - 安装完成后设备上的 APP 会重启,MQTT 断线重连并重发 `turnon`。 #### 2.5.6 `setimei` — 修改设备 IMEI **用途**:写入新的 IMEI 并落库,用于设备换板/换号。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 回一条 `warn` 确认 | | 生效时机 | **重启或重连后**(主题与 ClientID 使用新 IMEI) | | 代码位置 | `mqtthandler.cpp` L474 / `main.cpp` L592 | **参数(`ext`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `imei` | string | **是** | 新 IMEI,建议 15 位数字 | **请求 JSON** ```json {"cmd":"setimei","ext":{"imei":"862289057468809"}} ``` **设备上行确认** ```json {"cmd":"warn","ext":{"status":"更改IMEI:862289057468809","type":"原IMEI:862289057468809"}} ``` **使用说明** - **回执里的"原IMEI"实际是新 IMEI**(实现先赋值再拼报文,§4.3 第 5 条),不要据此判断变更前后值。 - 下发后当前 MQTT 连接仍用旧 IMEI 的主题,**必须重启/重连**才会用新主题;平台切换订阅请在下发后预留缓冲时间。 - IMEI 写错会导致设备"失联"(主题不匹配),务必先核对。 --- ### 2.6 远程运维(frpc / 日志) > frpc 为内网穿透客户端,用于现场设备无公网 IP 时远程 SSH/调试。配置路径:`{AppData}/frpc.toml`;可执行文件位于 APK 的 `nativeLibraryDir`。 #### 2.6.1 `frpc_config` — 保存内网穿透配置 **用途**:把 TOML 配置写入设备,可选立即重启 frpc 生效。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "config saved"` | | 代码位置 | `mqtthandler.cpp` L417 / `FrpcManager::setConfig()` | **参数(`params`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `toml` | string | **是** | 完整 TOML 文本,**换行用 `\n` 转义** | | `restart` | int | 否 | `1` = 保存后重启 frpc;`0`/缺省 = 仅保存 | **请求 JSON** ```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":9,"result":"config saved"} ``` **失败响应** | 场景 | message | |---|---| | TOML 为空 | `toml content is empty` | | 文件写入失败 | `cannot write config: <系统错误>` | **使用说明** - `toml` 必须是**完整配置**(整体覆盖写),不支持增量更新。 - JSON 字符串里的换行必须写成 `\n`;直接粘贴多行文本会解析失败。 - `restart=1` 时若 frpc 未运行,只保存配置、不启动进程;需要启动请另发 `frpc_start`。 #### 2.6.2 `frpc_start` — 启动内网穿透 **用途**:启动 frpc 进程,可携带新配置一并下发。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result` 为**状态 JSON 字符串** | | 运行限制 | 启动后 **1 小时自动停止**(安全看门狗) | | 代码位置 | `mqtthandler.cpp` L392 / `FrpcManager::start()` | **参数(`params`,可整个省略)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `toml` | string | 否 | 内联配置;提供时**先保存再启动** | **请求 JSON —— 用设备已有配置启动** ```json {"jsonrpc":"2.0","method":"frpc_start","id":10} ``` **请求 JSON —— 携带配置启动** ```json { "jsonrpc": "2.0", "method": "frpc_start", "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" }, "id": 10 } ``` **成功响应** ```json { "jsonrpc": "2.0", "id": 10, "result": "{\"running\":true,\"pid\":12345,\"uptime_sec\":0,\"last_exit_code\":0,\"last_exit_crashed\":false,\"config_exists\":true,\"log_tail\":[\"[I] [ssh] start proxy success\"]}" } ``` **失败响应(常见)** | message | 原因与处理 | |---|---| | `frpc already running` | 已在运行,先 `frpc_stop` 或直接查 `frpc_status` | | `config not found, use frpc_config first` | 无配置文件,先用 `frpc_config` 下发 | | `frpc binary missing: ...` | APK 内缺少 frpc 可执行文件,需重新打包 | | `cannot resolve nativeLibraryDir` | 系统接口异常,通常需重启 APP | | `failed to start frpc: ...` | 进程启动失败,看 `log_tail` 定位 | **使用说明** - **1 小时后自动停止**,不会自动续期;需要长时间通道请定时重新下发。 - 启动成功不代表隧道连通,请检查 `log_tail` 中是否出现 `start proxy success`。 - 远程操作完成后应主动 `frpc_stop`,减少暴露面。 #### 2.6.3 `frpc_stop` — 停止内网穿透 **用途**:停止 frpc 进程(`SIGTERM` → 3 s 未退出则 `SIGKILL`)。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result` 为**状态 JSON 字符串** | | 代码位置 | `mqtthandler.cpp` L404 | **请求 JSON** ```json {"jsonrpc":"2.0","method":"frpc_stop","id":11} ``` **成功响应** ```json { "jsonrpc": "2.0", "id": 11, "result": "{\"running\":false,\"pid\":0,\"uptime_sec\":0,\"last_exit_code\":0,\"last_exit_crashed\":false,\"config_exists\":true,\"log_tail\":[\"[I] exit\"]}" } ``` **失败响应** ```json {"jsonrpc":"2.0","id":11,"error":{"code":-32603,"message":"frpc not running"}} ``` **使用说明** - `frpc not running` 属正常情况(可能已被 1 小时看门狗停掉),不必重试。 - 返回 `result` 中的 `running` 才是最终状态,平台应以该字段更新展示。 #### 2.6.4 `frpc_status` — 查询内网穿透状态 **用途**:读取 frpc 运行状态、退出码与最近日志。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,恒成功,`result` 为状态 JSON 字符串 | | 代码位置 | `mqtthandler.cpp` L413 / `FrpcManager::status()` | **请求 JSON** ```json {"jsonrpc":"2.0","method":"frpc_status","id":3} ``` **响应** ```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\"]}" } ``` **`result` 解析后字段** | 字段 | 类型 | 说明 | |---|---|---| | `running` | bool | 进程是否在运行 | | `pid` | int | 进程号,未运行为 0 | | `uptime_sec` | int | 已运行秒数 | | `last_exit_code` | int | 上次退出码 | | `last_exit_crashed` | bool | 上次是否崩溃退出 | | `config_exists` | bool | 配置文件是否存在 | | `log_tail` | string[] | 最近日志,最多 **40** 行 | **使用说明** - `result` 是**字符串**,平台需再做一次 `JSON.parse` 才能取字段。 - 这是唯一无副作用的探活接口,可安全轮询(建议 ≥ 30 s 一次)。 #### 2.6.5 `upload_log` — 远程抓取日志 **用途**:把设备日志文件复制到临时目录并触发 FTP 上传,便于远程排障。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | JSON-RPC 2.0 | | 设备应答 | 是,`result = "log upload started"` | | 上传通道 | FTP(与图片同一通道),**不走 MQTT** | | 代码位置 | `mqtthandler.cpp` L291 | **参数(`params`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `filename` | string | **是** | 仅允许 `.txt`,且只含字母/数字/下划线/中划线,长度 1–64 | **请求 JSON** ```json {"jsonrpc":"2.0","method":"upload_log","params":{"filename":"run_log.txt"},"id":5} ``` **成功响应** ```json {"jsonrpc":"2.0","id":5,"result":"log upload started"} ``` **失败响应** | message | 原因 | |---|---| | `invalid filename` | 含路径分隔符、`..`,或不符合白名单正则 | | `path denied` | 规范化后路径越出 AppData 目录 | | `log file not found` | 文件不存在 | | `failed to copy log file` | 复制失败(空间不足/权限) | **使用说明** - 文件名白名单:`^[A-Za-z0-9_\-]{1,64}\.txt$`,传 `../../databases/config.db` 会被拒绝(安全限制,不要试图绕过)。 - 上传的是**副本**(`temp_log_yyyyMMdd_HHmmss.txt`),原日志不受影响。 - "upload started" 只表示已入队,FTP 是否成功需到服务器目录确认。 --- ### 2.7 离线缓存 #### 2.7.1 `cache_read` — 查询缓存条数 **用途**:查询 JSON / 图片离线缓存的当前条数、上限与开关状态。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 回一条 `warn`(非 RPC 应答) | | 代码位置 | `mqtthandler.cpp` L511 | **参数(`ext`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `type` | string | **是** | `data` = JSON 缓存;`photo` = 图片缓存 | **请求 JSON —— 查 JSON 缓存** ```json {"cmd":"cache_read","ext":{"type":"data"}} ``` **请求 JSON —— 查图片缓存** ```json {"cmd":"cache_read","ext":{"type":"photo"}} ``` **设备上行(JSON)** ```json {"cmd":"warn","ext":{"status":"缓存json数量:12[1]","type":"最大缓存数量:1000"}} ``` **设备上行(图片)** ```json {"cmd":"warn","ext":{"status":"缓存图片数量:3[1]","type":"最大缓存数量:500"}} ``` **字段解读** | 位置 | 含义 | |---|---| | `status` 中数字 | 当前缓存条数 | | `status` 中方括号值 | 1 = 缓存开关开启,0 = 关闭 | | `type` 中数字 | 最大缓存条数(默认 JSON 1000、图片 500) | **使用说明** - 图片那条的 `type` 用的是**全角冒号**(`最大缓存数量:`),平台解析请按后缀数字取值,不要精确匹配冒号。 - 缓存为满时新数据会丢最旧的(环形淘汰),长期满额说明网络或 FTP 有故障。 #### 2.7.2 `cache_enable` — 开关离线缓存 **用途**:开启/关闭某类数据的离线缓存,并立即回读当前状态。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 回一条 `warn`(与 `cache_read` 同格式) | | 代码位置 | `mqtthandler.cpp` L535 | **参数(`ext`)** | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `type` | string | **是** | `data` = JSON;`photo` = 图片 | | `enable` | int | **是** | `0` 关闭 / 非 0 开启 | **请求 JSON —— 关闭 JSON 缓存** ```json {"cmd":"cache_enable","ext":{"type":"data","enable":0}} ``` **请求 JSON —— 开启图片缓存** ```json {"cmd":"cache_enable","ext":{"type":"photo","enable":1}} ``` **设备上行** ```json {"cmd":"warn","ext":{"status":"缓存json数量:0[0]","type":"最大缓存数量:1000"}} ``` **使用说明** - 关闭缓存**不会清空已有数据**,只是不再写入新失败记录;已有条目仍会重传。 - 开关只作用于本次运行(未持久化到 `config.db`),重启后恢复默认开启。 - 断网期间关闭缓存等于主动丢弃数据,慎用。 #### 2.7.3 `cache_restore` — 缓存补传(预留) **用途**:协议预留的"指定条数补传"接口。 | 项目 | 值 | |---|---| | 方向 | 服务器 → 设备 | | 报文风格 | cmd/ext | | 设备应答 | 无 | | 当前状态 | **空实现,下发无任何效果** | | 代码位置 | `mqtthandler.cpp` L563 | **请求 JSON(按预留格式,当前无效)** ```json {"cmd":"cache_restore","ext":{"type":"data","num":10}} ``` **使用说明** - 设备收到后会**静默忽略**,不要依赖该指令补数据。 - 需要补传时请重启设备:重连成功后缓存会自动按 1 条/次重传(§1.5)。 --- ## 3 上行报文(设备 → 服务器) 发布主题统一为 `{pub}{imei}`,QoS 0。 ### 3.1 `turnon` — 上线通知 **用途**:MQTT 连接成功后立即发送,告知平台设备已上线。 | 项目 | 值 | |---|---| | 触发 | 每次 `onConnected()` | | 报文格式 | **纯文本,不是 JSON** | | 代码位置 | `mqtthandler.cpp` L236 | **报文内容** ``` turnon ``` **使用说明** - 平台必须按"非 JSON 文本"单独识别,对这条报文做 JSON 解析会失败。 - 断线重连成功后也会重发,可用于统计掉线次数。 ### 3.2 `data` — 主板数据(透传上报) **用途**:主板采集的环境、供电、胶带/滤网用量、参数等数据,由 APP 原样转发。 | 项目 | 值 | |---|---| | 触发 | 主板每 `dat_f` 分钟上报一次(默认 10);`read`/`paramconf` 会立即触发 | | 报文格式 | cmd/ext | | 转发范围 | 每个周期只转发**第一帧**(`data_upload` 标志位) | | 代码位置 | `mserial.cpp` L267 / `main.cpp` L539 | **报文示例** ```json { "cmd": "data", "ext": { "dver": "1.3.2-2.8.26", "at": "26.5", "ah": "63.2", "boxtem": "25.1", "vbat": "12.4", "current": "320", "fan_current": "85", "lat": "31.2304", "lng": "121.4737", "tpl": 5, "tph": 70, "tps": "0", "x_init_dis": 1300, "y_init_dis": 1600, "coll_time": ["8-10", "12-14", "16-18"], "coll_min": ["0-30", "0-30", "0-30"], "dat_f": "10", "tape_used": 1230, "tape_max": 60000, "filter_used": 12, "filter_max": 100, "freq_filter": "7", "worked_day": "36" } } ``` **字段说明**(字段由主板固件定义,常见值如下) | 字段 | 含义 | 备注 | |---|---|---| | `dver` | 版本号组合 `主板版本-APP版本` | APP 按 `-` 切分后显示 | | `at` / `ah` | 环境温度(℃)/ 湿度(%RH) | 缺失时沿用上一次值 | | `boxtem` | 箱内温度(℃) | — | | `vbat` | 蓄电池电压(V) | 低于 10 V 时 APP 弹"电源断电"提醒 | | `current` | 负载电流(mA) | — | | `fan_current` | 风机电流(mA) | 判断风机是否真的转 | | `lat` / `lng` | 纬度 / 经度 | 主板 GPS 定位 | | `tpl` / `tph` | 低温 / 高温保护阈值(℃) | 与 `paramconf` 对应 | | `tps` | 温控保护状态 | `"1"` = 保护中 | | `x_init_dis` / `y_init_dis` | 初始坐标 | 读为 0 时 APP 自动触发参数恢复 | | `coll_time` / `coll_min` | 三段采集时段 | 成对出现 | | `dat_f` | 数据上报周期(分钟) | APP 收到后更新定时器并写库 | | `tape_used` / `tape_max` | 胶带已用 / 总长 | 平台按 `used/max*100` 算百分比 | | `filter_used` / `filter_max` | 滤网已用 / 总量 | 同上 | | `freq_filter` | 滤网清洁周期(天) | — | | `worked_day` | 已工作天数 | — | **使用说明** - 数值多为**字符串**(主板 `lwjson` 序列化),平台做数值运算前先转型。 - `tape_*` / `filter_*` 的单位随主板固件,平台只用**比值**,不要写死毫米/米。 - 该报文同时也是业务心跳:超过 2 个 `dat_f` 周期没有 `data`,通常意味着主板通信或采集异常。 ### 3.3 `warn` — 告警 / 状态通知 **用途**:设备各环节的状态与告警,也是 `cmd` 风格指令的唯一回执方式。 | 项目 | 值 | |---|---| | 报文格式 | `{"cmd":"warn","ext":{"status":"...","type":"..."}}` | | 触发场景 | 缓存查询、IMEI 变更、升级结果、主板告警转发等 | | 缓存策略 | **不缓存**,断线期间直接丢弃 | | 代码位置 | `m_json.cpp` `MakeJsonWarn()` / `mqtthandler.cpp` 内联构造 | **报文结构** ```json {"cmd":"warn","ext":{"status":"<状态描述>","type":"<类型或补充信息>"}} ``` **已知的 status/type 组合** | `status` 示例 | `type` 示例 | 触发场景 | 代码位置 | |---|---|---|---| | `缓存json数量:12[1]` | `最大缓存数量:1000` | `cache_read` / `cache_enable` | mqtthandler.cpp L522 | | `缓存图片数量:3[1]` | `最大缓存数量:500` | 同上(photo) | mqtthandler.cpp L529 | | `更改IMEI:86...` | `原IMEI:86...`(实际是新 IMEI) | `setimei` | mqtthandler.cpp L482 | | `App DownLoad Start!` | (无 `type` 字段) | `dtu_update` | mqtthandler.cpp L439 | | `读取主板数据` | `超时` | 连续 >10 个周期未收到 `data` | mserial.cpp L32 | | `结果:0` | `主板固件升级完成` | YMODEM 升级结束(0 成功) | mserial.cpp L357 | | `Photo ERROR` | 灰度值(如 `12`) | 拍照图像异常 | cameramanager.cpp L2251 | | 主板原文(如 `takephoto_done`、`translate`) | 主板原文 | 主板 `warn` 转发 | mserial.cpp L213 | **使用说明** - `status`/`type` 都可能有中文前缀,平台建议用 `contains` 匹配关键词,不要全等判断。 - 部分 `warn`(如主板的 `auto_focus`、`movy`)**不上送**,仅 APP 内部处理。 - `warn` 不进离线缓存,平台漏收后无法补发。 ### 3.4 JSON-RPC 应答 **用途**:对 §2 中所有 JSON-RPC 指令的同步应答。 | 项目 | 值 | |---|---| | 触发 | 每条带 `id` 的 `method` 指令处理完毕 | | `id` | 原样回传请求的 `id` | | `result` | 字符串(`frpc_*` 为 JSON 字符串) | | `error.code` | 固定 `-32603` | | 发布 QoS | 0 | **成功** ```json {"jsonrpc":"2.0","id":42,"result":"mqtt1 config updated"} ``` **失败** ```json {"jsonrpc":"2.0","id":42,"error":{"code":-32603,"message":"ip and port are required"}} ``` **使用说明** - 应答没有 `method` 字段,平台需按 `id` 关联请求。 - 应答与请求走同一 `{pub}{imei}` 主题,不是独立响应主题。 ### 3.5 `offline` — 遗嘱报文(掉线) **用途**:设备异常掉线时由 Broker 代发,通知平台设备离线。 | 项目 | 值 | |---|---| | 主题 | `{lastwill}{imei}` | | QoS | 1 | | retain | false | | 触发 | MQTT 连接异常断开且未正常发 DISCONNECT | | 代码位置 | `m_json.cpp` `WillMessage()` / `mqtthandler.cpp` L144 | **报文示例** ```json {"cmd":"offline","ext":{"imei":"862289057468809"}} ``` **使用说明** - 该报文由 **Broker** 发送,设备自身不发布;平台需单独订阅离线主题。 - 正常重启(`dtu_reboot`)也可能触发遗嘱,应与随后的 `turnon` 结合判断。 - 遗嘱主题在连接时拼接 IMEI,改 IMEI 后需重连才生效。 --- ## 4 附录 ### 4.1 指令速查表 | 指令 | 风格 | 用途 | RPC 应答 | 转发串口 | |---|---|---|---|---| | `setserver_mqtt1` | RPC | 主 MQTT 配置 | ✅ | ❌ | | `setserver_mqtt2` | RPC | 备 MQTT 配置(暂存) | ✅ | ❌ | | `setserver_ftp1` | RPC | 主 FTP 配置 | ✅ | ❌ | | `setserver_ftp2` | RPC | 备 FTP 配置(暂存) | ✅ | ❌ | | `ctr_cam` | RPC | 设置曝光时间 | ✅ | ❌ | | `fusion_sw` | RPC | 景深融合开关/查询 | ✅ | ❌ | | `focus_algo` | RPC | 对焦/融合算法选择/查询 | ✅ | ❌ | | `frpc_config` | RPC | 保存穿透配置 | ✅ | ❌ | | `frpc_start` | RPC | 启动穿透 | ✅ | ❌ | | `frpc_stop` | RPC | 停止穿透 | ✅ | ❌ | | `frpc_status` | RPC | 查询穿透状态 | ✅ | ❌ | | `upload_log` | RPC | 抓取日志(FTP) | ✅ | ❌ | | `ctrl`(auto_takephoto) | cmd | 自动多图采集+融合 | ❌ | ❌ | | `ctrl`(takephoto) | cmd | 单张拍照(延时 10 s) | ❌ | ❌ | | `slide` | cmd | 远程校准/轴运动 | ❌ | ✅ | | `takephoto` | cmd | 主板原生拍照 | ❌ | ✅ | | `ledon` / `ledoff` | cmd | 补光灯 | ❌ | ✅ | | `windon` / `windoff` | cmd | 采集风机 | ❌ | ✅ | | `translate` | cmd | 胶带走带 | ❌ | ✅ | | `read` | cmd | 催一帧主板数据 | ❌ | ✅ | | `paramconf` | cmd | 采集参数配置 | ❌ | ✅ | | `sensor` | cmd | 传感器透传 | ❌ | ✅ | | `reboot` | cmd | 重启主板 | ❌ | ✅ | | `dtu_reboot` | cmd | 重启整机 | ❌ | ❌ | | `update` | cmd | 主板固件升级 | ❌ | ✅ | | `dtu_update` | cmd | 下载并安装 APK | ❌ | ❌ | | `app_update` | cmd | 安装已下载 APK | ❌ | ❌ | | `setimei` | cmd | 修改 IMEI | ❌ | ❌ | | `cache_read` | cmd | 查缓存条数 | ❌ | ❌ | | `cache_enable` | cmd | 开关缓存 | ❌ | ❌ | | `cache_restore` | cmd | 预留(空实现) | ❌ | ❌ | ### 4.2 典型交互时序 ``` 平台(Server) 设备(Android) STM32 主板 │ │ │ │── 订阅 {sub}{imei} ─────────────────►│ │ │◄─ turnon ────────────────────────────│ 上线(纯文本) │ │ │◄── data(每 dat_f 分钟)─────│ │◄─ {"cmd":"data",...} ────────────────│ 原样转发 │ │── setserver_ftp1 ───────────────────►│ │ │◄─ {"result":"ftp1 config updated"} ──│ │ │── ctrl / auto_takephoto ────────────►│ 采集 + 融合 │ │ │──── 图片走 FTP 上传 ────────► FTP │◄─ warn: takephoto_done ──────────────│ │ │── {"cmd":"reboot"} ─────────────────►│──── 转发 ───────────────────►│ │ x 设备异常掉线 │ │ │◄─ offline(Broker 代发遗嘱) │ │ ``` ### 4.3 实现差异与已知问题 > 本节记录**文档与代码实际行为**的差异,平台开发以此为准。 | 序号 | 项目 | 说明 | 建议 | |---|---|---|---| | 1 | `setserver_mqtt1/2` 不重连 | `handleMqttConfig()` 只写内存与数据库;`signal_reconfigure_mqtt` 仅声明未发射 | 改完配置追加 `dtu_reboot`,或等设备自然断线重连 | | 2 | `clientid` 参数无效 | 连接固定使用 `AndroidClient` + IMEI | 不要依赖自定义 ClientID 做设备识别,用 IMEI | | 3 | `qos` 参数无效 | 所有发布固定 QoS 0(含 RPC 应答) | 关键指令由平台侧自行重试 | | 4 | `synchronization` 不是 MQTT 报文 | 它是**工控机 → 主板**的串口轮询报文(见 §4.4) | 平台不会在 c2s 收到该报文;状态以 `data` 为准 | | 5 | `setimei` 回执"原IMEI"错误 | 代码先赋值 `param::imei` 再拼报文,`type` 回的是新 IMEI | 变更前后值请以平台下发记录为准 | | 6 | `upload_log` 文件名受限 | 白名单 `^[A-Za-z0-9_\-]{1,64}\.txt$`,且必须位于 AppData | 只下发 `.txt` 文件名,不带路径 | | 7 | RPC 与 cmd 分支不互斥 | 一条报文同时带 `method` 与 `cmd` 时两个分支都会执行 | 严禁混发两种风格 | | 8 | `frpc` 1 小时自动停止 | `kAutoStopMs = 60 * 60 * 1000` | 长时间运维需定时重新 `frpc_start` | | 9 | `cache_restore` 空实现 | 收到后静默忽略 | 补数据靠重启触发自动重传 | ### 4.4 串口报文对照(不经 MQTT) 以下报文走 **UART(115200 8N1)**,平台在 MQTT 侧看不到。列出以避免与 MQTT 指令混淆。 | 报文 | 方向 | 用途 | |---|---|---| | `{"cmd":"synchronization","ext":{...}}` | 工控机 → 主板 | 周期轮询/心跳,替代旧的 `cmd:read` | | `{"cmd":"data","ext":{...}}` | 主板 → 工控机 | 主板数据上报(APP 转发到 MQTT,见 §3.2) | | `{"cmd":"warn",...}` | 主板 → 工控机 | 主板状态通知(多数转发 MQTT) | | `{"jsonrpc":"2.0","method":"selfclean","id":1}` | 工控机 → 主板 | 启动自清洁 | | `{"jsonrpc":"2.0","method":"record_start","id":1}` | 工控机 → 主板 | 开始录制视频流 | | `{"jsonrpc":"2.0","method":"record_stop","id":1}` | 工控机 → 主板 | 停止录制并处理视频流 | | `{"jsonrpc":"2.0","method":"tape_reset","params":{"tape_max":60000},"id":1}` | 工控机 → 主板 | 胶带计数重置 | | `{"jsonrpc":"2.0","method":"filter_reset","params":{"filter_max":100},"id":1}` | 工控机 → 主板 | 滤网计数重置 | | `{"jsonrpc":"2.0","method":"sync_param","params":{...},"id":1}` | 主板 → 工控机 | 主板参数备份到 APP 数据库 | | `{"jsonrpc":"2.0","method":"recover_param","id":1}` | 工控机 → 主板 | 从数据库恢复主板参数 | | `{"jsonrpc":"2.0","method":"factory_reset","id":1}` | 工控机 → 主板 | MCU 参数恢复出厂设置(系统设置页「参数重置」按钮,二次确认后发送) | | `{"focus":<数值>}` | 相机 → 工控机 → 主板 | 清晰度评分结果,仅串口 | | `{"cmd":"slide","ext":{"movx":"f100","speed":"50"}}` | 工控机 → 主板 | 滑台运动(MQTT `slide` 也会转发) | ### 4.5 代码索引 | 功能 | 文件 | 位置 | |---|---|---| | 连接/遗嘱/重连 | `src/mqtthandler.cpp` | `connectToBroker()` L123、`onDisconnected()` L242 | | 下行分发 | `src/mqtthandler.cpp` | `onMessageReceived()` L255 | | MQTT 配置下发 | `src/mqtthandler.cpp` | `handleMqttConfig()` L679 | | FTP 配置下发 | `src/mqtthandler.cpp` | `handleFtpConfig()` L770 | | RPC 应答 | `src/mqtthandler.cpp` | `sendJsonRpcResponseImpl()` L660 | | 缓存查询/开关 | `src/mqtthandler.cpp` | L511-566 | | 报文构造 | `src/m_json.cpp` | `BoardMessage()` L83、`MakeJsonWarn()` L162、`WillMessage()` L179 | | 对焦/融合算法 | `src/slview_focus.cpp` | `getEdge()` / `guideFilterFusion()` / `multiScaleFusion()` / `computeFactor()` | | 算法选择分支 | `src/m_opencv.cpp` | `fuseAdvanced()` 内 `[SLViewFusion]` 分支;评分见 `evaluateFocusScore()` | | 串口分发 | `src/mserial.cpp` | `processJsonData()` L163 | | 离线缓存 | `src/app_sq_save.cpp` | `OfflineStorage` | | frpc 进程管理 | `src/frpcmanager.cpp` | `start()/stop()/status()/setConfig()` | | 信号接线 | `src/main.cpp` | L539-607 | ### 4.6 变更记录 | 版本 | 日期 | 说明 | |---|---|---| | 2.1 | 2026-10-22 | 新增 §2.2.3 `focus_algo`(对焦/融合算法选择),含三档算法对照表;速查表与代码索引同步补充。对应 APP 2.8.31。 | | 2.0 | 2026-10-21 | 全文重构:由"汇总表 + 通用模板"改为**一条指令一节**,每节含属性表、参数表、可直接复制的请求/响应 JSON 与使用说明;新增速查表、串口报文对照、9 项实现差异。修正旧版 4 处不准确描述(`setserver_*` 不重连、`clientid/qos` 未生效、`synchronization` 非 MQTT 上行、`frpc` 1 小时自动停止)。 | | 1.0 | 2026-08-21 | 首版,对应 APP 2.5.8。 |