MQTT_Protocol.md 57 KB

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 与请求一致:

成功

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

失败(错误码固定 -32603)

{"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":<Tenengrad 值>} 只发串口,不经 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

{
  "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
}

成功响应

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

失败响应(缺 ip 或 port)

{"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

{
  "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
}

成功响应

{"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

{
  "jsonrpc": "2.0",
  "method": "setserver_ftp1",
  "params": {
    "ip": "8.136.98.49",
    "port": 21,
    "uid": "bzy_user",
    "pwd": "YFkj@6O2O",
    "dir": "BZYV21/"
  },
  "id": 44
}

成功响应

{"jsonrpc":"2.0","id":44,"result":"ftp1 config updated"}

失败响应

{"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

{
  "jsonrpc": "2.0",
  "method": "setserver_ftp2",
  "params": {
    "ip": "8.136.98.50",
    "port": 21,
    "uid": "bzy_user",
    "pwd": "YFkj@6O2O",
    "dir": "BZYV21/"
  },
  "id": 45
}

成功响应

{"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

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

成功响应

{"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 —— 关闭

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

请求 JSON —— 开启

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

请求 JSON —— 查询(params 可整个省略)

{"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 —— 切到多尺度融合

{"jsonrpc":"2.0","method":"focus_algo","params":{"algo":1},"id":1}

请求 JSON —— 回退旧算法

{"jsonrpc":"2.0","method":"focus_algo","params":{"algo":2},"id":1}

请求 JSON —— 查询(params 可整个省略)

{"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

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

设备侧后续上行

{"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

{"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 —— 远程校准

{"cmd":"slide","ext":{"calibrate":"y","speed":"50"}}

请求 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

{"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

{"cmd":"ledon"}
{"cmd":"ledoff"}

使用说明

  • 无需 ext,带了也会忽略。
  • 补光灯常用于辅助对焦;采集结束后应主动 ledoff,避免长期点亮影响孢子活性观察。

2.4.2 windon / windoff — 采集风机开关

用途:控制采集风机启停。

项目 值
方向 服务器 → 设备
报文风格 cmd/ext
设备应答 无(风机电流变化体现在 data.fan_current)
处理方式 原样转发串口
代码位置 mqtthandler.cpp L505

请求 JSON

{"cmd":"windon"}
{"cmd":"windoff"}

使用说明

  • 风机是否真的转起来,用下一条 data 的 fan_current 判断(0 或异常低值说明未启动)。
  • 长时间运行建议周期性开关,避免风机过热。

2.4.3 translate — 胶带电机走带

用途:驱动胶带电机转动(换带、走带测试)。

项目 值
方向 服务器 → 设备
报文风格 cmd/ext
设备应答 无(主板回 warn status 含 translate 时转发)
处理方式 原样转发串口
代码位置 mqtthandler.cpp L507

请求 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

{"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 —— 设置采集时段

{"cmd":"paramconf","ext":{"coll_time":["8-10","12-14","16-18"]}}

请求 JSON —— 设置时段分钟

{"cmd":"paramconf","ext":{"coll_min":["0-30","0-30","0-30"]}}

请求 JSON —— 设置初始坐标

{"cmd":"paramconf","ext":{"x_init_dis":1300,"y_init_dis":1600}}

请求 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

{"cmd":"sensor","ext":{"type":"env"}}

使用说明

  • ext 结构由主板固件定义,APP 不校验、不改写;平台与主板固件需自行对齐字段。
  • 主板返回的数据同样走 data 上行,APP 不理解其含义。

2.5 系统与升级

2.5.1 reboot — 重启主板(MCU)

用途:让 STM32 主板重启。

项目 值
方向 服务器 → 设备
报文风格 cmd/ext
设备应答 无
处理方式 原样转发串口
代码位置 mqtthandler.cpp L436

请求 JSON

{"cmd":"reboot"}

使用说明

  • 只重启主板,Android 侧不断电;重启期间主板约数十秒不可用,data 上报会中断。
  • 主板重启后参数应从自身 Flash 恢复;若平台发现参数丢失,可下发 paramconf 重设。

2.5.2 dtu_reboot — 重启设备(Android)

用途:重启整机(工控机 + 主板)。

项目 值
方向 服务器 → 设备
报文风格 cmd/ext
设备应答 无(设备直接重启)
处理方式 发送系统重启广播 rebootSystem
代码位置 mqtthandler.cpp L444 / main.cpp L578

请求 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

{"cmd":"update"}

升级流程

步骤 动作 可观测信号
1 APP 从 FTP 下载 rbl 到本地 无 MQTT 报文
2 主板上报 {"cmd":"warn","ext":{"status":"update"}} 设备回 warn
3 APP 启动 YMODEM,串口独占传输 期间串口下行被丢弃
4 传输结束 {"cmd":"warn","ext":{"status":"结果:0","type":"主板固件升级完成"}}

结果判定

{"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

{"cmd":"dtu_update"}

设备立即上行

{"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

{"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

{"cmd":"setimei","ext":{"imei":"862289057468809"}}

设备上行确认

{"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

{
  "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":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 —— 用设备已有配置启动

{"jsonrpc":"2.0","method":"frpc_start","id":10}

请求 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
}

成功响应

{
  "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

{"jsonrpc":"2.0","method":"frpc_stop","id":11}

成功响应

{
  "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\"]}"
}

失败响应

{"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

{"jsonrpc":"2.0","method":"frpc_status","id":3}

响应

{
  "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

{"jsonrpc":"2.0","method":"upload_log","params":{"filename":"run_log.txt"},"id":5}

成功响应

{"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 缓存

{"cmd":"cache_read","ext":{"type":"data"}}

请求 JSON —— 查图片缓存

{"cmd":"cache_read","ext":{"type":"photo"}}

设备上行(JSON)

{"cmd":"warn","ext":{"status":"缓存json数量:12[1]","type":"最大缓存数量:1000"}}

设备上行(图片)

{"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 缓存

{"cmd":"cache_enable","ext":{"type":"data","enable":0}}

请求 JSON —— 开启图片缓存

{"cmd":"cache_enable","ext":{"type":"photo","enable":1}}

设备上行

{"cmd":"warn","ext":{"status":"缓存json数量:0[0]","type":"最大缓存数量:1000"}}

使用说明

  • 关闭缓存不会清空已有数据,只是不再写入新失败记录;已有条目仍会重传。
  • 开关只作用于本次运行(未持久化到 config.db),重启后恢复默认开启。
  • 断网期间关闭缓存等于主动丢弃数据,慎用。

2.7.3 cache_restore — 缓存补传(预留)

用途:协议预留的"指定条数补传"接口。

项目 值
方向 服务器 → 设备
报文风格 cmd/ext
设备应答 无
当前状态 空实现,下发无任何效果
代码位置 mqtthandler.cpp L563

请求 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

报文示例

{
  "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 内联构造

报文结构

{"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

成功

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

失败

{"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

报文示例

{"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。