# 虫情测报灯与服务器端交互通讯细节

## 简要描述

本文档主要用于阐述虫情测报灯与服务器端进行交互的通讯细节。对接采用 HTTP 协议，由接收方写接口来接收 HTTP POST 数据（需从 request 的 body（字节流类型）中取数据，取到之后进行 JSON 解析）。图片和设备数据为相互独立的两种数据。

## 接口说明

### 1. 数据接收接口

需要接收方写接口接收数据 POST 请求，数据分为 `status`、`data`、`offline` 类型，可共用一个接口，根据 `cmd` 字段进行解析。

#### status 数据返回示例

```json
{
  "topic": "/yfkj/cbd/pub/865650043207246",
  "payload": {
    "cmd": "status",
    "ext": {
      "imei": "865650043207246",
      "iccid": "89860401101700076471",
      "csq": 29,
      "dtype": 1,
      "dver": "1.0.0",
      "rps": 0,
      "lps": 0,
      "tps": 0,
      "gs": 0,
      "upds": 1,
      "dnds": 0,
      "hs": 0,
      "ts": 0,
      "lat": "34.815187",
      "lng": "113.67336",
      "lamp": 0,
      "lux": 1,
      "vs": 40,
      "ws": 0,
      "shake": 1,
      "proj": "DCCBD-2_HK",
      "stamp": "20180301211805",
      "gps": "2"
    }
  }
}
```
status 参数说明
| 字段名 | 描述 |
| ------ | ---- |
| imei   | 通讯板唯一 ID |
| iccid  | 物联网卡的 iccid 号，用于查询物联网卡的套餐、流量信息等 |
| csq    | 信号强度 |
| dtype  | 设备类型 (测报灯设备类型为 3) |
| dver   | 设备固件版本 |
| rps    | 雨控状态 1：雨控，0：正常 |
| lps    | 光控状态 1：光控，0：正常 |
| tps    | 温控状态 1：温控，0：正常 |
| gs     | 通道状态 1：落虫，0：排水 |
| upds   | 上仓门状态 1：打开，0：关闭 |
| dnds   | 下仓门状态 1：打开，0：关闭 |
| hs     | 加热状态 1：加热，0：正常 |
| ts     | 定时模式 0：光控，1：时控 |
| lat    | 纬度 |
| lng    | 经度 |
| stamp  | 时间戳（格式：YYYYMMDDHHmmss） |
| ws     | 工作状态 0：待机，1：工作 |
| lamp   | 灯管状态 0：灭，1：亮（只有 `ws=1` 时灯管状态才起作用） |
| lux    | 光照强度 |
| vs     | 内部版本号，做参考 |
| shake  | 震动时间（单位：毫秒） |
| proj   | 内部版本名称 |
| gps    | 定位说明, 0: 手动定位, 1: GPS 定位, 2: 基站定位 |

2. data 数据返回示例  
```json
{
  "topic": "/yfkj/cbd/pub/865650043207246",
  "payload": {}
}
```
data 参数说明
| 字段名    | 描述                                                                 |
| --------- | -------------------------------------------------------------------- |
| imei      | 通讯板唯一 ID                                                       |
| at        | 环境温度 (单位：℃)（注：温度值为乘以 10 后的结果，需要除以 10 得到温度值） |
| ah        | 环境湿度 (单位：%RH)（注：湿度值为乘以 10 后的结果，需要除以 10 得到相对湿度值） |
| hrt       | 加热仓实时温度 (单位：℃)                                           |
| rps       | 雨控状态 1：雨控，0：正常                                           |
| lps       | 光控状态 1：光控，0：正常                                           |
| tps       | 温控状态 1：温控，0：正常                                           |
| lat       | 纬度                                                               |
| lng       | 经度                                                               |
| stamp     | 时间戳（格式：YYYYMMDDHHmmss）                                     |
| ws        | 工作状态 0：待机，1：工作                                           |
| lamp      | 灯管状态 0：灭，1：亮（只有 `ws=1` 时灯管状态才起作用）             |
| lux       | 光照强度                                                           |
| batStatus | 电池状态 0：正常, 1：欠压                                             |
| vbat      | 电池电压                                                           |  
3. offline 参数返回说明  
会发布异常下线设备的遗愿消息。注意：设备离线会发送一条设备下线消息，设备上线后发送正常数据（data 和 status）。

