# 物联网杀虫灯http协议

## 简述

本文档主要用于阐述物联网杀虫灯与服务器端进行交互的通讯细节。

## 通信描述

对接采用 HTTP 协议，由接收方写接口来接收 http post 数据（需从 request 的 body （字节流类型）中取数据，取到之后进行 json 解析）。

## 对接说明

### 设备数据说明

1. **数据上传时间默认为 30 分钟一次**。
2. **电击次数就是杀虫数**，上传一次 data 数据后重置为 0。

### 设备对接说明

1. **设备数据包含**：设备号、SIM 卡号、境温湿度、工作状态、经纬度、电压等。
2. **由接收方提供接口接收数据**，设备方推送数据，需要提供一个可以外网访问的接口接收数据（与接收数据(离线数据与 data 数据区分，根据数据中的 cmd 字段进行区分)）。
3. **先进行接口测试**，没问题后才能发正式数据。
4. **如果对接完成后设备未收到数据**，请先检查所提供的接口是否有问题，然后再联系对接人员。
5. **设备上线后会自动发送 data 数据**。
6. **关于接口安全问题**，可以针对传输方 IP 做限制,不是传输方的 IP 不让其调用接口，（传输方 IP 可以联系对接人员提供）。
7. **设备数据格式不可变**，不能按接收方增加或者减少字段，如有需求请联系销售经理。
8. **接口设置是我们这边进行配置**，您只需要把接口发给对接人员就可以了。

## 设备数据报文结构

```json
{
  "topic": "/yfkj/scd/pub/867435052203452",
  "payload": {
    "cmd": "data",
    "ext": {
      "imei": "867435052203452",
      "iccid": "89680401101700076471",
      "csq": "29",
      "dtype": "1",
      "dver": "1.0.0",
      "stm8vs": "1.0.0",
      "ws": "0",
      "ds": "1",
      "tt": "7",
      "lps": "0",
      "rps": "0",
      "tps": "0",
      "dps": "0",
      "bt": "25",
      "voltval": "60",
      "ts": "0",
      "st": "20",
      "et": "2",
      "cv": "18.000",
      "bv": "12.800",
      "at": "0",
      "ah": "0",
      "ct": "0",
      "clt_t": "30",
      "dat_f": "30",
      "rcnt": "0",
      "info": "2",
      "gps": "1",
      "lng": "113.67336",
      "lat": "34.815187",
      "stamp": "20180301211805"
    }
  }
}
```
字段说明

| 字段名       | 描述                                                                 |
| ------------ | -------------------------------------------------------------------- |
| imei         | 通讯板唯一 ID                                                       |
| iccid        | SIM 卡卡号                                                           |
| csq          | 信号强度                                                             |
| dver         | 4G 物联网模块代码版本号                                             |
| ws           | 工作状态 0: 待机，1: 工作，2: 充电                                   |
| ds           | 设备开关 0: 关机，1: 开机                                            |
| tt           | 定时时长 (0~7)小时, 0 表示常亮                                       |
| lps          | 光控状态 0: 正常 1: 保护 (检测到白天，光控模式下白天不工作，所以保护，2: 充电状态) |
| rps          | 雨控状态 0: 正常 1: 保护                                             |
| tps          | 温控状态 0: 正常 1: 保护 (设备进入温控状态)                          |
| dps          | 倾倒状态 0: 正常 1: 保护 (设备进入倾倒状态)                          |
| bt           | 主板温度，默认 25 度                                                 |
| ts           | 时控开关 0: 关闭时控 1: 开启时控（设备工作状态，光控默认工作时间为天黑后 8 小时，时控可以设置工作时间范围） |
| st           | 时控开始时间，单位: 小时 0~23                                        |
| et           | 时控结束时间，单位: 小时 0~23                                        |
| cv           | 充电电压，单位: V 字符串                                             |
| bv           | 电池电压，单位: V 字符串                                             |
| at           | 环境温度 (字符串)                                                    |
| ah           | 环境湿度 (字符串)                                                    |
| ct           | 电击次数，范围 0~255 (每上报一次数据消息（data 消息）后清零)         |
| clt_t        | 清虫间隔时间，单位：分钟                                             |
| dat_f        | 数据上传时间，单位：分钟                                             |
| rcnt         | 设备重启次数                                                         |
| gps          | 定位方式 0: 手动定位 1: GPS 定位 2: 基站定位                         |
| lng          | 经度                                                                 |
| lat          | 纬度                                                                 |
| stamp        | 时间戳，格式：YYYYMMDDHHmmss（例如 20180301211805）                 |


