JetLinks物聯網基礎平臺-官方協議

JetLinks 官方協議

除了使用自定義協議以外,jetlinks提供了默認的協議支持.
設備可以使用此協議接入平臺. 設備協議已經確定並且無法修改協議的時候,建議使用自定義協議接入

MQTT接入

目前支持MQTT3.1.1和3.1版本協議.

認證

CONNECT報文:

clientId: 設備實例ID
username: secureId+"|"+timestamp
password: md5(secureId+"|"+timestamp+"|"+secureKey)

說明: secureId以及secureKey在創建設備產品和設備實例時進行配置.
timestamp爲當前系統時間戳(毫秒),與系統時間不能相差5分鐘.

讀取設備屬性

topic: /{productId}/{deviceId}/properties/read

方向: 下行

消息格式:

{
"messageId":"消息ID",
"deviceId":"設備ID",
"properties":["sn","model"] //要讀取到屬性列表
}

回覆Topic: /{productId}/{deviceId}/properties/read/reply

回覆消息格式:

//成功
{
    "messageId":"與下行消息中的messageId相同",
    "properties":{"sn":"test","model":"test"}, //key與設備模型中定義的屬性id一致
    "deviceId":"設備ID",
    "success":true,
}
//失敗. 下同
{
    "messageId":"與下行消息中的messageId相同",
    "success":false,
    "code":"error_code",
    "message":"失敗原因"
}

修改設備屬性:

topic: /{productId}/{deviceId}/properties/write

方向: 下行

消息格式:

{
"messageId":"消息ID",
"deviceId":"設備ID",
"properties":{"color":"red"} //要設置的屬性
}

回覆Topic: /{productId}/{deviceId}/properties/wirte/reply

方向: 上行

回覆消息格式:

{
"messageId":"與下行消息中的messageId相同",
"properties":{"color":"red"}, //設置成功後的屬性,可不返回
"success":true,
}

設備屬性上報

topic: /{productId}/{deviceId}/properties/report

方向: 上行

消息格式:

{
"messageId":"隨機消息ID",
"properties":{"temp":36.8} //上報數據
}

調用設備功能

topic: /{productId}/{deviceId}/function/invoke

方向: 下行

消息格式:

{
"messageId":"消息ID",
"deviceId":"設備ID",
"function":"playVoice",//功能ID
"inputs":[{"name":"text","value":"播放聲音"}] //參數
}

回覆Topic: /{productId}/{deviceId}/function/invoke/reply

方向: 上行

消息格式:

{
"messageId":"與下行消息中的messageId相同",
"output":"success", //返回執行結果
"success":true,
}

設備事件上報

topic: /{productId}/{deviceId}/event/{eventId}

方向: 上行

消息格式:

{
"messageId":"隨機消息ID",
"data":100 //上報數據
}

子設備註冊

與子設備消息配合使用,實現設備與網關設備進行自動綁定.

topic: /{productId}/{deviceId}/child/{childDeviceId}/register

方向: 上行

消息格式:

{
"messageId":"隨機消息ID",
"deviceId":"子設備ID"
}

子設備註銷

與子設備消息配合使用,實現設備與網關設備進行自動解綁.

topic: /{productId}/{deviceId}/child/{childDeviceId}/unregister

方向: 上行

消息格式:

{
"messageId":"隨機消息ID",
"deviceId":"子設備ID"
}

子設備上線

與子設備消息配合使用,實現關聯到網關的子設備上線.(默認情況下,網關上線,子設備也會全部自動上線.)

topic: /{productId}/{deviceId}/child/{childDeviceId}/connected

方向: 上行

消息格式:

{
"messageId":"隨機消息ID",
"timestamp":1584331469964//時間戳
}

子設備離線

與子設備消息配合使用,實現關聯到網關的子設備離線.(默認情況下,網關離線,子設備也會全部自動離線.)

topic: /{productId}/{deviceId}/child/{childDeviceId}/disconnected

方向: 上行

消息格式:

{
"messageId":"隨機消息ID",
"timestamp":1584331469964//時間戳
}

子設備消息

topic: /{productId}/{deviceId}/child/{childDeviceId}/{topic}

方向: 上行或下行, 根據{topic}決定.

tip {topic} 以及數據格式與設備topic定義一致. 如: 獲取子設備屬性: /1/d1/child/c1/properties/read

CoAP接入

使用CoAP協議接入僅需要對數據進行加密即可.加密算法: AES/ECB/PKCS5Padding.

使用自定義Option: 2100:設備ID 來標識設備.

將請求體進行加密,密鑰爲在創建設備產品和設備實例時進行配置的(secureKey).

請求地址(URI)與MQTT Topic相同.消息體(payload)與MQTT相同(只支持上行消息).

DTLS接入

使用CoAP DTLS 協議接入時需要先進行認證:

發送認證請求:

POST /auth
Accept: application/json
Content-Format: application/json
2100: 設備ID
2110: 簽名 md5(payload+secureKey)
payload: {"timestamp":"時間戳"}

響應結果:

2.05 (Content)
payload: {"token":"令牌"}

之後的請求中需要將返回的令牌攜帶到自定義Option:2111

例如:

POST /test/device1/event/fire_alarm
2100: 設備ID
2111: 令牌
...其他Option
payload: json數據