设备默认设置配置了 MQTT 遗愿消息。当设备异常下线时（客户端断开前未向服务器发送 DISCONNECT 消息），MQTT 消息服务器会发布异常下线设备的遗愿消息。订阅设备遗愿消息，可实现对设备在线和离线状态的监控。

离线消息主题  
/yfkj/cbd/offline/<imei>  
报文结构  

```json
{
  "cmd": "offline",
  "ext": {
    "imei": "865650043207246"
  }
}
```
offline 参数返回示例  
```json
{
  "payload": {
    "cmd": "offline",
    "ext": {
      "imei": "865650043207246"
    }
  },
  "topic": "/yfkj/cbd/pub/865650043207246"
}
设备带害虫识别图片传输说明  
注意事项
数据上传时间默认是 20 分钟上传一次。  
图片数据上传时间受落虫时间、加热时间影响，默认是 30 分钟上传一次。  
设备拍照只在设置的工作范围内拍照，设备在雨控、温控状态下不会进行拍照和图片数据上传，只会上传设备数据（data 和 status 数据）。  
图片保存的时候不要直接保存图片链接到数据库，有可能图片链接会失效，导致图片展示不了的问题，需要下载保存到本地。  
示例 1  
```json
{
  "Image": "http://www.yfzhwlw.com/cbd_img/868956044831318/2020/09/202009191823.jpg",
  "Result_image": "http://www.yfzhwlw.com/result_pyftp/ftp_file/ykm_cbd/868956044824807/192.168.1.100_01_20201112174044521_ALARM_INPUTresult.jpg",
  "Result": "20,3#8,1#64,1#49,1#3,1#112,1#79,1",
  "imei": "865650043207246"
}
```
示例 2  
```json
{
  "Image": "http://www.yfzhwlw.com/cbd_img/868956044831318/2020/09/202009191823.jpg",
  "Result_image": "0",
  "Result": "0",
  "imei": "865650043207246"
}
```
图片参数说明  
| 字段名       | 描述                                                                 |
| ------------ | -------------------------------------------------------------------- |
| imei         | 设备序列号                                                           |
| Image        | 拍照图片（图片链接，建议下载保存）                                   |
| Result_image | 识别结果图片（图片链接，建议下载保存）                               |
| Result       | 结果字符串，用“种类 1,种类 1 数目#种类 2,种类 2 数目…”表示，如 “10,1#12,2”，表示种类 10 的数目是 1，种类 12 的数目是 2 |
设备不带害虫识别图片传输说明  
接口说明: 
对接采用 HTTP 协议，由接收方写接口来接收 HTTP POST 数据（需从 request 的 body（字节流类型）中取数据，取到之后进行 JSON 解析）。图片和设备数据为相互独立的两种数据。  
图片保存的时候不要直接保存图片链接到数据库，有可能图片链接会失效，导致图片展示不了的问题，需要下载保存到本地。

示例  
```json
{
  "Image": "http://www.yfzhwlw.com/cbd_img/868956044831318/2020/09/202009191823.jpg",
  "imei": "865650043207246"
}
```
图片参数说明  
| 字段名 | 描述 |
| ------ | ---- |
| imei   | 设备序列号 |
| Image  | 拍照图片（图片链接，建议下载保存） |
设备温控、雨控说明  
温控：为了冬季保护电池。即使供电系统是市电，在这种温度条件下，并不会发生虫情，因此设计为系统待机，不再拍照，也比较符合节能降耗的思想。  
雨控：为了防止设备进水而设计，发生雨控也进入待机，不再工作和拍照。