### 遗愿消息
设备默认设置配置了 MQTT 遗愿消息。当设备异常下线时（客户端断开前未向服务器发送 DISCONNECT 消息），MQTT 消息服务器会发布异常下线设备的遗愿消息。

报文结构
```
{
  "cmd": "offline",
  "ext": {
    "imei": "867435052203452"
  },
  "topic": "/yfkj/scd/pub/867435052203452"
}
```


# 物联网杀虫灯mqtt协议

## 简述

本文档主要用于阐述物联网杀虫灯与服务器端进行交互的通讯细节，其中包括物联网杀虫灯与服务器之间使用的通信协议和交互通讯协议两部分。

## 适用范围

适用于【通用物联网杀虫灯】与服务器之间的通讯。

## 设备主题

关于主题 `sub` 和 `pub` 的说明，注意不要混淆：
- 除离线消息主题：`/yfkj/scd/offline/<imei>` 以外
- 所有上行通信的主题：`"/yfkj/scd/pub/<imei>"`
- 所有下行通信的主题：`"/yfkj/scd/sub/<imei>"`

其中 `<imei>` 指设备唯一标识。

## 术语和缩略语

| 术语        | 描述                                                                 |
| ----------- | -------------------------------------------------------------------- |
| imei        | 杀虫灯设备的通讯 ID，可作为设备唯一标识                             |
| MQTT        | 公开的物联网通信协议                                                 |
| QOS         | 0,1,2 -- MQTT 的质量协议                                             |
| cmd         | 协议命令字标识，为消息报文分类                                       |
| data        | 数据报告协议命令字，报文中使用                                       |
| paramconf   | 参数配置协议命令字，报文中使用                                       |
| read        | 服务器下发查询协议命令字，报文中使用                                 |
| power       | 服务器下发开关协议命令字，报文中使用                                 |
| timer       | 服务器下发定时协议命令字，报文中使用                                 |

## 通信协议

### MQTT协议版本

物联网杀虫灯使用主流公开的 MQTT 协议 V3.1.1 版本作为通讯协议，默认 QOS 质量等级为 0。服务器端需要实现 MQTT 协议的转发和解析，数据的上报为 JSON 格式。MQTT V3.1.1 协议详见附件。

## 交互协议

### 报文分类

| 分类     | 描述                           |
| -------- | ------------------------------ |
| status   | 状态报告                       |
| data     | 数据报告                       |
| paramconf| 杀虫灯参数配置报告             |
| power    | 下发开关控制                   |
| timer    | 下发工作定时时长               |
| read     | 下发查询                       |

**根据 MQTT 的特性，下发服务不必回复，可以通过设置下位机的 QOS 为 2 或 1 来保证命令必达，也可以通过服务器主动下发查询状态和下发查询配置指令，来判断是否执行成功。**

### 报文结构

```json
{
  "cmd": "<协议命令字>",
  "ext": {<message>}
}
```
协议命令字 cmd 为报文分类定义的英文标识。
ext 为各个命令字对应的信息内容。
以上数据内容为 JSON 格式。
上行通信
数据报告
报文结构
```json
{
  "cmd": "data",
  "ext": {
    "imei": "867435052203452",
    "iccid": "89680401101700076471",
    "csq": "29",
    "dtype": "1",
    "dver": "1.0.0",
    "stm8vs": "1.0.0",
    "ws": "0",
    "ds": "1",
    "tt": "7",
    "lps": "0",
    "rps": "0",
    "tps": "0",
    "dps": "0",
    "bt": "25",
    "voltval": "60",
    "ts": "0",
    "st": "20",
    "et": "2",
    "cv": "18.000",
    "bv": "12.800",
    "at": "0",
    "ah": "0",
    "ct": "0",
    "clt_t": "30",
    "dat_f": "30",
    "rcnt": "0",
    "info": "2",
    "gps": "1",
    "lng": "113.67336",
    "lat": "34.815187",
    "stamp": "20180301211805"
  }
}
```
字段说明 

