update

zh-cn/cbd-sq/_sidebar.md

@@ -25,3 +25,34 @@
       * [nodejs语言接收数据案例](/zh-cn/cbd-sq/cbd-sq?id=nodejs语言接收数据案例)
 
       * [python语言接收数据案例](/zh-cn/cbd-sq/cbd-sq?id=python语言接收数据案例)
+
+* [测报灯mqtt协议](/zh-cn/cbd-sq/cbd-sq?id=测报灯mqtt协议)
+
+  * [简要描述](/zh-cn/cbd-sq/cbd-sq?id=简要描述)
+
+    * [术语和缩略语](/zh-cn/cbd-sq/cbd-sq?id=术语和缩略语)
+
+      * [通信协议](/zh-cn/cbd-sq/cbd-sq?id=通信协议)
+
+      * [文本传输协议](/zh-cn/cbd-sq/cbd-sq?id=文本传输协议)
+
+      * [文件传输协议](/zh-cn/cbd-sq/cbd-sq?id=文件传输协议)
+
+      * [主题说明](/zh-cn/cbd-sq/cbd-sq?id=主题说明)
+
+      * [上行通信](/zh-cn/cbd-sq/cbd-sq?id=上行通信)
+
+      * [状态报告](/zh-cn/cbd-sq/cbd-sq?id=状态报告)
+
+      * [交互协议](/zh-cn/cbd-sq/cbd-sq?id=交互协议)
+
+      * [下发拍照指令](/zh-cn/cbd-sq/cbd-sq?id=下发拍照指令)
+
+      * [遗愿消息](/zh-cn/cbd-sq/cbd-sq?id=遗愿消息)
+
+      * [设备带害虫识别图片传输说明1](/zh-cn/cbd-sq/cbd-sq?id=设备带害虫识别图片传输说明1)
+
+      * [设备不带害虫识别图片传输说明1](/zh-cn/cbd-sq/cbd-sq?id=设备不带害虫识别图片传输说明1)
+
+* [常见问题解答](/zh-cn/cbd-sq/cbd-sq?id=常见问题解答)
+

zh-cn/cbd-sq/cbd-sq.md

@@ -216,3 +216,366 @@ offline 参数返回示例
 ###  python语言接收数据案例  
 ![python语言接收数据案例](../zh-cn/images/python语言接收数据案例.png)
 
