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

背景信息

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

封装方式

设备端和访问端均与安全隧道连接成功后，依赖安全隧道的通信协议进行设备的远程访问。设备端与访问端之间的通信、安全隧道内部的会话（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的相关信息。