Просмотр исходного кода

新增协议文档和框架代码

niujiuru 10 месяцев назад
Родитель
Сommit
9f3187653a

+ 392 - 0
docs/便携色板监测设备与平台端交互协议.md

@@ -0,0 +1,392 @@
+# 便携式色诱板监测设备与平台端交互协议
+
+版本:V0.3
+日期:2025-09-19
+作者:牛九如
+
+约定:
+a) 通信消息分为两大类: 通知类消息和请求应答类消息, 通知类消息无应答
+b) MQTT主题名称中带"notify"表明是通知类消息,带"rpc"表明是请求应答类消息
+c) 通知和请求应答类消息的内容字段, 数据类型全部使用字符串, 编码设定为: UTF-8
+d) 复用JSON-RPC 2.0标准错误码, 本文档中不做重述, 请参考JSON-RPC 2.0相关规定
+e) "Device Unique Identifier", 简称为"DUI", 相关的具体说明和编码规则, 请参
+   考我司内部资料文档, 设备唯一编号
+
+## 1. JSON-RPC 2.0 over MQTT请求应答设备上线
+
+客户端请求<->服务端应答
+
+客户端发送上线请求, pub主题:/yfkj/bxs-sy/server/rpc/request
+客户端接收上线应答, sub主题:/yfkj/bxs-sy/server/rpc/response
+服务端接收上线请求, sub主题:/yfkj/bxs-sy/server/rpc/request
+服务端发送上线应答, pub主题:/yfkj/bxs-sy/server/rpc/response
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "login",
+  "params": {
+    // 设备类型, 便携式色诱产品类型为: 33
+    "deviceType": "33",
+    // 设备的唯一标识, 15个十进制数字组成
+    "imei": "123456789012345",
+    // 电话卡唯一标识, 20个十进制数字组成
+    "iccid": "12345678901234567890",
+    // 4G网络接收信号强度指示
+    "rssi": "18",
+    // 当前app版本号, 格式: x.x.x.x, 具体描述如下:
+    // [major(8bit)].[minor(8bit)].[patch(8bit)].[build(8bit)]
+    "appVersion": "1.0.0.1",
+    // 设备继承的DUI(关联历史台账信息), 可选特殊用途字段, 说明:
+    // 1, 更换硬件板块登录时, 使用该字段表明要继承的历史台账信息
+    // 2, 服务端完成历史台账的变更、迁移后, 返回成功或失败的应答
+    // 3, 设备收到成功应答后, 下次开机登录时将不再上报该请求字段
+    // 4, 设备收到失败应答后, 下次开机登录还会再次发送该请求字段
+    "inheritDUI": "25091703300001"
+  },
+  "id": 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": {
+    // 设备的唯一标识, 15个十进制数字组成
+    "imei": "123456789012345",
+    // 设备唯一逻辑ID, 由平台侧分配管理, 14个十进制数字组成
+    "DUI": "25091703300001"
+  },
+  "id": 1
+}
+或失败无需应答
+
+备注说明: 如果需要对客户端进行接入身份验证, 后期可以对该接口参数进行扩展
+
+## 2. JSON-RPC 2.0 over MQTT请求应答命令交互
+
+服务端请求<->客户端应答
+
+服务端发送操作指令, pub主题:/yfkj/bxs-sy/device/rpc/dui/request
+服务端接收指令应答, sub主题:/yfkj/bxs-sy/device/rpc/dui/response
+客户端接收操作指令, sub主题:/yfkj/bxs-sy/device/rpc/dui/request
+客户端发送指令应答, pub主题:/yfkj/bxs-sy/device/rpc/dui/response
+
+### 2.1. 服务端下发MCU控制板运行参数
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "setMCUParams",
+  "params": {
+    // 版本号, 格式: x.x.x.x, 具体描述如下:
+    // [major(8bit)].[minor(8bit)].[patch(8bit)].[build(8bit)]
+    "version": "0.0.0.1",
+    // 定时控制模式(0=光控, 1=时控)
+    "ctrlMode": "1",
+    // 光控定时时长(小时, 1-10, 仅光控模式有效)
+    "lightDuration": "10",
+    // 时控开始时间(小时, 0-23, 仅时控模式有效)
+    "startHour": "0",
+    // 时控结束时间(小时, 0-23, 仅时控模式有效)
+    "endHour": "23",
+    // 拍照间隔(分钟)
+    "takePhotoIntervalMinutes": "60"
+  },
+  "id": 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": "Success",
+  "id": 1
+}
+或
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "设置MCU运行参数失败的错误描述"
+  },
+  "id": 1
+}
+
+### 2.1. 服务端获取MCU控制板运行参数
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "getMCUParams",
+  "id": 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": {
+    // 版本号, 格式: x.x.x.x, 具体描述如下:
+    // [major(8bit)].[minor(8bit)].[patch(8bit)].[build(8bit)]
+    "version": "0.0.0.1",
+    // 定时控制模式(0=光控, 1=时控)
+    "ctrlMode": "1",
+    // 光控定时时长(小时, 1-10, 仅光控模式有效)
+    "lightDuration": "10",
+    // 时控开始时间(小时, 0-23, 仅时控模式有效)
+    "startHour": "0",
+    // 时控结束时间(小时, 0-23, 仅时控模式有效)
+    "endHour": "23",
+    // 拍照间隔(分钟)
+    "takePhotoIntervalMinutes": "30"
+  },
+  "id": 1
+}
+或
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "获取MCU运行参数失败的错误描述"
+  },
+  "id": 1
+}
+
+### 2.3. 服务端触发RTU拍照一次并上传
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "takephoto",
+  "id": 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": {
+    // 照片文件名, 格式: "YYYY-MM-DDThh:mm:ss.sssZ.jpg"
+    "filename": "ftp://xxx.xxx.xxx.xxx:21/xxx/2025-09-15T02:16:16.442Z.jpg"
+  },
+  "id": 1
+}
+或
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "本次拍照失败的错误描述"
+  },
+  "id": 1
+}
+
+### 2.4. 触发RTU上报此时刻的环境数据
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "getCurrentEnvData",
+  "id": 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "获取当前环境数据失败的错误描述"
+  },
+  "id": 1
+}
+或
+{
+  "jsonrpc": "2.0",
+  "result": "success",
+  "id": 1
+}
+
+成功应答后, 服务端需等待客户端异步通知上报此时刻的环境数据。
+客户端主动上报数据, pub主题:/yfkj/bxs-sy/notify/dui/envDataNow
+服务端需订阅该主题, 上报的数据格式如下:
+{
+  // 设备的唯一标识, 15个十进制数字组成
+  "imei": "123456789012345",
+  "envData": {
+      // 时间戳(秒)
+      "timestamp": "1640969600",
+      // 温度(0.1°C)
+      "temperature": "25.3",
+      // 湿度 (%RH)
+      "humidity": "50.2",
+      // 光照 (lux)
+      "illuminance": "300",
+      // 电压 (V)
+      "voltage": "3.3"
+    }
+}
+
+### 2.5. 服务端触发RTU重新热启动一次
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "reboot",
+  "id": 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": "Success",
+  "id": 1
+}
+
+### 2.6. 获取RTU当前所在的位置信息值
+
+-> 请求:
+{
+  “jsonrpc”: “2.0”,
+  “method”: "getLocation",
+  “id”: 1
+}
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": {
+    // 纬度, 纯度格式, WGS-84坐标系
+    "lat": "30.5233",
+    // 经度, 纯度格式, WGS-84坐标系
+    "lon": "114.3545",
+  },  
+  "id": 1
+}
+或
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "获取当前位置信息失败的错误描述"
+  },
+  "id": 1
+}
+
+### 2.7. 触发RTU升级应用程序到最新版
+
+-> 请求:
+{
+  "jsonrpc": "2.0",
+  "method": "upgradeApp",
+  "params": {
+    // 升级包的URL地址
+    "url": "ftp://username:password@xxx.xxx.xxx.xxx:xxx/xxx/rtu_bxs_seyou_1.0.0.1.tar.gz",
+    // 升级包的MD5校验值, 32个十六进制数字组成, 16字节
+    "md5": "5d41402abc4b2a76b9719d911017c592"
+  },
+  "id": 1
+}
+
+"rtu_bxs_seyou_1.0.0.1.tar.gz"升级包内容格式:
+
+- 升级程序文件: rtu_bxs_seyou.out
+- 升级版本文件: version.txt, 格式: x.x.x.x
+- 升级程序校检: rtu_bxs_seyou.md5, 内容: 5d41402abc4b2a76b9719d911017c592, 说明: 为防止改值被篡改, 可以
+  简单的加入一层AES-128的加密安全处理, 密码固定到程序中, 密钥: "YFKJ@seyou123456", 长16字节。
+
+<- 应答:
+{
+  "jsonrpc": "2.0",
+  "result": "Success",
+  "id": 1
+}
+或
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "升级应用程序失败的错误描述"
+  },
+  "id": 1
+}
+
+## 3. 发送上一个工作循环24小时温湿度光照电压等环境数据
+
+客户端主动上报数据, pub主题:/yfkj/bxs-sy/notify/dui/envData24h
+上报的数据格式如下:
+{
+  // 设备的唯一标识, 15个十进制数字组成
+  "imei": "123456789012345",
+  "envDataGroup": [
+    {
+      // 时间戳(秒)
+      "timestamp": "1640969600",
+      // 温度(0.1°C)
+      "temperature": "25.3",
+      // 湿度 (%RH)
+      "humidity": "50.2",
+      // 光照 (lux)
+      "illuminance": "300",
+      // 电压 (V)
+      "voltage": "3.3"
+    },
+    {
+      "timestamp": "1640973200",
+      "temperature": "24.8",
+      "humidity": "49.5",
+      "illuminance": "280",
+      "voltage": "3.2"
+    },
+    // ..., 一般是24组
+  ]
+}
+
+## 4. 定位成功
+
+客户端主动上报数据, pub主题:/yfkj/bxs-sy/notify/dui/location
+上报的数据格式如下:
+{
+  // 设备的唯一标识, 15个十进制数字组成
+  "imei": "123456789012345",
+  // 纬度, 纯度格式, WGS-84坐标系
+  "lat": "30.5233",
+  // 经度, 纯度格式, WGS-84坐标系
+  "lon": "114.3545"
+}
+
+## 5. MCU控制板的运行参数-(登录成功时、变更时)
+
+客户端主动上报数据, pub主题:/yfkj/bxs-sy/notify/dui/mcuParams
+上报的数据格式如下:
+{
+  // 设备的唯一标识, 15个十进制数字组成
+  "imei": "123456789012345",
+  // 版本号, 格式: x.x.x.x, 具体描述如下:
+  // [major(8bit)].[minor(8bit)].[patch(8bit)].[build(8bit)]
+  "version": "0.0.0.1",
+  // 定时控制模式(0=光控, 1=时控)
+  "ctrlMode": "1",
+  // 光控定时时长(小时, 1-10, 仅光控模式有效)
+  "lightDuration": "10",
+  // 时控开始时间(小时, 0-23, 仅时控模式有效)
+  "startHour": "0",
+  // 时控结束时间(小时, 0-23, 仅时控模式有效)
+  "endHour": "23",
+  // 拍照间隔(分钟)
+  "takePhotoIntervalMinutes": "30"
+}
+
+## 6. 上传照片
+
+通过FTP客户端将照片文件上传到指定的FTP服务器目录,照片存在"./dui"目录下, 文件名称格式: "YYYY-MM-DDThh:mm:ss.sssZ.jpg"
+
+## 7. JSON-RPC 2.0 over MQTT通知设备离线消息
+
+客户端离线遗愿消息, pub主题:/yfkj/bxs-sy/notify/logout
+遗愿消息内容如下:
+{
+  "jsonrpc": "2.0",
+  "method": "logout",
+  "params": {
+    // 设备的唯一标识, 15个十进制数字组成
+    "imei": "123456789012345"
+  },
+  "id": 1
+}

BIN
docs/星火MCU控制板通讯协议251226.docx