网关与服务器对接协议说明¶
- 更新日期：2023年9月23日
- 适用网关型号：VG-L4GRF80
- 协议编写格式：json
更新说明： 2023年9月23日 - 更新服务器下发透传数据字段
说明： 协议由三部分组成，如下：
- method：包含指令的类型，指令的目标对象
- sys：指令的基本属性，包含指令来源对象，指令应答需求
- params：指令携带的参数或者信息，以列表的方式装载不同的数据
在线远程操作和离线usb连接操作指令一致，如果服务器的通讯协议为MQTT，则MQTT的发布和订阅主题为基于method的值重新改造得来，格式：thing.\({device_id}.\).\({process}.\)，比如：
目标网关设备的设备ID为01010101
- 获取设备信息时，发布的主题：
thing.01010101.gw.config.get - 如果要得到设备上报上来的设备信息，则需要订阅主题：
thing.01010101.sv.config.push - 接收心跳包，则需要订阅主题：
thing.01010101.sv.ping - 回复心跳包，则需要发布主题：
thing.01010101.gw.pong
表 - 字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | method | 字符串 | =============================================================== thing.\({target}.\).\({action}**<br>**\) 详见 sys.src\({process}** 过程操作，比如config、property、ack、login、ping、pong<br>**\) 操作动作，比如get、set、push。不是每个method都有action |
||
| 2 | sys | 对象 | |||
| src | 字符串 | ext、sub、gw、sv | 数据来源对象 ext为外设，比如网关的串口外设之类的 sub为无线或者有线的组网终端节点 gw为网关设备 sv为服务器 |
||
| ack | 数字 | =0，目标对象无需回复 =1，需要回复 method为thing.sv.ack的信息 |
|||
| 3 | params | 列表 |
一、网关注册信息¶
主题：thing.${device_id}.sv.login
{
"method" : "thing.sv.login",
"sys" : {
"src" : "gw",
"ack" : 1
},
"params" : [ {
"device_id" : "000000",
"pw" : "000000",
"svip" : "000.000.000.176",
"svport" : "1883",
"netCh" : "LAN",
"version" : "V1.2",
"netVer" : "2.1.2",
"netImei" : "865328060000000",
"netIccid" : ""
} ]
}
表 - params[0] 字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | device_id | 字符串 | 该信息来源设备的id，如果sys.src=gw，则device_id为网关设备的id |
||
| 2 | pw | 字符串 | 服务器登陆密码，用于设备登录判断 | ||
| 3 | svip | 字符串 | 服务器ip地址 | ||
| 4 | svport | 字符串 | 服务器端口 | ||
| 5 | netCh | 字符串 | 当前网关联网通道， LAN表示正使用以太网联网， SIM表示正使用4G网络联网 |
||
| 6 | version | 字符串 | 当前网关固件版本 | ||
| 7 | netImei | 字符串 | 当前网关4G模组的imei号，可用于4G模组的远程升级等用途 | ||
| 8 | netVer | 字符串 | 当前网关4G模组固件版本，可用于4G模组的远程升级等用途 |
服务器回复
{
"method": "thing.gw.ack",
"sys": {
"src": "sv",
"ack": 0
},
"params": [{
"datetime": "2023-09-12 16:23:15"
}]
}
表 - params[0] 字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | datetime | 字符串 | 当前网络时间，格式：YYYY-MM-DD HH:mm:ss |
二、网关心跳信息¶
当服务器收到该信息时，必须需回复pong信息，网关一个小时内没有收到任何数据，将自动重启设备
主题：thing.${device_id}.sv.ping
{
"method" : "thing.sv.ping",
"params" : [ {
"gwTemp" : "31.02",
"rf0Rssi" : -109
} ],
"sys" : {
"src" : "gw",
"ack" : 1
}
}
表 - params[0] 字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | gwTemp | 字符串 | 当前网关的设备温度，单位：摄氏度 | ||
| 2 | rf0Rssi | 数字 | 有符号整型类型，环境无线信号强度，单位：dBm |
网关心跳服务器响应信息¶
主题：thing.${device_id}.gw.pong
{
"method" : "thing.gw.pong",
"sys" : {
"src" : "sv",
"ack" : 0
},
"params" : [ {
"time" : "2023-08-12 22:11:35"
} ]
}
表 - params[0].字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | time | 字符串 | 当前日期时间，格式：YYYY-MM-DD hh:mm:ss |
三、mqtt遗嘱信息¶
主题：thing.${device_id}.sv.will
备注：
- 当网关设备掉线超时后服务器会向订阅了主题为thing.${device_id}.sv.will的客户端发布该主题数据
{
"method" : "thing.sv.will",
"sys" : {
"src" : "gw",
"ack" : 0
},
"params" : [ ]
}
表 - params[0] 字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 |
四、lora无线数据透传普通数据上报到服务器¶
主题：thing.${device_id}.sv.property.push
透传数据包：01030002000125CA，格式：hex
{
"method" : "thing.sv.property.push",
"sys" : {
"src" : "sub",
"ack" : 0
},
"params" : [ {
"drtPkt" : {
"device_id" : "00000000",
"rssi" : -53,
"dtTyp" : "hex",
"packet" : "01030002000125CA",
"pktLen" : 8
}
} ]
}
表 - params[0].drtPkt字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | device_id | 字符串 | 该信息来源设备的id，如果sys.src=sub，则device_id为终端节点设备的id |
||
| 3 | rssi | 数字 | 有符号整型，无线数据包信号强度 | ||
| 4 | dtTyp | 字符串 | hex、str | packet数据包的数据格式 | |
| 5 | packet | 字符串 | 透传数据包 | ||
| 6 | pktLen | 数字 | 透传数据包长度 |
五、服务器下发无线透传普通数据信息¶
主题：thing.${device_id}.sub.property.push
透传数据包：01030002000125CA，格式：hex
若为多通道无线模块的网关，默认使用第一个模块作为下行数据通道
{
"method" : "thing.sub.property.push",
"sys" : {
"src" : "sv",
"ack" : 0
},
"params" : [ {
"drtPkt" : {
"device_id" : "00000000",
"dtTyp" : "hex",
"groupId" : 0,
"rfCh" : 0,
"packet" : "01030002000125CA"
}
} ]
}
表 - params[0].drtPkt字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | device_id | 字符串 | 必填，目标终端节点设备ID | ||
| 2 | dtTyp | 字符串 | hex、str | 非必填，packet数据包的数据格式，不填为str |
|
| 3 | groupId | 数字 | 0~15 | 0 | 非必填，组ID |
| 4 | rfCh | 数字 | 0~255 | 非必填，，无线信道，不填则使用设备当前设置信道 | |
| 5 | packet | 字符串 | 必填，透传数据包 |
六、RS485或串口数据透传普通数据上报到服务器¶
主题：thing.${device_id}.sv.property.push
透传数据包：313233343536373839，格式：hex
{
"params": [{
"drtPkt": {
"packet": "313233343536373839",
"pktLen": 9,
"dtTyp": "hex"
}
}],
"method": "thing.sv.property.push",
"sys": {
"src": "ext",
"ack": 0,
"prdType": 0
}
}
表 - params[0].drtPkt字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | device_id | 字符串 | 目标终端节点设备ID | ||
| 2 | dtTyp | 字符串 | hex、str | packet数据包的数据格式 | |
| 3 | packet | 字符串 | 透传数据包 | ||
| 4 | pktLen | 数字 | 透传数据包长度 |
七、服务器下发透传普通数据信息到RS485或串口¶
主题：thing.${device_id}.ext.property.push
透传数据包：01030002000125CA，格式：hex
{
"method" : "thing.ext.property.push",
"sys" : {
"src" : "sv",
"ack" : 0
},
"params" : [ {
"drtPkt" : {
"dtTyp" : "hex",
"packet" : "01030002000125CA"
}
} ]
}
表 - params[0].drtPkt字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | dtTyp | 字符串 | hex、str | packet数据包的数据格式 | |
| 2 | packet | 字符串 | 透传数据包 |
八、网关RS485-modbus温度传感器数据上报¶
主题：thing.${device_id}.sv.property.push
{
"method": "thing.sv.property.push",
"sys": {
"src": "ext",
"ack": 0,
"prdType": 0
},
"params": [{
"mdbusTempt": {
"Temp": "32.4",
"device_id": 1
}
}]
}
表 - params[0].mdbusTempt字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | Temp | 字符串 | 通过RS485的modbus协议读取到的温度，单位：摄氏度，精度：0.5摄氏度 | ||
| 2 | device_id | 数字 | modbus设备地址 |
九、网关串口外挂GNSS定位模组数据上报¶
当未收到有效卫星数据时，1分钟上报一次，收到有效卫星数据时，立即上报
定位模组的协议规范：CASIC： 多模卫星导航接收机协议规范，包括通用标准NMEA0183协议 已测试通过模组型号: 1、VG7669T160N0MA 2、VG7669T160N0SA
主题：thing.${device_id}.sv.property.push
{
"params": [{
"navdata": {
"alt": "76.54",
"hdop": "0.7",
"vdop": "1.0",
"pdop": "1.2",
"lat": "22.681345",
"lon": "113.985299",
"speed": "0.31",
"max_sv_cn0": "36",
"max_sv_name": "GPS",
"datetime": "2023-08-29 09:22:11:000",
"num_sv_view": "4",
"num_sv_fix": "23",
"fix_valid": "1",
"heading": "341.25"
}
}],
"method": "thing.sv.property.push",
"sys": {
"src": "ext",
"ack": 0,
"prdType": 0
}
}
表 - params[0].navdata字段说明 数据长度：351字节
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | alt | 字符串 | 海拔高度值，单位：米 | ||
| 2 | hdop | 字符串 | 水平精度因子 | ||
| 3 | vdop | 字符串 | 垂直精度因子 | ||
| 4 | pdop | 字符串 | 位置精度因子 | ||
| 5 | lat | 字符串 | 纬度 | ||
| 6 | lon | 字符串 | 经度 | ||
| 7 | speed | 字符串 | 速度 | ||
| 8 | max_sv_cn0 | 字符串 | 获取到的最大卫星信号噪声比，每次上报都会更新 | ||
| 9 | max_sv_name | 字符串 | 获取到的最大卫星信号噪声比对应的卫星系统名称，每次上报都会更新 | ||
| 10 | datetime | 字符串 | UTC世界标准时间，经度0度时区的时间，若需转换为当地时间，则需要根据所在地区的时区转换。比如在中国，时区为东八区，比0时区早8个小时，读到的datetime为2023-08-29 09:22:11:000，则当地时间为北京时间2023-08-29 17:22:11:000 |
||
| 11 | num_sv_view | 字符串 | 接收到有效信号的卫星数量 | ||
| 12 | num_sv_fix | 字符串 | |||
| 13 | fix_valid | 字符串 | 是否为固定值 | ||
| 14 | heading | 字符串 | 航向角 |
当出现错误时数据上报
{
"params" : [ {
"navdata" : {
"error" : "error"
}
} ],
"method" : "thing.sv.property.push",
"sys" : {
"src" : "ext",
"ack" : 0,
"prdType" : 0
}
}
表 - params[0].navdata字段说明
| 序号 | 字段 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| 1 | error | 字符串 | 当存在该字段时，表示定位模组出错，工作不正常。10分钟上报一次 |