| 字段名  | 描述                                                                 |
| ------- | -------------------------------------------------------------------- |
| imei    | 通讯板唯一 ID                                                       |
| iccid   | SIM 卡卡号                                                          |
| csq     | 信号强度                                                           |
| dtype   | 设备类型 (4G 杀虫灯设备类型为 2) (不用展示)                         |
| dver    | 4G 物联网模块代码版本号                                             |
| stm8vs  | 主板代码版本号 (不用展示)                                           |
| ws      | 工作状态 0：待机，1：工作，2：充电                                  |
| ds      | 设备开关 0：关机，1：开机                                           |
| tt      | 定时时长 (0~7)小时, 0 表示常亮                                      |
| lps     | 光控状态 0：正常 1：保护(1 设备进入光控状态,检测到白天，光控模式下白天不工作) |
| rps     | 雨控状态 0：正常 1：保护(1 设备进入雨控状态时，是不进入工作拍照的)  |
| tps     | 温控状态 0：正常 1：保护(1 设备进入温控状态)                        |
| dps     | 倾倒状态 0：正常 1：保护(1 设备进入倾倒状态)                        |
| bt      | 主板温度 默认 25 度                                                 |
| voltval | 灯管异常检测 ADC 电压值 单位：mV (不用展示)                         |
| ts      | 时控开关 0：关闭时控 1：开启时控（设备工作状态，光控默认工作时间为天黑后 8 小时，时控可以设置工作时间范围） |
| st      | 时控开始时间 单位:小时 0~23                                         |
| et      | 时控结束时间 单位:小时 0~23                                         |
| cv      | 充电电压 单位:V 字符串                                              |
| bv      | 电池电压 单位:V 字符串                                              |
| at      | 环境温度 (字符串)                                                   |
| ah      | 环境湿度 (字符串)                                                   |
| ct      | 电击次数 范围 0~255 (每上报一次数据消息（data 消息）后清零)         |
| clt_t   | 清虫间隔时间 单位：分钟                                             |
| dat_f   | 数据上传时间 单位：分钟                                             |
| rcnt    | 设备重启次数                                                        |
| info    | 重启信息 1：正常 2：socket 重连 3：MQTT 重连 (不用展示)              |
| gps     | 定位方式 0：手动定位 1：GPS 定位 2：基站定位 (不用展示)              |
| lng     | 经度                                                              |
| lat     | 纬度                                                              |
| stamp   | 时间戳 20180301211805(时间字符串 2018 03 01 21:18:05)               |  

参数配置  
报文结构
```json
{
  "cmd": "paramconf",
  "ext": {
    "vsunset": "6000",
    "uvoff": "12500",
    "vfloat": "13600",
    "unlowt": "10",
    "battype": "0",
    "tt": "4",
    "stamp": "20200713182415",
    "vstart": "12000",
    "imei": "866950040595174",
    "overtemp": "70",
    "unovert": "50",
    "uvon": "11500",
    "lowtemp": "5",
    "vsunrise": "1500",
    "vcutof": "14400",
    "vrecharge": "12800"
  }
}
```
字段说明  

