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

版本：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
}
