提供一組與設備配網和綁定相關的服務接口，通過本組接口可以實現藍牙、GPRS、Wi-Fi設備的用戶綁定流程，本組接口還包含了子設備入網流程所需的相關操作接口。

說明 配網服務已升級，新增了家、空間、群組控制等功能。若您無需使用這些功能，請查看歷史版本配網服務。

配網前準備

設備配網

設備綁定

獲取發現設備列表

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/awss/enrollee/list/get 1.0.7 分頁查詢發現設備列表 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
pageSize Integer 是 分頁大小，小于等于99
pageNum Integer 是 頁編號，從1開始

返回參數

參數 子鍵 類型 描述
totalNum Integer 總數
items JSON List 對象數組
gmtCreate Date 創建時間
gmtModified Date 修改時間
regIotId String 已配網設備iotId
regProductKey String 已配網設備productKey
regDeviceName String 已配網設備deviceName
regProductName String 已配網設備的產品名稱
enrolleeIotId String 待配網設備iotId
enrolleeProductKey String 待配網設備productKey
enrolleeDeviceName String 待配網設備deviceName
enrolleeProductName String 待配網設備的產品名稱
bssid String 路由器bssid
ssid String 熱點ssid
rssi String 熱點rssi
type Integer 發現者設備類型，0表示device；1表示router
status Integer 配網過程狀態，0表示初始態； 1表示配網中

示例

  • 請求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "pageSize": 10，
        "pageNum": 1
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": {
        "totalNum":12,
        "items":[
            {
                "gmtCreate":xxx,
                "gmtModified":xxx,
                "regIotId":"xxx",
                "regProductKey":"xxx",
                "regDeviceName":"xxx",
                "enrolleeIotId":"xxx",
                "enrolleeProductKey":"xxx",
                "enrolleeDeviceName":"xxx",
                "bssid":"xxx",
                "ssid":"xxx",
                "rssi":"xxx",
                "type":0,
                "status":1
            }
        ]
    },
    "message": "success"
}

本地發現設備列表信息過濾

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/awss/enrollee/product/filter 1.0.7 根據過濾規則從客戶端通過本地通訊發現的本地設備列表中，過濾出還未被用戶綁定的設備信息
說明 該接口默認只處理已發布的產品，如果您需要同時處理開發中的產品，調用該接口前需在SDK中設置PRODUCT_SCOPE_ALL參數：
  • Android：setProductScope
  • iOS：[[IMSIotSmart sharedInstance] configProductScope:PRODUCT_SCOPE_ALL];
 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
iotDevices JSON List 是 本地發現的設備信息列表

iotDevices的列表結構如下

字段名 字段類型 必填 詳細描述
productKey String 是 產品的Key
deviceName String 是 設備名稱

返回參數

參數 類型 描述
productKey String 產品的Key（與入參一致）
deviceName String 設備名稱（與入參一致）
productName String 產品名稱
netType Integer 入網類型
  • 0：LORA
  • 3：WIFI
  • 4：ZIGBEE
  • 5：BT
  • 6：CELLULAR
  • 7：ETHERNET
  • 8：NET_OTHER
nodeType Integer 節點類型，0表示設備；1表示網關
categoryKey String 產品所屬品類的品類標識符
categoryName String 產品所屬品類的名稱
categoryId Long 產品歸屬品類的ID

示例

  • 請求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params":{
        "iotDevices": [{
            "productKey": "a1xxxxm"，
            "deviceName": "xxxxxx"
        },
        {
            "productKey": "a1xxxxb"，
            "deviceName": "xxxxxx"
        }]
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data":[{
                "productKey":"a1xxxxm",
                "deviceName":"xxxxxx",
                "netType":3,
                "nodeType":0,
                "categoryKey":"xxx",
                "categoryName":"xxx",
                "categoryId":14
            }
    ],
    "message": "success"
}

根據token查詢設備的證書信息

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/awss/token/check 1.0.9 token校驗 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
token String 是 設備上報的token
productKey String 否 設備的productKey
deviceName String 否 設備的deviceName，該參數不為空時，productKey不能為空

返回參數

參數 類型 描述
productKey String 待配網設備productKey
deviceName String 待配網設備deviceName
iotId String 設備的iotId

