Jelajahi Sumber

简化代码,上传与云飞MQTT服务器的后台通信协议

niujiuru 1 bulan lalu
induk
melakukan
1ae81fa4e4
1 mengubah file dengan 314 tambahan dan 0 penghapusan
  1. 314 0
      docs/测报灯MQTT云飞通信协议.md

+ 314 - 0
docs/测报灯MQTT云飞通信协议.md

@@ -0,0 +1,314 @@
+# CBD 设备通信协议文档
+
+- **文档版本:** V1.0
+- **最后更新:** 2024 年
+
+## 1. MQTT 主题
+
+| 主题类型 | 主题格式 |
+|---|---|
+| 上传主题 | `/yfkj/cbd/pub/imei` |
+| 下发主题 | `/yfkj/cbd/sub/imei` |
+| 离线消息主题 | `/yfkj/cbd/offline/<imei>` |
+
+其中,`imei` 为设备通信板的唯一标识。
+
+## 2. 数据上报
+
+### 2.1 查询设备状态
+
+服务器通过 MQTT 下发以下报文,查询设备状态:
+
+```json
+{
+    "cmd": "read",
+    "ext": "data"
+}
+```
+
+### 2.2 定时数据上报及查询回复
+
+设备定时上报数据,或收到状态查询指令后,返回以下格式的报文:
+
+```json
+{
+    "cmd": "data",
+    "ext": {
+        "dver": "1.2.2HK",
+        "proj": "CBDV1",
+        "dtype": "3",
+        "ws": "0",
+        "ds": "0",
+        "tt": "4",
+        "st": "20",
+        "et": "5",
+        "ah": "50",
+        "at": "30",
+        "tps": "0",
+        "lps": "0",
+        "rps": "0",
+        "batStatus": "0",
+        "stamp": "20200910180714",
+        "imei": "867435052203452",
+        "iccid": "89860476232090133920",
+        "upds": "0",
+        "dnds": "0",
+        "dws": "0",
+        "lng": "",
+        "lat": "",
+        "hrt": "27",
+        "turnon": "11",
+        "current": "86.33",
+        "vbat": "15.04",
+        "datt": "10",
+        "hs": "0",
+        "collt": "0",
+        "htim": "0",
+        "hst": "125",
+        "csq": "31",
+        "tph": "70",
+        "tpl": "0",
+        "shake": "0",
+        "shake_sec": "1",
+        "gps": "0",
+        "fuse_voltage": "15.04"
+    }
+}
+```
+
+### 2.3 数据字段说明
+
+| 字段 | 含义 | 取值或说明 |
+|---|---|---|
+| `imei` | 通信板唯一标识 | 设备唯一 ID |
+| `iccid` | 物联网卡 ICCID | 用于查询套餐、流量等信息 |
+| `csq` | 信号强度 | 信号强度值 |
+| `lat` | 纬度 | GPS 或定位结果 |
+| `lng` | 经度 | GPS 或定位结果 |
+| `dtype` | 设备类型 | `3`:测报灯 |
+| `dver` | 设备固件版本 | 固件版本号 |
+| `proj` | 项目标识 | 项目名称或编号 |
+| `ws` | 工作状态 | `0`:待机;`1`:工作 |
+| `ds` | 设备开关状态 | `0`:关机;`1`:开机 |
+| `vbat` | 电池或供电电压 | 单位:V |
+| `st` | 时控开始时间 | `0`~`23` 小时 |
+| `et` | 时控结束时间 | `0`~`23` 小时 |
+| `tt` | 光控定时时长 | `1`~`10` 小时 |
+| `ts` | 定时模式 | `0`:光控;`1`:时控 |
+| `tps` | 温控状态 | `0`:正常;`1`:保护 |
+| `lps` | 光控状态 | `0`:正常;`1`:保护 |
+| `rps` | 雨控状态 | `0`:正常;`1`:保护 |
+| `batStatus` | 电压状态 | `0`:正常;`1`:欠压 |
+| `collt` | 数据收集时间 | `1`~`30` 分钟 |
+| `current` | 功率字段 | 原文标注单位为 mA |
+| `hrt` | 加热仓实时温度 | 实时温度值 |
+| `hst` | 加热仓设定温度 | `70`~`130` ℃ |
+| `at` | 环境温度 | 环境温度值 |
+| `ah` | 环境湿度 | 环境湿度值 |
+| `stamp` | 数据时间戳 | 格式:`YYYYMMDDHHmmss` |
+| `datt` | 数据上传间隔 | 单位:分钟 |
+| `turnon` | 开机次数 | 每次重启加 1 |
+| `htim` | 加热时间 | `1`~`30` 分钟 |
+| `upds` | 上仓门状态 | `1`:打开;`0`:关闭 |
+| `dnds` | 下仓门状态 | `1`:打开;`0`:关闭 |
+| `dws` | 原文未说明 | 待确认 |
+| `hs` | 加热状态 | `0`:正常;`1`:加热 |
+| `tph` | 高温保护参数 | 保护温度设置 |
+| `tpl` | 低温保护参数 | 原文未说明具体含义 |
+| `shake` | 震动开关 | `0`:关闭;`1`:开启 |
+| `shake_sec` | 震动时间参数 | 单位及范围见参数设置说明 |
+| `fuse_voltage` | 保险丝电压 | 单位:V |
+| `gps` | 定位状态 | `0`:失败;`1`:GPS 定位成功;`2`:基站定位成功 |
+| `lamp` | 灯管/工作状态 | 工作:`lamp=0 && ws=1`;待机:`ws=0`;异常:`ws=1 && lamp` 非 `0` |
+
+> 注:部分字段的含义、单位或取值范围在原始资料中未完整定义,已按原文保留并标注待确认,建议以实际固件实现为准。
+
+## 3. 下发参数设置
+
+### 3.1 设置参数报文
+
+服务器通过 MQTT 下发 `paramconf` 指令,设置设备运行参数:
+
+```json
+{
+    "cmd": "paramconf",
+    "ext": {
+        "hst": "110",
+        "collt": "20",
+        "et": "5",
+        "datt": "20",
+        "shake_sec": "1",
+        "tpl": "5",
+        "shake": "1",
+        "tph": "70",
+        "ts": "1",
+        "st": "20",
+        "htim": "20",
+        "tt": "4",
+        "ds": "1",
+        "vt": "4"
+    }
+}
+```
+
+### 3.2 参数字段说明
+
+| 字段 | 含义 | 范围或取值 |
+|---|---|---|
+| `hst` | 加热温度 | `75`~`130` ℃ |
+| `collt` | 收集时间 | `1`~`30` 分钟 |
+| `st` | 时控开始时间 | `0`~`23`,字符串 |
+| `et` | 时控结束时间 | `0`~`23`,字符串 |
+| `datt` | 数据上传间隔 | `1`~`60` 分钟 |
+| `shake` | 震动开关 | `0`:关闭;`1`:开启 |
+| `shake_sec` | 震动时间 | `100`~`5000` ms |
+| `tph` | 高温保护温度 | `50`~`80` ℃ |
+| `ts` | 定时模式 | `0`:光控;`1`:时控 |
+| `htim` | 加热时间 | `1`~`30` 分钟 |
+| `tt` | 光控定时时长 | `1`~`10` 小时 |
+| `ds` | 设备开关状态 | `0`:关机;`1`:开机 |
+| `vt` | 版本类型 | `1`:1.0;`4`:4.0 |
+| `tpl` | 低温保护参数 | 原文未说明具体含义 |
+
+> 注:原始报文中使用 `vt`,数据上报字段中使用 `vtype`,两者是否对应同一参数需结合设备固件确认。原始资料对 `et` 的说明存在不一致,此处依据数据上报部分整理为“时控结束时间”。
+
+## 4. 控制命令
+
+### 4.1 重启设备
+
+```json
+{
+    "cmd": "reboot"
+}
+```
+
+### 4.2 拍照
+
+```json
+{
+    "cmd": "takephoto"
+}
+```
+
+## 5. DTU/RTU MQTT 配置
+
+### 5.1 服务器配置报文
+
+服务器通过 `setnet` 指令配置设备的 MQTT 和 FTP 连接参数:
+
+```json
+{
+    "cmd": "setnet",
+    "ftp": {
+        "pwd": "",
+        "uid": "",
+        "port": 1883,
+        "ip": "120.27.222.26"
+    },
+    "mqtt": {
+        "qos": 0,
+        "uid": "",
+        "sub": "/yfkj/cbd/sub/",
+        "port": 1883,
+        "keepalive": 60,
+        "pwd": "",
+        "lastwill": "/yfkj/cbd/offline/",
+        "pub": "/yfkj/cbd/pub/",
+        "ip": "39.104.94.153"
+    }
+}
+```
+
+### 5.2 MQTT 配置字段说明
+
+| 字段 | 含义 | 默认值或说明 |
+|---|---|---|
+| `ip` | MQTT 服务器 IP 或域名 | 由服务器配置 |
+| `port` | MQTT 服务端口 | `1883` |
+| `sub` | 服务器下发指令主题前缀 | `/yfkj/cbd/sub/` |
+| `pub` | 设备上报数据主题前缀 | `/yfkj/cbd/pub/` |
+| `lastwill` | 离线遗嘱主题前缀 | `/yfkj/cbd/offline/` |
+| `uid` | MQTT 用户名 | 默认空 |
+| `pwd` | MQTT 密码 | 默认空 |
+| `qos` | MQTT 服务质量等级 | `0` |
+| `keepalive` | MQTT 心跳间隔 | `60` 秒 |
+
+`sub`、`pub` 和 `lastwill` 为主题前缀,设备根据协议规则拼接设备标识。
+
+### 5.3 FTP 配置字段说明
+
+| 字段 | 含义 | 默认值或说明 |
+|---|---|---|
+| `ip` | FTP 服务器 IP 或域名 | 由服务器配置 |
+| `port` | FTP 服务端口 | 原始配置示例为 `1883`,需确认实际端口 |
+| `uid` | FTP 用户名 | 默认空 |
+| `pwd` | FTP 密码 | 默认空 |
+
+## 6. 查询网络配置
+
+### 6.1 查询指令
+
+服务器下发 `readnet` 指令,查询设备当前网络配置:
+
+```json
+{
+    "cmd": "readnet"
+}
+```
+
+### 6.2 网络配置回复
+
+设备返回 `netconf` 报文:
+
+```json
+{
+    "cmd": "netconf",
+    "mqtt": {
+        "ip": "120.xx.xx.xx",
+        "port": 1883,
+        "sub": "/yfkj/cbd/sub/7001",
+        "pub": "/yfkj/cbd/pub/7001",
+        "lastwill": "/yfkj/cbd/offline/",
+        "uid": "",
+        "pwd": "",
+        "qos": 0,
+        "keepalive": 60
+    },
+    "ftp": {
+        "ip": "120.xx.xxx.xx",
+        "port": 1883,
+        "uid": "",
+        "pwd": ""
+    }
+}
+```
+
+其中,`mqtt` 为 MQTT 连接配置,`ftp` 为 FTP 连接配置。
+
+## 7. 离线消息
+
+### 7.1 离线消息报文
+
+设备 MQTT 连接断开时,通过遗嘱机制发布离线消息:
+
+```json
+{
+    "cmd": "offline",
+    "ext": {
+        "imei": "868575028xxxxxx"
+    }
+}
+```
+
+### 7.2 字段说明
+
+| 字段 | 含义 |
+|---|---|
+| `cmd` | 消息类型,固定为 `offline` |
+| `ext.imei` | 离线设备的唯一标识 |
+
+离线消息主题格式为:
+
+```text
+/yfkj/cbd/offline/<imei>
+```