自有网关对接规范
用户有自己的网关想对接平台,网关和子设备之间的协议可以沿用原始的协议,网关与平台的协议规范要按照《自有网关对接规范》修改。
网关设备登陆
网关设备通过标准MQTT协议和平台连接交互,登陆采用MQTT的connect报文,其中设备clientId是在平台创建网关设备时生成的,用户名填写任意非空字符串,密码是平台创建网关设备时生成的特征串。网关登陆方式可以参考平台MQTT协议接入。网关本身的上报数据和接受指令下发和平台MQTT协议非透传一致,参考MQTT协议非透传的数据上下行。
网关子设备上下行协议
所有接入网关的子设备,子设备的登陆登出,数据上行和指令下行,都通过网关进行转发。子设备登陆登出和上行数据,通过网关上传给平台;下行指令,平台通过网关转发给子设备。Payload中的设备id都是子设备的id。所有与子设备相关的报文,qos都是1。
1.子设备登陆报文
子设备登陆认证通过网关转发到平台认证。如果设备在网关侧有自己的认证方式,网关可以从平台下发的设备信息中取出设备对应的token(即为特征串)填到报文的password中,这样平台的认证一定会通过,相当于没有在平台认证,网关必须自己保证设备认证正确性,这种模式下,此报文是通知天翼物联网平台(AIoT)子设备上线。
子设备上报时可以带上设备编号(deviceSn),由网关把产品id拼接在设备编号前面组成设备id(deviceId);或者有设备上报的信息中,身份标识和设备编号有对应的映射关系,只需要最终的报文中的deviceId是平台上生成的设备id即可。
Topic:v1/up/login
Payload:{"deviceId":"1000011111","productId":10000,"password":"abcd"}
说明:deviceId为子设备id,productId为子设备产品id,password为子设备特征串。设备和边缘计算模块连接时,需要自己实现心跳
2.子设备登陆平台响应结果报文
此报文是平台返回子设备的登陆认证结果。
如果设备在网关侧有自己的认证方式,网关可以从平台下发的设备信息中取出设备对应的token(即为特征串)填到报文的password中,这样平台的认证一定会通过,相当于没有在平台认证。这种模式下,此报文只是流程上的需要,网关可以忽略。
Topic:v1/dn/login
Payload:{"deviceId":"100001111","productId":10000,"resultCode":0,"msg":""}
说明:deviceId为子设备id(无法解析时为空字符串),productId为子设备产品id(无法解析时为-1),msg为返回消息。
resultCode为返回结果码,具体如下:
结果码 | 含义 |
0 | 成功 |
10000 | 未知错误 |
10001 | 非json格式 |
10002 | 后端服务请求失败 |
10003 | 传入参数缺失 |
10004 | 参数类型错误 |
12001 | 设备不存在 |
12002 | 设备协议类型或者状态校验失败 |
12003 | 子设备不属于该网关设备 |
12004 | 认证失败 |
12005 | 产品ID不匹配 |
3.子设备上报数据报文
此报文是子设备上报数据的报文格式。网关收到子设备上报数据的报文,需要按照下面的格式和主题发送到天翼物联网平台(AIoT)。
Topic:v1/up/ad
Payload:
{"deviceId":"100001111","serviceIdentifier":"service1","payload":{"field1":"value1"}}
说明:deviceId为子设备id,messageId为上报数据的消息id(在同一子设备id范围内,所有messageId不可重复),serviceIdentifier为数据上报服务标识,payload的值也是json,放的是设备上报数据解析出来的字段和值。
4.子设备错误信息报文
当子设备上报数据或者子设备发送指令下发响应在平台解析发生错误,或者子设备未在线就发送数据等问题,通过此报文从平台把错误信息发送给网关。
Topic:v1/dn/error
Payload:{"deviceId":"100001111","productId":10000,"messageId":"12345","resultCode":0,"msg":""}
说明:deviceId为子设备id(无法解析时为空字符串),productId为对应的产品id(无法解析时为-1),messageId为子设备上报数据时对应的消息id(如果无法解析出上报数据中的消息id,此字段为空字符串。如果是指令下发响应出错,此字段为taskId,值类型为数字),msg为错误具体描述消息
resultCode为错误码,具体如下:
错误码 | 含义 |
10000 | 未知错误 |
10001 | 非json格式 |
10002 | 后端服务请求失败 |
10003 | 传入参数缺失 |
10004 | 参数类型错误 |
14001 | 设备不在线 |
14002 | 物模型解析失败 |
5.平台下行命令给子设备报文
此报文是下发给子设备指令的报文格式。网关收到平台下发的如下的指令报文,需要转换成子设备需要的报文,下发给子设备。
Topic:v1/dn/cmd
Payload:
{"deviceId":"100001111","productId":10000,"serviceIdentifier":"service1","taskId":123,"payload":{"field1":"value1"}}
说明:deviceId为子设备id,productId为子设备产品id,,serviceIdentifier为指令下发服务标识,taskId为下发指令的编号。payload的值也是json,放的是要在边缘计算进行编码的字段和值。
6.子设备执行下行命令响应结果报文
此报文是子设备上报指令执行结果的报文格式。网关收到子设备上报指令执行结果的报文,需要按照下面的格式和主题发送到平台。
Topic:v1/up/cmd
Payload:
{"deviceId":"100001111","serviceIdentifier":"service1","taskId":123,"payload":{"field1":"value1"}}
说明:deviceId为子设备id,serviceIdentifier为指令下发响应服务标识,taskId为下发指令的编号。payload的值也是json,放的是设备上报数据解析出来的字段和值
7.子设备登出报文
子设备下线报文。此报文用来通知平台某个子设备下线。
Topic:v1/up/logout
Payload:{"deviceId":"100001111"}
说明:deviceId为子设备id
网关子设备信息驱动信息下发
1.子设备驱动全量信息下发报文
此报文是天翼物联网平台(AIoT)下发网关关联的子设备信息以及协议解析驱动的报文,在边缘实例界面中,点击部署时,平台下发此报文给网关。网关可以根据设备编号和产品id,拼接出设备id,为产品id+设备id。驱动不是必须的,网关可以自己实现驱动,不一定需要上传到平台。
Topic:v1/dn/allInfo
Payload:
{"taskId":123,"payload":
[
{
"productId":1,
"devices":[
{
"deviceSn":"test1",
"token":"password1"
},
{
"deviceSn":"test2",
"token":"password2"
}
],
"port":8001,
"drivenPath":"http://asdasd.jar",
"drivenName":"driven1.jar"},
{
"productId":2,
"devices":[
{
"deviceSn":"test1",
"token":"password1"
},
{
"deviceSn":"test2",
"token":"password2"
}
],
"port":8002,
"drivenPath":"http://sdfsdf.jar",
"drivenName":"driven2.jar"
}
]}
说明:taskId为驱动下发指令的编号。payload为链表,里面每一个对象为子设备信息,其中productId为子设备产品id,port为子设备接入的端口,drivenPath为驱动下载路径(可以为空),drivenName为驱动名称(可以为空),devices为子设备列表,deviceSn为子设备编号,token为子设备特征串。
2.子设备驱动信息下发响应报文
此报文是网关返回子设备信息下发或者驱动下发执行结果的报文。
Topic:v1/up/info
Payload:{"taskId":123,"resultCode":0,"msg":{}}
说明:taskId为驱动下发指令的编号,msg为返回的消息。
resultCode 0:成功,其他值:失败
附录:
0为成功,其他为失败。错误码,具体如下所示:
错误码 | 含义 |
10000 | 未知错误 |
10001 | 非json格式 |
10002 | 后端服务请求失败 |
10003 | 传入参数缺失 |
10004 | 参数类型错误 |
12001 | 设备不存在 |
12002 | 设备协议类型或者状态校验失败 |
12003 | 子设备不属于该网关设备 |
12004 | 认证失败 |
12005 | 产品ID不匹配 |
14001 | 设备不在线 |
14002 | 物模型解析失败 |