目录
本文件是网关和平台的交互协议，首先在网关和网关管理工具上实现。
协议MQTT上实现，基于无连接的MQTT消息，消息为UTF-8编码的JSON数据结构（涉及到不同编码的在数据包内特别处理）。
协议计划扩展到http和通用串行总线，仍保持同样的消息处理模式。
协议包括设备管理和数据上报两个。
设备管理包括网关注册、网关更新、网关配置、状态查询等功能。
数据操作包括实时上报、历史上报、数据确认、数据写入等功能。
基本格式：
|
数据项 |
平台 |
功能 |
必填 |
说明 |
|
func |
|
功能 |
是 |
|
|
ts |
|
时间戳 |
|
数据包生成的时间戳 |
|
uid |
|
唯一标识 |
|
唯一识别数据包 |
|
data |
|
数据项 |
|
每个func的独特数据 |
数据序列是网关上报的数据的序列，单调递增。网关注册时会报告起始数据序列值-1（相当于已经确认的数据的最大值，如果发生了数据丢弃，这个值表明这些数据已经不存在）。已经确认数据无法再次上报。
平台定时或定量向网关发送数据确认消息。如果平台长时间没有确认数据，网关可能丢弃部分数据或停止采集。
数据序列从1开始递增。
普通数据为json格式。压缩数据则以大写字母“Z”开头，加密数据以大写字母“E”开头，先压缩后加密的数据则以大写字母“EZ”开头。
网关默认不压缩，默认不对reg、hb和push加密。
网关使用约定的密码加密其它上报数据。网关存在初始密码并可通过平台指令更改密码。
用于网关对平台下发的各种指令的应答，部分指令规定了专门的应答，通用和专用的应答平台都应该支持。
应答包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
func |
功能 |
是 |
对应的下发指令的func |
|
uid |
唯一标识 |
是 |
对应的下发指令的uid |
|
state |
状态 |
是 |
0:失败 1:成功 |
|
error_code |
错误码 |
|
如果失败，建议携带错误码 |
|
message |
附加信息 |
|
可能是出错信息也可能是执行结果 |
{
"func": "respond",
"ts": 1706676012126,
"uid": "1e0b8d3d86f28702bda02f6998897bdb",
"data": {
"func": "sudo",
"uid": "请求包的uid",
"state": 1,
"error_code": 0,
"message": ""
}
}
指定网关的日志级别。
|
Data项 |
功能 |
必填 |
说明 |
|
loglevel |
日志级别 |
是 |
0为正常，1为调试。仅对正在运行的程序有效，重启后失效。 |
调试用，网关无需应答。
设置平台下发指令的处理时间（某些指令可能导致死锁从而影响网关运行，如果发生因为处理时间限制而未能完成处理的情况可适当增大超时设置）。
|
Data项 |
功能 |
必填 |
说明 |
|
overtime |
超时时间（秒） |
是 |
大于等于30 |
用于尚未正规化的信息上报。
|
Data项 |
功能 |
必填 |
说明 |
|
interface_code |
接口 |
|
相关的接口，未填则属于整体信息 |
|
device_code |
设备 |
|
未填则属于整个接口 |
|
channel_code |
通道 |
|
未填则属于整个设备 |
|
messsage |
消息 |
是 |
信息文本 |
网关上电时注册信息同时发送到专用topic："device_gateway/reg"，此topic仅用来进行网关发现。
注册信息同reg。
由网关发起，向平台注册自身，汇报自身的序列号、硬件版本、软件版本。
平台返回注册成功或失败。
网关请求包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
sn |
序列号 |
是 |
网关序列号IMEI |
|
model |
型号 |
|
硬件型号，5G网关、4G网关、wifi网关 |
|
sw_version |
软件版本 |
是 |
网关程序的版本 |
|
iccid |
SIM卡号 |
|
SIM卡号（如果有） |
|
latitude |
纬度 |
|
|
|
longitude |
经度 |
|
|
|
key_seq |
配置的密钥标识 |
|
|
|
current_key_seq |
实际的密钥标识 |
|
|
|
data_sequence |
数据序列 |
|
已确认的数据序列，这些数据已经在网关上丢弃，无法再次提供 |
|
|
uid |
|
|
|
start_time |
程序启动时间 |
|
程序的启动时间 |
|
uptime |
系统启动时间 |
|
操作系统的启动时间 |
平台应答包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
code |
处理状态 |
是 |
0成功，1失败 |
平台发起，平台认为网关需要注册时下发。网关可能必须先注册才能发送其它数据包（由平台决定），平台发送此数据包后可能会立即关闭网关的连接，也可能保持连接并丢弃所有非注册数据包。网关收到此数据包应立即重新注册或重新连接平台注册。
包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
|
|
|
无data项 |
{
"func": "notreg",
"sn": "ABCD1234567890"
}
平台现在为网关主动上报。2-配置轮询中 3-无配置 4-主板通信异常 5-点位读取异常
改为平台请求。
平台下发包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
|
|
|
无data项 |
{
"func": "state"
}
网关上报包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
gw_state |
网关状态 |
|
|
|
mobile_type |
连接类型 |
|
5G/4G/Wifi |
|
csq |
信号强度 |
|
|
|
interface_state[] |
设备状态 |
|
每个接口的状态 |
Interface_state格式：
|
数据项 |
功能 |
必填 |
说明 |
|
interface_state |
接口状态 |
|
已连接、未连接、连接失败 |
|
interface_code |
接口名 |
|
|
|
device_state[] |
设备状态 |
|
每个设备的状态，包含存在错误的设备 |
Device_state格式：
|
数据项 |
功能 |
必填 |
说明 |
|
device_state |
设备状态 |
|
|
|
device_code |
设备标识 |
是 |
|
|
channel_state[] |
设备状态 |
|
每个通道的状态，包含存在错误的通道 |
Channel_state格式：
|
数据项 |
功能 |
必填 |
说明 |
|
channel_state |
通道状态 |
|
|
|
Channel_write_state |
通道写入状态 |
|
|
|
channel_code |
通道标识 |
是 |
|
{
"func": "state",
"ts": 1706681745689,
"uid": "529a9d42abf8bc75b1fde02ec59e3d01",
"data": {
"gw_state": 0,
"mobile_type": "5G",
"csq": "27",
"interface_state": [
{
"interface_code": "",
"interface_state": 1,
"device_state": [
{
"device_code": "device503",
"device_state": 0,
"channel_state": [
{
"channel_no": 0,
"channel_code": "code1",
"channel_name": "规格",
"channel_state": 1,
"channel_write_state": 0
}
]
}
]
},
{
"interface_code": "",
"interface_state": 2,
"device_state": [
{
"device_code": "La1",
"device_state": 0,
"channel_state": [
{
"channel_no": 0,
"channel_code": "0",
"channel_name": "",
"channel_state": 0,
"channel_write_state": 0
},
{
"channel_no": 1,
"channel_code": "1",
"channel_name": "testBit",
"channel_state": 0,
"channel_write_state": 0
}
]
}
]
}
]
}
}
网关主动上报。仅当一段时间内没有任何信息上报的时候发送。
无需特别数据。
{
"func": "hb",
"ts": 1706681046297,
"uid": "58261d73bcbf864005185c4f814c9aa0",
"data": {
"hb": 1,
"ts": 1706681046298,
}
}
网关上报异常。
|
Data项 |
功能 |
必填 |
说明 |
|
interface_code |
接口 |
否 |
消息相关的网口或串口标识 |
|
device_code |
设备 |
否 |
消息相关的设备标识 |
|
channel_code |
通道 |
否 |
消息相关的通道标识 |
|
message |
消息 |
是 |
消息内容 |
升级网关软件，由平台发起，提供一个下载链接。网关应答升级成功或失败。
清除网关的协议配置，由平台发起，网关应答。
{"func":"reset","data":{"seq":"6a67acf6935040c4bf78384c9ce2d628"}}
网关程序下次启动时生效。
数据结构：
|
Data项 |
子项 |
功能 |
必填 |
说明 |
|
protocolCode |
|
协议标识 |
是 |
|
|
interfaceCode |
|
接口名称 |
否 |
串口名称，非串口协议可不填 |
|
resolvePropertyMap |
|
接口参数 |
是 |
消息相关的通道标识 |
|
|
rate |
采集频率 |
是 |
秒 |
|
（非串口） |
ip |
|
是 |
|
|
port |
|
是 |
|
|
|
（串口） |
serial_port |
串口名 |
|
不可与interfaceCode同时为空 |
|
baudRate |
波特率 |
是 |
最高115200 |
|
|
parity |
校验 |
是 |
N E O |
|
|
dataBit |
数据位 |
是 |
5 6 7 8 |
|
|
stopBit |
停止位 |
是 |
1 2 |
|
|
timeout |
响应时间 |
是 |
实际未用（库有问题） |
|
|
confTabs[] |
|
设备数组 |
是 |
见下表 |
confTabs的每个数组成员：
|
confTabs []项 |
子项 |
功能 |
必填 |
说明 |
|
deviceCode |
|
设备标识 |
是 |
全局唯一 |
|
encodeType |
|
编码类型 |
|
仅用于隧道协议，hex ascii |
|
stationCode |
|
从站号 |
|
仅用于非隧道协议 |
|
resolveParamConfigVOList[] |
|
通道列表数组 |
是 |
秒 |
|
|
paramCode |
通道标识 |
是 |
|
|
|
paramName |
通道名称 |
是 |
|
|
|
paramCommand |
指令 |
|
仅用于隧道协议，并且隧道协议不使用后续所有字段 |
|
|
dataType |
数据类型 |
是 |
自本字段以下仅适用于非隧道协议 |
|
|
paramAddr |
地址 |
是 |
使用functionCode则基于0，使用zone（仅用于从csv配置）则基于1 |
|
|
functionCode |
功能码 |
是 |
注意与PCL分区的关系 |
|
|
dataLength |
数据长度 |
是 |
实际仅用于string类型 |
|
|
processType |
读写类型 |
是 |
|
|
|
reportStrategy |
上报类型 |
是 |
1-按采集频率上报 2-变化上报 3-监听上报(尚未支持) 4-条件上报（尚未支持） 5-依赖上报6-变化触发全量 |
|
|
transferRuleStr |
字节序 |
|
ABCD AB 适用于所有数据类型包括string |
|
|
associationParamCode |
依赖的通道标识 |
|
用于依赖上报 |
尚未规范化的特征：
|
项 |
平台 |
功能 |
必填 |
说明 |
|
zone |
|
Plc分区 |
|
目前仅在csv中使用，使用此字段配置时地址基于1（网关执行时会自动修正指令） |
|
collectorRate |
|
采集频率或变化上报的变化百分比 |
|
目前仅在csv中使用，变化幅度超过此值才上报 |
|
charsetCode |
|
字符串编码 |
|
目前仅在csv中使用，设备使用的编码，网关与平台交互始终是utf-8，但设备使用的编码可能是本地编码，如果设置了此值，网关会尝试做编码转换 |
平台下发，网关应答。
下发格式：
{"func":"ip","data":{"phyConnect":"a","ip":"b","gateway":"c","seq":"1706682377329","ts":1706682377329}}
由于硬件差异，串口名和网卡名不确定，目前缺乏与平台的沟通机制，所以网关暂时只处理ip。IP是点分格式+“/24”。
注意，由于网关是执行shell命令方式修改，网关应答成功并不一定表示操作成功。
网关支持额外的选项：
|
Data项 |
功能 |
必填 |
说明 |
|
operate |
操作 |
否 |
add(默认) del 删除 show 列出现有IP |
平台下发，网关应答。
网关程序下次启动时生效。由于网关需要支持不同的平台，因此需要对协议做些修改。
|
Data项 |
功能 |
必填 |
说明 |
|
comment |
说明 |
|
|
|
type |
连接类型 |
是 |
MQTT MQTTS |
|
platform |
平台代码 |
|
MQTTS必填，此值影响使用的证书 |
|
hostname |
主机名 |
是 |
|
|
port |
端口 |
是 |
|
|
userid |
用户名 |
是 |
|
|
upwd |
密码 |
是 |
|
平台发起，重启网关。注意，此命令如果成功执行，可能收不到任何应答（因为网关已经重启）。
无需额外数据。
重启程序，重新加载配置。
无需额外数据。
网关的可操作列表，目前功能是提供网关可供下载的文件列表。
平台下发格式（可以无data）：
|
Data项 |
功能 |
必填 |
说明 |
|
dir |
目录 |
否 |
目录名，绝对路径或相对路径，默认为网关的工作路径 |
网关上报包含请求的uid以供识别。
|
Data项 |
功能 |
必填 |
说明 |
|
file_list[] |
文件名 |
是 |
文件列表 |
file_list结构：
|
数据项 |
功能 |
必填 |
说明 |
|
file_name |
文件名 |
是 |
|
|
is_dir |
是否是目录 |
是 |
1：目录 |
|
file_size |
文件长度 |
是 |
|
|
file_time |
文件时间 |
是 |
最后修改时间 YYYY-MM-DD HH:MM:SS |
|
file_checksum |
文件校验和 |
是 |
MD5-16字节，HEX字符串 |
下载网关的文件。
平台请求格式：
|
Data项 |
功能 |
必填 |
说明 |
|
file_name |
文件名 |
是 |
文件名 |
|
dir |
目录路径 |
|
相对或绝对 |
|
private_data |
回送字段 |
|
在应答中原样回送，实际上是对应的本地路径 |
网关应答：
|
Data项 |
功能 |
必填 |
说明 |
|
file_name |
文件名 |
是 |
|
|
file_size |
文件长度 |
是 |
|
|
file_content |
文件内容 |
是 |
Base64编码 |
|
file_time |
文件修改时间 |
是 |
YYYY-MM-DD HH:MM:SS |
|
private_data |
回送字段 |
|
如果请求中存在，原样回送 |
|
content_start |
开始位置 |
|
内容开始位置，如果是完整内容，不需要发送 |
|
content_length_ |
内容长度 |
|
必须和content_start一起发送 |
上传文件。可能需要额外的认证。
|
Data项 |
功能 |
必填 |
说明 |
|
file_name |
文件名 |
是 |
|
|
dir |
目录 |
|
相对或绝对路径 |
|
file_size |
文件长度 |
是 |
|
|
file_content |
文件内容 |
是 |
Base64编码 |
|
file_time |
文件修改时间 |
是 |
YYYY-MM-DD HH:MM:SS |
|
content_start |
开始位置 |
|
内容开始位置，如果是完整内容，不需要发送 |
|
content_length_ |
内容长度 |
|
必须和content_start一起发送 |
|
file_checksum |
文件校验和 |
|
MD5-16字节，HEX字符串 随最后一个分段发送 |
网关使用通用应答回复。最后一个应答会告知是否全部处理成功。如果文件校验失败，不会真正写入文件（如果分段到达顺序混乱则会失败）。
执行控制台命令。
显示内部数据。
启用压缩（小数据包压缩后更长，所以依据实际效果选择），压缩的数据包第一个字符为’Z’，其后为base64编码的数据，数据通过zlib压缩：
|
数据项 |
|
|
|
Z（大写） |
|
前导符，非压缩数据包总是以大括号开始 |
|
Base64数据 |
|
通过base64编码的下列数据 |
|
|
解压缩后长度 |
8字节，网关的字节序 |
|
|
压缩数据 |
使用zlib压缩的数据块（不是zip文件） |
下发此指令不需要其它数据。
启用加密，所有数据都会加密传输（如果已经压缩则加密的数据为压缩之后的数据）。加密算法为AES256-CBC。默认控制类指令已经是加密的。
|
数据项 |
|
|
|
E（大写） |
|
前导符 |
|
Base64数据 |
|
通过base64编码的下列数据 |
|
|
明文长度 |
8字节，网关的字节序 |
|
|
填充字节 |
8字节 |
|
|
初始IV |
16字节 |
|
|
加密数据 |
16字节的倍数，最后一个块不足部分用0填充 |
下发此指令不需要其它数据。
下发新密钥。网关已实现，由于配套设施尚未完成，暂不公开。
按照平台接口。
补充的数据：
|
Data数组项 |
含义 |
必填 |
说明 |
|
type |
上报类型 |
是 |
1为全采，包含所有可读通道，0为其它 |
|
events |
触发事件 |
|
事件被触发的通道代码，空格分隔： 关联上报的依赖的通道 变化全部上传的通道 注意，全采时不判断是否变化，不会有触发事件 |
|
ms |
耗时 |
|
本次处理所用的时间，单位为毫秒 |
|
count |
个数 |
是 |
上报数据的个数 |
无需额外数据。网关立即发起一次全部采集。
平台下发已经收到的数据序列号，网关收到后即可丢弃此序列号以及之前的所有数据。
|
Data项 |
功能 |
必填 |
说明 |
|
data_sequence |
数据序列 |
|
平台已经收到的最大数据序列 |
网管使用通用应答回复处理状态。
平台下发缺失的数据序列，网关重新发送。如果指定的数据序列不存在，网关将重新注册。如果数据存在，网关重新push。
数据包格式：
|
Data项 |
功能 |
必填 |
说明 |
|
data_sequence |
数据序列 |
|
逗号分隔，短横线表示范围 范例：“2,6-10” |
平台请求，网关返回执行结果。
Data是一个数组，每个元素的属性如下：
|
Data项 |
功能 |
必填 |
说明 |
|
deviceCode |
设备标识 |
是 |
|
|
paramCode |
点位标识 |
二选一 |
|
|
channelNo |
通道编号 |
|
|
|
value |
要写入的值 |
是 |
|
仅可用于隧道协议。
|
Data项 |
功能 |
必填 |
说明 |
|
deviceCode |
设备标识 |
是 |
|
|
dataValue |
要写入的指令 |
是 |
编码必须和设备属性一致（hex或ascii） |
用于隧道协议报告连接状态。
用于隧道协议。连接失败后网关自动重连存在时间间隔，可以发送reload指令重启程序（相当于快速重连）。
考虑到流量问题，此消息不再发送。
用于隧道协议。连接成功后如果设备异常断开，网关可能无法知晓设备断开而无法自动重连，此时需要重启网关（发送reload重启程序即可）。
Retain消息会被忽略（MQTT服务器仅在真正的遗嘱消息上标记retain，所以不影响正常发送的消息）。
系统还原、文件传输、后台指令、修改密码必须加密（即必须知晓网关密钥）。
透传支持：
设备配置增加encodeType，取值为hex或string
点位配置用于配置采集指令，增加paramCommand
配置示例：
{
"protocolCode": "TCP_TUNNEL",
"protocolName": "TCP隧道协议",
"resolvePropertyMap": {
"ip": "192.168.136.1",
"port": "503",
"rate": "30000" ----------采集间隔，每条指令间隔为1秒（后续可用参数调整），多条指令之间会用一秒钟来接收数据
},
"confTabs": [
{
"deviceCode": "deviceTcpTunnel",
"encodeType": "hex",
"resolveParamConfigVOList": [
{
"paramCode": "read",----------任意
"paramName": "从0开始读取10个保持寄存器",---------任意
"paramCommand": "00 06 00 00 00 06 01 03 00 00 00 0A"----------指令
}
]
}
]
}
上报数据：
（此上报数据与上面的指令无关联！）
{
"func": "push",
"ts": 1710150390230,
"uid": "270e27cb353752fd4bedc4f1f32d634f",
"identify": 175,
"data": [
{
"deviceCode": "tunnel",
"dataValues": [
{
"paramCode": "tunnel",
"paramName": "tunnel",
"ts": 1710150390230,
"val": "000600000017010314000A109AFFFE0000CDCC0C400000000000000000"-----------只有这个有意义，其余均无意义，编码与指令相同（同为hex或字符串）
}
]
}
]
}
（完）