|
|
@@ -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>
|
|
|
+```
|