本文介绍物联网平台定义的安全隧道通信协议。

背景信息

通信协议传输数据的封装方式如下图所示。

封装方式

设备端和访问端均与安全隧道连接成功后,依赖安全隧道的通信协议进行设备的远程访问。设备端与访问端之间的通信、安全隧道内部的会话(Session)管理及Session内的数据通信,都基于通信协议中隧道帧实现。隧道帧为WebSocket中二进制类型数据帧的Payload。

您需在访问端应用程序和设备端目标应用中,自行设计和开发应用层通信协议,建立访问端与设备端的通信。

通信数据格式说明

隧道帧包括以下两部分:

  • Tunnel Header:定义安全隧道会话(Session)类型。
    字段 说明
    Header Length Tunnel Header内容的字节数组长度,最大值为2048个字节。字节数组长度必须占位2个字节,高位字节在前,低位字节在后。

    例如,Tunnel Header内容的字符串使用UTF-8编码转码成字节数组的长度为十进制的87,对应十六进制57,则高位字节为0x00,低位字节为0x57。

    Header Bytes Tunnel Header内容,即JSON格式内容对应的UTF-8编码格式的字节数组。JSON格式内容参见下表Tunnel Header的JSON数据
    表 1. Tunnel Header的JSON数据
    参数 数据类型 说明
    frame_type Integer 隧道帧类型。可取值为:
    • 1:common_response,响应数据。
    • 2:session_create,创建Session。
    • 3:session_release,关闭Session。
    • 4:data_transport,创建Session内的数据传输。
    session_id String 不同类型隧道帧的会话ID,在当前安全隧道内唯一。

    访问端发送创建Session的请求帧时,不需要传入该参数,物联网平台会根据收到的请求帧分配一个会话ID,并发送给设备端。其他类型的隧道帧,访问端和设备端均需要传递会话ID。

    frame_id Long 访问端或设备端发送通信数据时设置的帧ID,取值范围为0~(263-1)。

    建议设备端和访问端均使用递增的帧ID,用于区分每个session_id会话中的通信数据。

    service_type String Session对应的业务类型,由您自定义。支持英文字母、下划线(_)、短划线(-)和英文句号(.),首字母必须为英文字母,最长不超过16个字符。
  • Tunnel Payload:定义Session的payload,其长度不能超过4 KB。由frame_type决定数据格式。具体说明,请参见Session说明

Session说明

设备端与访问端进行Session通信的流程图如下。

会话流程
序号 流程 说明
1和2 WebSocket建连。 设备端与访问端建立安全的WebSocket通道。
3 创建Session。 由访问端发送给设备端。
注意 创建Session隧道帧成功发送到设备端后,若超过10秒设备端未返回响应结果,访问端会收到超时异常的信息。
4 创建响应数据。 由物联网平台或设备端返回给访问端的响应结果。
说明 支持创建不同类型隧道帧的响应数据。
5和6 Session内的数据传输。 设备端和访问端可使用该Session进行数据通信。
注意 物联网平台不会对Tunnel Payload数据做任何解析,直接中转至设备端或访问端。
7 关闭Session。 应用场景如下:
  • 设备端和访问端均可主动关闭Session。
  • 物联网平台升级时会关闭Session。此时,访问端需具备被动关闭会话时重连设备的能力。
  • 设备端与访问端中任意一端断连,另一端会关闭Session。

Session使用过程中,Tunnel Header中JSON数据和Tunnel Payload的配置,请参见下表。

字段 创建Session 响应数据 Session内的数据传输 关闭Session
frame_type 取值2。 取值1。 取值4。 取值3。
session_id 无需传入。

创建Session成功时,由物联网平台生成,并发送给设备。

必须传入。

必须是设备端收到的对应Session创建时,物联网平台下发的session_id

必须传入。

填充该Session创建时物联网平台生成的session_id

必须传入。

填充该Session创建时物联网平台生成的session_id

frame_id 必须传入。

根据上文参数说明自定义。

必须传入。

必须是设备端收到的对应Session创建中的frame_id

必须传入。

根据上文参数说明自定义。

必须传入。

根据上文参数说明自定义。

service_type 必须传入。

根据上文参数说明自定义。访问端指定业务类型后,设备端收到创建Session的请求时,才能根据业务类型连接到指定的设备端目标应用。

必须传入。

必须是设备端收到的对应Session创建中指定的service_type

必须传入。

对应Session创建时指定的service_type

不涉及。
payload 不涉及。 JSON格式数据,内容如下:
{
    "code": 0,
    "msg": ""
}

参数说明,请参见下表响应数据的payload参数说明

由您自定义数据内容的字节数组,其长度不能超过4 KB。 JSON格式数据,内容如下:
{
    "code": 0,
    "msg": ""
}

参数说明,请参见下表关闭Session的payload参数说明

表 2. 响应数据的payload参数说明
参数 数据类型 说明
code Integer 响应结果码,取值范围0~255,0~15为系统预留响应码,16~255可由您自定义。
  • 0:表示创建Session成功,其他表示失败。
  • 1:表示物联网平台的云端识别到单个安全隧道中Session数量已达到上限(10个),无法再创建。
  • 2:表示设备端拒绝创建该Session。
msg String 创建失败后,返回的错误提示。
表 3. 关闭Session的payload参数说明
参数 数据类型 说明
code Integer 关闭Session的原因,可取值:
  • 0:表示访问端主动关闭Session。
  • 1:表示设备端主动关闭Session。
  • 2:表示物联网平台因检测到访问端断连,关闭Session。
  • 3:表示物联网平台因检测到设备端断连,关闭Session。
  • 4:表示物联网平台因系统更新,关闭Session,设备端和访问端可以延时1秒后重新建连。
msg String 关闭Session的相关信息。