Главная Обзор Помощь
Регистрация Вход
yf_yzl
/
yfdoc
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: main
Ветки Метки
yfdoc
/
zh-cn
/
scd
/
scd.md

scd.md 18 KB
Постоянная ссылка История Исходник

物联网杀虫灯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. 接口设置是我们这边进行配置，您只需要把接口发给对接人员就可以了。

设备数据报文结构

{
  "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 来保证命令必达，也可以通过服务器主动下发查询状态和下发查询配置指令，来判断是否执行成功。

报文结构

{
  "cmd": "<协议命令字>",
  "ext": {<message>}
}

协议命令字 cmd 为报文分类定义的英文标识。 ext 为各个命令字对应的信息内容。 以上数据内容为 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)

参数配置
报文结构

{
  "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

下行通信
下发查询请求
查询状态报文结构

{
  "cmd": "read",
  "ext": "data"
}

字段说明

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

参数配置下发
报文结构

{
  "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

控制指令下发

{
	"cmd": "paramconf",
	"ext": {
		"timctrl": 1,
		"st": 20,
		"et": 2,
		"dattim": 10,
		"clt": 30,
		"tt": 4,
		"ds": 1
	}
}

下发一键测试报文结构

{
  "cmd": "test"
}

下发重启报文结构

{
  "cmd": "reboot"
}

下发升级报文结构

{
  "cmd": "update"
}

字段说明

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

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

离线消息主题 /yfkj/scd/offline/

报文结构

{
  "cmd": "offline",
  "ext": {
    "imei": "868575028xxxxxx"
  }
}