适用固件: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 | 速查表与附录(时序、实现差异、串口报文对照) | — |
| 项目 | 取值 | 说明 |
|---|---|---|
| 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 周期上报 |
主题 = 配置前缀 + 设备 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 | JSON-RPC 2.0 | 同时含非空 jsonrpc、method(字符串)、id |
是,同 id 回包 |
配置下发、状态查询、运维操作 |
| 2 | cmd/ext | 含 cmd 字段 |
否(仅可能回 warn) |
动作指令、透传主板 |
实现细节:RPC 分支执行完后不会跳过
cmd分支。一条报文若同时带method和cmd,两个分支都会执行(§4.3 第 7 条),平台侧请勿混发。
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 观察结果 |
| 数据 | 缓存条件 | 存储与上限 | 重传策略 |
|---|---|---|---|
| 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。
c2s 主题(设备发布)
┌──────────┐ ◄────────────────────── ┌───────────────┐
│ MQTT │ │ │──► 相机(拍照/录像/融合)
│ Broker │ ──────────────────────► │ MqttHandler │──► 串口(STM32 主板)
└──────────┘ s2c 主题(设备订阅) │ │──► QML 界面
└───────────────┘
cmd:data、部分 warn 由 SerialThread::dataUpload 直通 MQTT{"focus":<Tenengrad 值>} 只发串口,不经 MQTTsetserver_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 会被忽略)。pub/sub 一并带上。dtu_reboot(§2.5.2)。result,重启后会回退到旧配置。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"}
使用说明
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 只作根前缀。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"}
使用说明:当前无上传失败自动切换备通道的逻辑,仅作配置留存。
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"}
使用说明
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)。2、-1 等价于 1)。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 多尺度金字塔融合 MS2=原程序算法(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 只影响最清晰帧的评分方式。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"}}
使用说明
data 中的 tape_used 观察采集消耗。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"}}
使用说明
auto_takephoto 的区别:本指令只拍一张,不做多焦点融合。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,字段含义见主板协议。takephoto — 主板拍照(透传)用途:转发给主板执行其原生拍照流程,兼容老平台指令。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 主题 | {sub}{imei} |
| 报文风格 | cmd/ext |
| 设备应答 | 无,主板执行后可能回 warn 或同 cmd |
| 处理方式 | 原样转发串口,APP 不做业务处理 |
| 代码位置 | mqtthandler.cpp L508 |
请求 JSON
{"cmd":"takephoto"}
使用说明
ctrl / auto_takephoto(§2.3.1),本指令仅为兼容保留。{"cmd":"takephoto"} 时 APP 只做内部完成通知,不再上行;如需可观测,请用 ctrl 系列。本节指令 APP 不解析
ext,只校验cmd后整条报文转发给 STM32 主板;执行结果通过主板data/warn回传。
ledon / ledoff — 补光灯开关用途:打开/关闭相机补光灯。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无 |
| 处理方式 | 原样转发串口 |
| 代码位置 | mqtthandler.cpp L501 |
请求 JSON
{"cmd":"ledon"}
{"cmd":"ledoff"}
使用说明
ext,带了也会忽略。ledoff,避免长期点亮影响孢子活性观察。windon / windoff — 采集风机开关用途:控制采集风机启停。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无(风机电流变化体现在 data.fan_current) |
| 处理方式 | 原样转发串口 |
| 代码位置 | mqtthandler.cpp L505 |
请求 JSON
{"cmd":"windon"}
{"cmd":"windoff"}
使用说明
data 的 fan_current 判断(0 或异常低值说明未启动)。translate — 胶带电机走带用途:驱动胶带电机转动(换带、走带测试)。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无(主板回 warn status 含 translate 时转发) |
| 处理方式 | 原样转发串口 |
| 代码位置 | mqtthandler.cpp L507 |
请求 JSON
{"cmd":"translate"}
使用说明
data.tape_used 会增加,可用于核对胶带消耗是否正常。read — 请求主板数据(兼容)用途:要求主板立即回一帧 data。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 间接:主板回 cmd:data,APP 转发 MQTT |
| 处理方式 | 转发串口,并将下一帧 data 标记为需上报 |
| 代码位置 | mqtthandler.cpp L502 / mserial.cpp mqtttoserial() |
请求 JSON
{"cmd":"read"}
使用说明
synchronization(串口报文,见 §4.4),本指令仅兼容老平台。dat_f 分钟上报一次(默认 10 分钟);下发 read 可立即催一帧。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")而不采集。data 时同步;若坐标被读成 0,APP 会自动触发参数恢复(见 §4.4 recover_param)。sensor — 传感器透传用途:把平台自定义的传感器指令原样交给主板,由主板固件解释。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 由主板决定(通常回 data) |
| 处理方式 | 原样转发串口 |
| 代码位置 | mqtthandler.cpp L509 |
请求 JSON
{"cmd":"sensor","ext":{"type":"env"}}
使用说明
ext 结构由主板固件定义,APP 不校验、不改写;平台与主板固件需自行对齐字段。data 上行,APP 不理解其含义。reboot — 重启主板(MCU)用途:让 STM32 主板重启。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无 |
| 处理方式 | 原样转发串口 |
| 代码位置 | mqtthandler.cpp L436 |
请求 JSON
{"cmd":"reboot"}
使用说明
data 上报会中断。paramconf 重设。dtu_reboot — 重启设备(Android)用途:重启整机(工控机 + 主板)。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无(设备直接重启) |
| 处理方式 | 发送系统重启广播 rebootSystem |
| 代码位置 | mqtthandler.cpp L444 / main.cpp L578 |
请求 JSON
{"cmd":"dtu_reboot"}
使用说明
offline(§3.5);平台应把随后收到的 turnon 视为恢复上线。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使用说明
update;APP 每次都会重新下载,不存在脏文件问题。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!"}}
使用说明
app_update。data.dver。app_update — 安装已下载的 APK用途:手动触发安装 /sdcard/app.apk。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无 |
| 执行延时 | 5 s(等待界面准备) |
| 代码位置 | mqtthandler.cpp L442、install_app() |
请求 JSON
{"cmd":"app_update"}
使用说明
turnon。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"}}
使用说明
frpc 为内网穿透客户端,用于现场设备无公网 IP 时远程 SSH/调试。配置路径:
{AppData}/frpc.toml;可执行文件位于 APK 的nativeLibraryDir。
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 必须是完整配置(整体覆盖写),不支持增量更新。\n;直接粘贴多行文本会解析失败。restart=1 时若 frpc 未运行,只保存配置、不启动进程;需要启动请另发 frpc_start。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 定位 |
使用说明
log_tail 中是否出现 start proxy success。frpc_stop,减少暴露面。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 才是最终状态,平台应以该字段更新展示。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 才能取字段。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),原日志不受影响。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 用的是全角冒号(最大缓存数量:),平台解析请按后缀数字取值,不要精确匹配冒号。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),重启后恢复默认开启。cache_restore — 缓存补传(预留)用途:协议预留的"指定条数补传"接口。
| 项目 | 值 |
|---|---|
| 方向 | 服务器 → 设备 |
| 报文风格 | cmd/ext |
| 设备应答 | 无 |
| 当前状态 | 空实现,下发无任何效果 |
| 代码位置 | mqtthandler.cpp L563 |
请求 JSON(按预留格式,当前无效)
{"cmd":"cache_restore","ext":{"type":"data","num":10}}
使用说明
发布主题统一为 {pub}{imei},QoS 0。
turnon — 上线通知用途:MQTT 连接成功后立即发送,告知平台设备已上线。
| 项目 | 值 |
|---|---|
| 触发 | 每次 onConnected() |
| 报文格式 | 纯文本,不是 JSON |
| 代码位置 | mqtthandler.cpp L236 |
报文内容
turnon
使用说明
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_* 的单位随主板固件,平台只用比值,不要写死毫米/米。dat_f 周期没有 data,通常意味着主板通信或采集异常。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 不进离线缓存,平台漏收后无法补发。用途:对 §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} 主题,不是独立响应主题。offline — 遗嘱报文(掉线)用途:设备异常掉线时由 Broker 代发,通知平台设备离线。
| 项目 | 值 |
|---|---|
| 主题 | {lastwill}{imei} |
| QoS | 1 |
| retain | false |
| 触发 | MQTT 连接异常断开且未正常发 DISCONNECT |
| 代码位置 | m_json.cpp WillMessage() / mqtthandler.cpp L144 |
报文示例
{"cmd":"offline","ext":{"imei":"862289057468809"}}
使用说明
dtu_reboot)也可能触发遗嘱,应与随后的 turnon 结合判断。| 指令 | 风格 | 用途 | 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 | 预留(空实现) | ❌ | ❌ |
平台(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 代发遗嘱) │ │
本节记录文档与代码实际行为的差异,平台开发以此为准。
| 序号 | 项目 | 说明 | 建议 |
|---|---|---|---|
| 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 空实现 |
收到后静默忽略 | 补数据靠重启触发自动重传 |
以下报文走 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 也会转发) |
| 功能 | 文件 | 位置 |
|---|---|---|
| 连接/遗嘱/重连 | 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 |
| 版本 | 日期 | 说明 |
|---|---|---|
| 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。 |