提供一组与设备配网和绑定相关的服务接口，通过本组接口可以实现蓝牙、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
}