+
+# 测报灯mqtt协议
+
+## 简要描述
+
+本文档主要用于阐述云飞自动虫情测报灯与服务器端进行交互的通讯细节，其中包括自动虫情测报灯与服务器之间使用的通信协议和交互通讯协议两部分。
+
+## 术语和缩略语
+
+| 缩略语 | 含义 |
+|--------|------|
+| imei   | 杀虫灯设备的通讯 ID，可作为设备唯一标识 |
+| MQTT   | 公开的物联网通信协议 |
+| QOS    | 0,1,2 -- MQTT 的质量协议 |
+| cmd    | 协议命令字标识，为消息报文分类 |
+| status | 状态报告协议命令字，报文中使用 |
+| data   | 数据报告协议命令字，报文中使用 |
+| paramconf | 参数配置协议命令字，报文中使用 |
+| read   | 服务器下发查询协议命令字，报文中使用 |
+
+## 通信协议
+
+### 文本传输协议
+
+云飞自动虫情测报灯文本数据使用主流公开的 MQTT 协议 V3.1.1 版本作为通讯协议，默认 QOS 质量等级为 0。服务器端需要实现 MQTT 协议的转发和解析，数据的上报为 JSON 格式。MQTT V3.1.1 协议详见附件。
+
+### 文件传输协议
+
+云飞自动虫情测报灯文本数据使用主流公开的 MQTT 协议和 HTTP 协议作为文件传输协议，可根据用户需求来自行选择。
+
+根据 MQTT 的特性，下发服务不必回复，可以通过设置下位机的 QOS 为 2 或 1 来保证命令必达，也可以通过服务器主动下发查询状态和下发查询配置指令，来判断是否执行成功。
+
+### 主题说明
+
+关于主题 `sub` 和 `pub` 的说明，注意不要混淆：
+- 除离线消息主题：`/yfkj/cbd/offline/2001` 以外
+- 所有上行通信的主题：`"/yfkj/cbd/pub/2001"`
+- 所有下行通信的主题：`"/yfkj/cbd/sub/2001"`
+
+其中 `2001` 指设备唯一 `imei`
+
+### 上行通信
+
+#### 状态报告
+
+**报文结构：**
+
+```json
+{
+  "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,
+    "stamp": "20180301211805",
+    "gps": "2"
+  }
+}
+```
+
+字段说明  
+
+| 字段    | 含义或表示的内容                                    |
+| ------- | --------------------------------------------------- |
+| 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   | 时间戳：20180301211805                              |
+| ws      | 工作状态 0：待机，1：工作                           |
+| lamp    | 灯管状态 0：灭，1：亮 (只有 ws=1 灯管状态才起作用)  |
+| lux     | 光照强度                                            |
+| vs      | 内部版本号                                          |
+| gps     | 定位说明, 0：手动定位, 1：GPS定位, 2：基站定位      |  
+
+数据报告
+报文结构：
+
+```json
+
+{
+  "cmd": "data",
+  "ext": {
+    "imei": "865650043207246",
+    "at": 245,
+    "ah": 745,
+    "hrt": 55,
+    "rps": 0,
+    "lps": 0,
+    "tps": 0,
+    "lat": "34.815187",
+    "lng": "113.67336",
+    "lamp": 0,
+    "lux": 1,
+    "ws": 0,
+    "stamp": "20180301211805"
+  }
+}
+```
+字段说明  
+
+| 字段    | 含义或表示的内容                                                   |
+| ------- | ------------------------------------------------------------------ |
+| imei    | 通讯板唯一 ID                                                      |
+| at      | 环境温度 (单位：℃) (注：温度值为乘以10后的结果，需要除以10得到温度值) |
+| ah      | 环境湿度 (单位：%RH) (注：湿度值为乘以10后的结果，需要除以10得到相对湿度值) |
+| hrt     | 加热仓实时温度 (单位：℃)                                           |
+| rps     | 雨控状态 1：雨控，0：正常                                          |
+| lps     | 光控状态                                                           |
+| tps     | 温控状态                                                           |
+| lat     | 纬度                                                               |
+| lng     | 经度                                                               |
+| stamp   | 时间戳：20180301211805                                             |
+| ws      | 工作状态 0：待机，1：工作                                          |
+| lamp    | 灯管状态 0：灭，1：亮 (只有 ws=1 灯管状态才起作用)                 |
+| lux     | 光照强度                                                           |  
+
+### 交互协议
+下行通信
+下发查询请求
+查询状态报文结构：
+
+```json
+{
+  "cmd": "read",
+  "ext": {
+    "type": "paramconf"
+  }
+}
+```
+字段说明  
+
+| 字段    | 含义或表示的内容                                                   |
+| ------- | ------------------------------------------------------------------ |
+| type    | 读取参数类型                                                       |
+| status  | 请求读取设备状态信息                                   |
+| data    | 请求读取数据信息                                         |
+| paramconf|请求读取参数配置信息                                |  
+
+报文结构：
+
+```json
+{
+  "cmd": "paramconf",
+  "ext": {
+    "imei": "3001",
+    "ts": 0,
+    "tt": 6,
+    "st": 20,
+    "et": 6,
+    "collt": 10,
+    "htim": 10,
+    "hst": 85,
+    "tph": 70,
+    "tpl": 5,
+    "datt": 20,
+    "imgres": 0,
+    "stamp": "20180301211805"
+  }
+}
+```
+字段说明  
+
+| 字段    | 含义或表示的内容                                                   |
+| ------- | ------------------------------------------------------------------ |
+| imei    | 通讯板唯一 ID                                                      |
+| ts      | 定时模式 0：光控，1：时控                                          |
+| tt      | 光控定时模式下，定时时长(1~10) (单位：小时) (默认：8 小时)        |
+| st      | 定时开始时间 (默认 20:00)                                          |
+| et      | 定时结束时间 (默认 06:00)                                          |
+| collt   | 收集时间、落虫时间（5~20）(单位：分钟) (默认 10 分钟)             |
+| htim    | 设定的加热时间（5~20）(单位：分钟) (默认 10 分钟)                  |
+| hst     | 设定的加热温度（75~125）(单位：℃) (默认 85℃)                      |
+| tph     | 高温保护阈值温度 (单位：℃) (默认 70℃)                             |
+| tpl     | 低温保护阈值温度 (单位：℃) (默认 5℃)                              |
+| datt    | 数据上传时间间隔（5~60）(单位：分钟) (默认 20 分钟)                |
+| imgres  | 照片分辨率 <br> - 0：高(1280*960) <br> - 1：中(1024*768) <br> - 2：低(640*480) <br> (默认 2) |
+| stamp   | 时间戳：20180301211805                                             |  
+
+参数配置下发
+报文结构：
+
+```json
+
+{
+  "cmd": "paramconf",
+  "ext": {
+    "ts": 0,
+    "tt": 6,
+    "st": 20,
+    "et": 6,
+    "collt": 10,
+    "htim": 10,
+    "hst": 85,
+    "tph": 70,
+    "tpl": 5,
+    "datt": 20,
+    "imgres": 0
+  }
+}
+```
+
+
+字段说明  
+
+| 字段 | 描述 |
+| --- | --- |
+| ts | 定时模式 0：光控， 1：时控 (默认：1 时控) |
+| tt | 光控定时模式下，定时时长(1~10) (单位：小时) (默认：8 小时) |
+| st | 定时开始时间 (默认时间：20：00) |
+| et | 定时结束时间 (默认时间：06：00) |
+| collt | 收集时间、落虫时间（5~20）(单位：分钟) (默认：10 分钟) |
+| htim | 设定的加热时间（5~20）(单位：分钟) (默认：10 分钟) |
+| hst | 设定的加热温度（75~125）(单位：℃) (默认：85℃) |
+| tph | 高温保护阈值温度 (单位：℃) (默认：70℃) |
+| tpl | 低温保护阈值温度 (单位：℃) (默认：5℃) |
+| datt | 数据上传时间间隔（5~60）(单位：分钟) |
+| imgres | 照片分辨率 0：高(1280*960)；1：中(1024*768)；2：低(640*480) (默认：2) |
+
+## 下发拍照指令
+
+下发拍照指令后，图片会通过接收图片接口发送。
+
+```json
+{
+  "ext": {
+    "type": "takephoto"
+  },
+  "cmd": "ctrl"
+}
+```
+### 遗愿消息  
+设备默认设置配置了MQTT遗愿消息。当设备异常下线时，MQTT消息服务器会发布异常下线设备的遗愿消息。订阅设备遗愿消息可实现对设备在线和离线状态的监控。
+
+离线消息主题：/yfkj/cbd/offline/<imei>
+
+报文结构：
+```json
+{
+  "cmd": "offline",
+  "ext": {
+    "imei": "865650043207246"
+  }
+}
+```
+### 设备带害虫识别图片传输说明1  
+数据上传时间默认是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 |  
+
+
+### 设备不带害虫识别图片传输说明1  
+接口说明: 
+对接采用 HTTP 协议，由接收方写接口来接收 HTTP POST 数据（需从 request 的 body（字节流类型）中取数据，取到之后进行 JSON 解析）。图片和设备数据为相互独立的两种数据。  
+图片保存的时候不要直接保存图片链接到数据库，有可能图片链接会失效，导致图片展示不了的问题，需要下载保存到本地。
+
+示例  
+```json
+{
+  "Image": "http://www.yfzhwlw.com/cbd_img/868956044831318/2020/09/202009191823.jpg",
+  "imei": "865650043207246"
+}
+```
+图片参数说明  
+
+| 字段名 | 描述 |
+| ------ | ---- |
+| imei   | 设备序列号 |
+| Image  | 拍照图片（图片链接，建议下载保存） |  
+
+
+# 常见问题解答
+
+## 1. 测报灯拍照时间
+**问：** 测报灯拍照时间   
+![测报灯拍照时间设置图](../zh-cn/images/测报灯拍照时间设置图.png)  
+**答：** 默认数据上传时间为20分钟一次，图片上传时间为30分钟一次。测报灯拍照时间是在设备设置的工作时间段内拍照，拍照时间间隔为设置的落虫时间+加热时间为一次照片的间隔时间。
+
+## 2. 设备拍照时多时少，偶尔不拍照
+**问：** 设备拍照时多时少，偶尔不拍照  
+**答：** 首先排查设备是否是雨控和温控状态。雨控是为了防止设备进水而设计，发生雨控也进入待机，不再工作和拍照；温控是为了冬季保护电池的。以上两种状态设备均为待机状态，不会进行拍照动作。
+
+## 3. 设备数据传输方式
+**问：** 设备数据传输方式  
+**答：** 有两种对接方式：
+- **HTTP对接方式**：平台对平台，通过服务器转发完成。客户需提供接收数据的接口，被动接收数据，我们这边主动推送数据，推送数据频率与设备设置的数据、图片时间有关。
+- **MQTT方式**：需要客户那边启动一个MQTT服务，设备通过MQTT传输协议直接上传客户方服务器。但是这一对接方式中，设备图片需使用HTTP方式。
+
+## 4. 测报灯图片是怎样传输的
+**问：** 测报灯图片是怎样传输的  
+**答：** 图片是通过HTTP传输的，是图片链接，需要下载保存到本地，不能直接把图片链接保存到数据库中，因为图片链接有可能会失效。
+
+## 5. 害虫识别是在设备上进行识别的还是在服务器上进行识别的
+**问：** 害虫识别是在设备上进行识别的还是在服务器上进行识别的  
+**答：** 是在服务端进行识别的，然后与图片一起通过HTTP协议传输过去。
+
+## 6. 害虫识别数据包含哪些
+**问：** 害虫识别数据包含哪些  
+**答：** 包含原图链接、识别后的图片链接、害虫编号（用于害虫表中的害虫编号对应，与对接人员要）、害虫数量。
+
+## 7. 使用HTTP对接方式接口地址配置在什么地方
+**问：** 使用HTTP对接方式接口地址配置在什么地方  
+**答：** 直接把接口地址发给对接人员，由对接人员进行配置，一台设备不能接多个转发地址（数据一个，图片一个）。如果需要多个，可以由接收方接收到数据后再次转发。
+
+## 8. 设备数据都包含有哪些数据
+**问：** 设备数据都包含有哪些数据  
+**答：** 环境温湿度、经纬度、雨控、温控、工作状态、定时模式等数据。
+
+## 9. 光控、时控工作模式代表什么
+**问：** 光控、时控工作模式代表什么  
+**答：** 光控就是设定工作时长，时控是设定工作范围。