本文介紹物聯網平臺定義的安全隧道通信協議。

背景信息

通信協議傳輸數據的封裝方式如下圖所示。

封裝方式

設備端和訪問端均與安全隧道連接成功后，依賴安全隧道的通信協議進行設備的遠程訪問。設備端與訪問端之間的通信、安全隧道內部的會話（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的相關信息。