update

zh-cn/cbd.md

@@ -180,4 +180,261 @@
 | imei           | 设备序列号                                                          |
 | Image          | 拍照图片（图片链接，建议下载保存到本地）                              |
 | Result_image   | 识别结果图片（图片链接，建议下载保存到本地）                           |
-| Result         | 昆虫种类及数目（如模型未识别到害虫，`Result_image` 与 `Result` 数据为 0）     |
+| Result         | 昆虫种类及数目（如模型未识别到害虫，`Result_image` 与 `Result` 数据为 0）     |  
+
+
+# 物联网自动虫情测报灯与服务器端交互通讯细节
+
+## 简述
+
+本文档主要用于阐述物联网自动虫情测报灯与服务器端进行交互的通讯细节，其中包括物联网自动虫情测报灯与服务器之间使用的通信协议和交互通讯协议两部分。
+
+## 适用范围
+
+适用于【通用物联网自动虫情测报灯】与服务器之间的通讯。
+
+## 对接说明
+
+1. **数据上传频率**：
+   - 设备数据默认是每30分钟上传一次。
+   - 图片数据在设备工作时间段内每20分钟上传一次。如果设备处于温控或雨控状态，不会拍照，但会正常上传设备数据。
+
+2. **温控、雨控说明**：
+   - **温控**：为了冬季保护电池。即使供电系统是市电，在这种温度条件下，并不会发生虫情，因此设计为系统待机，不再拍照，符合节能降耗的思想。
+   - **雨控**：为了防止设备进水而设计，发生雨控时进入待机状态，不再工作和拍照。
+
+3. **图片保存**：
+   - 图片数据中的链接需要下载并保存到本地。保存时不要直接保存图片链接到数据库，因为图片链接可能会失效。应将下载后的图片保存到本地，并将本地路径存入数据库。
+
+4. **设备数据内容**：
+   - 包含设备号、SIM卡号、环境温湿度、工作状态、经纬度、电压等。
+
+5. **图片数据内容**：
+   - 不识别：包含原图链接和设备号。
+   - 识别：包含设备号、原图链接、识别后的图片链接、害虫名称和数量。
+
+6. **设备拍照时间**：
+   - 设备收集时间 + 加热时间 = 设备拍照时间。
+
+7. **数据格式**：
+   - 设备数据格式不可变，不能按接收方增加或减少字段。如有需求请联系销售经理。
+
+8. **接口安全**：
+   - 可以针对传输方IP做限制，非传输方IP不允许调用接口。传输方IP可以联系对接人员提供。
+
+9. **数据独立性**：
+   - 图片和设备数据为相互独立的两种数据。
+
+## 相关主题
+
+- **所有上行通信的主题**：`/yfkj/cbd/pub/<imei>`
+- **所有下行通信的主题**：`/yfkj/cbd/sub/<imei>`
+- **离线消息主题**：`/yfkj/cbd/offline/<imei>`
+
+## 查询状态报文结构
+
+### MQTT 下发查询
+
+```json
+{
+  "cmd": "read",
+  "ext": "data"
+}
+```
+定时数据上报和查询的回复报文  
+```json
+{
+  "cmd": "data",
+  "ext": {
+    "hst": "110",
+    "ds": "1",
+    "gs": "0",
+    "dver": "1.7.4(140)HK",
+    "hs": "0",
+    "shake_sec": "1",
+    "tpl": "5",
+    "dat_f": "30",
+    "tph": "70",
+    "lat": "041.0501403",
+    "st": "21",
+    "tt": "8",
+    "lng": "111.0030517",
+    "vbat": "24.15",
+    "imei": "867038039304375",
+    "htim": "20",
+    "collt": "10",
+    "et": "1",
+    "iccid": "89860492192090447636",
+    "dtype": "3",
+    "batStatus": "0",
+    "dnds": "0",
+    "hrt": "24",
+    "proj": "DCCBD-2_HK",
+    "gps": "2",
+    "ts": "1",
+    "ws": "0",
+    "vs": "140",
+    "shake": "1",
+    "current": "0.0",
+    "ah": "30.0",
+    "at": "25.0",
+    "stamp": "20210810092758",
+    "lamp": "0",
+    "rps": "0",
+    "upds": "0",
+    "lps": "1",
+    "tps": "0",
+    "csq": "31"
+  }
+}
+```
+字段说明  
+
+| 字段名      | 描述                                                                 |
+| ----------- | -------------------------------------------------------------------- |
+| imei        | 通讯板唯一 ID                                                       |
+| iccid       | 物联网卡的 iccid 号，用于查询物联网卡的套餐、流量信息等             |
+| csq         | 信号强度                                                           |
+| lat         | 纬度                                                               |
+| lng         | 经度                                                               |
+| dtype       | 设备类型 (测报灯设备类型为 3)                                       |
+| ws          | 工作状态 0：待机，1：工作                                           |
+| dver        | 设备固件版本                                                       |
+| vbat        | 电压（单位：V）                                                    |
+| st          | 时控开始时间：0-23（当设备设置以时控模式开始工作时，该字段为开始工作时间） |
+| et          | 时控结束时间：0-23（当设备设置以时控模式开始工作时，该字段为结束工作时间） |
+| tps         | 温控：0-正常，1-保护（1：设备进入温控状态，不进入工作拍照）         |
+| lps         | 光控：0-正常，1-保护（1：设备进入光控状态，检测到白天，光控模式下白天不工作） |
+| rps         | 雨控：0-正常，1-保护（1：设备进入雨控状态时，不进入工作拍照）       |
+| collt       | 收集时间：1-30 分钟                                                |
+| current     | 功率：单位 mA                                                      |
+| hrt         | 加热仓实时温度（℃）                                                |
+| hst         | 加热仓设定温度：70-130（℃）                                        |
+| at          | 环境温度（℃）                                                      |
+| ah          | 环境湿度（%RH）                                                     |
+| stamp       | 时间戳（格式：YYYYMMDDHHmmss）                                     |
+| dat_f       | 数据上传时间间隔 单位：分钟（默认上传时间为 20 分钟）               |
+| turnon      | 开机次数，每次重启加 1                                             |
+| htim        | 加热时间：1-30 分钟                                                |
+| batStatus   | 电压状态 0-正常 1-欠压                                              |
+| tt          | 光控定时时间 1~10（当设备处于光控状态时，该字段为设备工作时间）     |
+| shake       | 震动开关:0-关，1-开                                                |
+| shake_sec   | 震动时间：1~20（步长：100ms）                                      |
+| ts          | 定时模式:0-光控，1-时控（设备工作状态，光控默认工作时间为天黑后 8 小时，时控可以设置工作时间范围） |
+| upds        | 上仓门状态 1：打开，0：关闭                                        |
+| dnds        | 下仓门状态 1：打开，0：关闭                                        |
+| lamp        | 灯管/工作状态 0：工作 1：未工作                                     |
+| fuse_voltage| 保险丝电压                                                          |
+| ds          | 设备开关状态 0：关机 1：开机                                        |
+| hs          | 加热状态                                                            |
+| tpl         | 低温保护值                                                          |
+| tph         | 高温保护                                                            |
+| proj        | 版本号                                                              |
+| vs          | 内部版本号                                                          |  
+
+下发设置
+```Json
+{
+  "cmd": "paramconf",
+  "ext": {
+    "hst": 110,
+    "collt": 10,
+    "et": 6,
+    "datt": 20,
+    "shake_sec": 1,
+    "tpl": 5,
+    "shake": 1,
+    "tph": 70,
+    "ts": 1,
+    "st": 20,
+    "htim": 20,
+    "tt": 8,
+    "ds": 0,
+    "vt": 4
+  }
+}
+```
+字段说明  
+
+| 字段名  | 描述                                                                 |
+| ------- | -------------------------------------------------------------------- |
+| hst     | 加热温度 75-130℃                                                    |
+| collt   | 收集时间 1-30 分钟                                                   |
+| et      | 结束时间：0~23（字符串）                                             |
+| datt    | 数据上传间隔：1-60 分钟                                              |
+| shake   | 震动开关：0-关 1-开                                                  |
+| shake_sec | 震动时间：100~5000 ms                                               |
+| tph     | 高温保护 50~80℃                                                     |
+| ts      | 定时模式：0：光控 1：时控                                             |
+| st      | 开始时间：0~23（字符串）                                             |
+| htim    | 加热时间：1~30 分钟                                                  |
+| tt      | 光控定时时长：1~10 小时                                              |
+| ds      | 设备开关状态 0：关机 1：开机                                          |
+| vt      | 版本类型: 1 - 1.0, 4 - 4.0                                            |  
+
+下发控制命令
+下发重启
+```json
+{
+  "cmd": "reboot"
+}
+```
+下发升级 STM32
+```json
+{
+  "cmd": "update"
+}
+```
+拍照
+```json
+{
+  "cmd": "takephoto"
+}
+```
+遗愿消息  
+
+设备默认配置了遗愿消息，当设备异常下线时（客户端断开前未向服务器发送 DISCONNECT 消息），会发布异常下线设备的遗愿消息。注意：设备离线会发送一条设备下线消息，设备上线后发送正常数据。
+
+离线消息主题
+
+/yfkj/cbd/offline/<imei>
+报文结构
+```json
+{
+  "cmd": "offline",
+  "ext": {
+    "imei": "868575028xxxxxx"
+  }
+}
+```
+图片传输
+对接说明  
+HTTP 协议：对接采用 HTTP 协议，由接收方写接口来接收 HTTP POST 数据（需从 request 的 body （字节流类型）中取数据，取到之后进行 JSON 解析）。
+图片保存：图片需要下载保存到本地。保存时不要直接保存图片链接到数据库，因为图片链接可能会失效。应将下载后的图片保存到本地，并将本地路径存入数据库。
+带害虫识别图片传输案例
+参数案例 1
+```json
+{
+  "Image": "http://www.yfzhwlw.com/pyftp/ftp_file/ykm_cbd/868956048817419/192.168.1.100_01_20200623233048184_ALARM_INPUT.jpg",
+  "Result_image": "http://www.yfzhwlw.com/result_pyftp/ftp_file/ykm_cbd/868956048817419/192.168.1.100_01_20200623233048184_ALARM_INPUTresult.jpg",
+  "Result": "62,1",
+  "imei": "867435052203452"
+}
+```
+参数案例 2
+```json
+{
+  "Result": "0",
+  "Result_image": "0",
+  "Image": "https://bigdata-image.oss-cn-hangzhou.aliyuncs.com/Basics/cbd/861551058865106/2023/8/29/861551058865106-20230829234037.jpg",
+  "imei": "861551058865106"
+}
+```
+参数说明  
+
+| 字段名       | 描述                                                                 |
+| ------------ | -------------------------------------------------------------------- |
+| imei         | 设备序列号                                                           |
+| Image        | 拍照图片（图片链接，建议下载保存）                                   |
+| Result_image | 识别结果图片（图片链接，建议下载保存）                               |
+| Result       | 结果字符串，用“种类 1,种类 1 数目#种类 2,种类 2 数目…”表示，如 “10,1#12,2”，表示种类 10 的数目是 1，种类 12 的数目是 2 |