| 字段名      | 描述                                                                 |
| ----------- | -------------------------------------------------------------------- |
| imei        | 通讯板唯一 ID                                                       |
| tt          | 定时时长 (0~7)小时, 0 表示常亮                                      |
| uvon        | 电池欠压锁定电压 mv                                                 |
| uvoff       | 电池欠压解锁电压 mv                                                 |
| vfloat      | 电池浮充电压 mv                                                     |
| vcutof      | 电池充电截至电压 mv                                                 |
| overtemp    | 高温保护 ℃ 默认：70                                                |
| lowtemp     | 低温保护 ℃ 默认：5                                                 |
| battype     | 电池类型 0：铅蓄电池，1：锂电池                                     |
| stamp       | 时间戳 20180301211805                                               |
| vsunset     | 日出电压 mv                                                         |
| vsunrise    | 日落电压 mv                                                         |
| vrecharge   | 充电回滞电压 mv                                                     |
| vstart      | 开机电压 mv                                                         |
| unovert     | 解除高温保护℃ 默认：50                                             |
| unlowt      | 解除低温保护℃ 默认：10                                             |    

下行通信  
下发查询请求  
查询状态报文结构  
```json
{
  "cmd": "read",
  "ext": "data"
}
```
字段说明  

| 字段名      | 描述                           |
| ----------- | ------------------------------ |
| data        | 请求读取数据信息               |
| paramconf   | 请求读取参数配置信息           |  

参数配置下发  
报文结构  
```json
{
  "cmd": "SetScdParam",
  "ext": {
    "battype": 0,
    "vsunrise": 1500,
    "vsunset": 6000,
    "vcutof": 14400,
    "vfloat": 13600,
    "vrecharge": 12800,
    "uvstart": 12000,
    "uvoff": 12500,
    "uvon": 11500,
    "overtemp": 55,
    "lowtemp": 0,
    "unovert": 30,
    "unlowt": 5,
    "version": 144
  }
}
```
字段说明  

| 字段名      | 描述                                                                 |
| ----------- | -------------------------------------------------------------------- |
| battype     | 电池类型 0：铅蓄电池，1：锂电池                                     |
| vsunrise    | 日落电压 mv                                                          |
| vsunset     | 日出电压 mv                                                          |
| vcutof      | 电池充电截至电压 mv                                                  |
| vfloat      | 电池浮充电压 mv                                                      |
| vrecharge   | 再次启动充电动作的电压 mv                                            |
| uvstart     | 开机电压 mv                                                          |
| uvoff       | 电池欠压解锁电压 mv                                                  |
| uvon        | 电池欠压锁定电压 mv                                                  |
| overtemp    | 高温保护 ℃ 默认 70                                                  |
| lowtemp     | 低温保护 ℃ 默认 5                                                   |
| unovert     | 解除高温保护℃ 默认 50                                               |
| unlowt      | 解除低温保护℃ 默认 10                                               |
| version     | 版本号 0~255                                                         |  

控制指令下发  
```json
{
	"cmd": "paramconf",
	"ext": {
		"timctrl": 1,
		"st": 20,
		"et": 2,
		"dattim": 10,
		"clt": 30,
		"tt": 4,
		"ds": 1
	}
}
```

下发一键测试报文结构  
```json
{
  "cmd": "test"
}
```
下发重启报文结构
```json
{
  "cmd": "reboot"
}
```
下发升级报文结构
```json
{
  "cmd": "update"
}
```
字段说明  

| 字段名  | 描述                                                                 |
| ------- | -------------------------------------------------------------------- |
| cmd     | 协议命令字标识，为消息报文分类                                       |
| timctrl | 下发配置定时控制参数 `timctrl` 时控开关 0：关闭时控 1：开启时控 `st`：开始时间 `et`：结束时间 |
| dattim  | 下发配置数据上报时间间隔，单位：分钟                                 |
| clt     | 下发配置清虫时间间隔，单位：分钟                                     |
| tt      | 下发配置光控工作时间，单位：小时                                     |
| ds      | 下发配置设备开关机 0：关机 1：开机                                   |
| test    | 一键测试                                                             |
| reboot  | 重启                                                                 |
| update  | 升级                                                                 |  

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

离线消息主题
/yfkj/scd/offline/<imei>

报文结构
```json
{
  "cmd": "offline",
  "ext": {
    "imei": "868575028xxxxxx"
  }
}
```