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