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

便携式色诱板监测设备与平台端交互协议

版本：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, 内容: 5d41402abc, 说明: 为防止改值被篡改, 可以 简单的加入一层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 }