示例

  • 請求示例 
    {
    "request": {
        "iotToken": "109049c80bxxxx62e29a3ba",
        "apiVer": "1.0.9"
    },
    "id": 1508212818676,
    "params": {
        "token":"xxx"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
  "code": 200,
  "data": {
      "iotId": "xxxx"
      "productKey": "xxxx",
      "deviceName": "xxxx"
    },
  "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}
  • 異常返回示例 
    {
 "code":6608,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "message":"token not found"
}

基于token方式綁定設備

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/awss/token/user/bind 1.0.8 根據token校驗并綁定設備 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
homeId String 是 家的id，家的唯一標識
productKey String 是 待配網設備productKey
deviceName String 是 待配網設備deviceName
token String 是 設備上報的token

返回參數

參數 類型 描述
data String 已配網設備iotId

示例

  • 請求示例 
    {
    "id":"xxx",
    "version":"1.0.0",
    "request":{
        "language":"zh-CN",
        "appKey":"xxx",
        "iotToken":"xxx",
        "apiVer":"1.0.8"
    },
    "params":{
        "homeId":"50f5op1556xxxxf2f28104512",
        "productKey":"xxx",
        "deviceName":"xxx",
        "token":"xxx"
    }
}
  • 正常返回示例 
    {
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":"xxxxxxxxxxxxx"
}

基于時間窗口的方式綁定設備

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/awss/time/window/user/bind 1.0.8 根據時間窗口（600秒）校驗并綁定設備，從設備上電開始計算 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
homeId String 是 家的id，家的唯一標識
productKey String 是 待配網設備productKey
deviceName String 是 待配網設備deviceName

返回參數

參數 類型 描述
data String 已配網設備iotId

示例

  • 請求示例 
    {
    "id":"xxx",
    "version":"1.0.0",
    "request":{
        "language":"zh-CN",
        "appKey":"xxx",
        "iotToken":"xxx",
        "apiVer":"1.0.8"
    },
    "params":{
        "homeId":"50f5op15xxxxca4f2f28104512",
        "productKey":"xxx",
        "deviceName":"xxx"
    }
}
  • 正常返回示例 
    {
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":"xxxxxxxxxxxxx"
}

獲取密鑰

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/awss/cipher/get 1.0.7 獲取密鑰 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 子鍵 類型 必填 描述
deviceInfoForCipher 是 JSON對象
deviceName String 是 deviceName
productKey String 是 productKey，非藍牙設備必傳，藍牙設備不用傳
productId String 是 productId為productKey的十六進制字符串，藍牙設備必傳，非藍牙設備不用傳
cipherType Integer 是 生成密鑰的類型（具體介紹參見表下方介紹），為空默認為一型一密
random String 是 隨機數（32字節16進制字符串）
params JSON 是 擴展參數（藍牙設備需要傳mac，非藍牙設備傳空map）

cipherType取值介紹如下

cipherType=3 一型一密：根據productKey查詢productSecret，密鑰算法sha256(contentByteArray)。
contentByteArray=productSecret.getByte()+0x2c+hexToByte(random) 

cipherType=4 一機一密：根據productKey和deviceName查詢deviceSecret，密鑰算法sha256(contentByteArray)。
contentByteArray=deviceSecret.getByte()+0x2c+hexToByte(random)

cipherType=6 BLE一型一密：密鑰算法sha256(contentByteArray)。
contentByteArray=productSecret.getByte()+0x2c+hexToByte(mac)+0x2c+hexToByte(random)

cipherType=7 BLE一機一密：密鑰算法sha256(contentByteArray)
contentByteArray=deviceSecret.getByte()+0x2c+hexToByte(mac)+0x2c+hexToByte(random)

一型一密和一機一密區別如下。

  • 一型一密：是指使用產品的密鑰，即productSecret作為參數來生成配網時本地通信的加密密鑰，此時僅需提供productKey即可。
  • 一機一密：是指使用設備的密鑰，即deviceSecret作為參數來生成配網時本地通信的加密密鑰，此時必須同時提供productKey和deviceName。

返回參數

名稱 類型 描述
secret Integer 用于本地配網時通信的加密密鑰

示例

  • 請求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "deviceInfoForCipher": {
            "deviceName": "xxxx",
           "productKey": "xxxx",
            "productId": "001e7",
            "cipherType": 3, 
            "random": "00000000000000000000000000000000",
            "params": {
                "mac":"xxx"
            }
        }
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

網關接入子設備

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/thing/gateway/permit 1.0.2 允許網關處理子設備接入的請求 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
iotId String 是 網關設備iotId
productKey String 是 允許接入網關的子設備產品標識符
time Integer 是
  • 0：網關一直允許添加子設備
  • 0～65535：網關允許添加子設備的時間長度，單位為秒
  • 65535：網關不允許添加子設備

返回參數

無業務返回參數

示例

  • 請求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxxxxxxxxxxx",
        "productKey": "xxxxxxxxx", 
        "time": 60                   
    }
}
  • 正常返回示例 
    {
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":null
}

解除子設備網絡拓撲

定義描述

path 版本 描述 是否需要用戶身份的鑒權
/thing/topo/remove 1.0.2 解除子設備的網絡拓撲 是，客戶端SDK需啟用身份的鑒權，進行身份認證

請求參數

參數 類型 必填 描述
iotId String 是 設備iotId
subIotid String 是 子設備iotId

返回參數

無業務返回參數

示例

  • 請求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxxxxxxxxxxx",
        "subIotId": "xxxxxxxxx"                
    }
}
  • 正常返回示例 
    {
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":null
}