提供一组与设备配网和绑定相关的服务接口,通过本组接口可以实现蓝牙、GPRS、Wi-Fi设备的用户绑定流程,本组接口还包含了子设备入网流程所需的相关操作接口。

说明 配网服务已升级,新增了家、空间、群组控制等功能。若您无需使用这些功能,请查看历史版本配网服务

配网前准备

设备配网

设备绑定(推荐)

历史设备绑定API(不推荐)

获取发现设备列表

定义描述

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
    }                   

Wi-Fi设备绑定

一个设备最多被100个用户绑定,一个用户最多能绑定1000个设备。

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/enrollee/user/bind 1.0.7 用于Wi-Fi设备的绑定操作 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
productKey String 设备所属产品productKey
deviceName String 设备deviceName
token String 设备上报的token

返回参数

名称 类型 描述
iotId String 已绑定设备iotId

示例

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

蓝牙设备绑定

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/ble/user/bind 1.0.7 用于蓝牙设备的绑定操作 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
deviceName String 设备deviceName
productKey String 待配网设备的productKey
sign String 签名,详细见下方说明
signMethod String signMethod可支持:hmacSha1、hmacSha256、hmacMd5、sha256
signParams JSON 加签扩展参数
说明 蓝牙设备进行身份认证时,蓝牙传的不是productkey而是productId。验签是将“productKey + deviceName + map”里的参数,按照字典进行升序排序,再组成kv串即为待加密的签名

签名方法支持(忽略大小写)hmacSha1、hmacSha256、hmacMd5,签名规则如下:

  • hmac_md5(deviceSecret, clientId***deviceName***productKey***timestamp***)
  • hmac_sha1(deviceSecret, clientId***deviceName***productKey***timestamp***)
  • hmac_sha256(deviceSecret, clientId***deviceName***productKey***timestamp***)
  • sha256(clientId***deviceName***deviceSecret***productKey***timestamp***)

返回参数

名称 类型 描述
data String 已配网设备的iotId

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.7"
        },
        "params":{
            "homeId":"50f5op1xxxxf2f28104512",
            "productKey":"xxx",
            "deviceName":"xxx",
            "sign":"xxxxxxx",
            "signMethod":"hmacSha1",
            "signParams":{
                "mac":"xxx"
            }
        }
    }
  • 正常返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"CKuX18xxxx000100"
    }

GPRS设备绑定

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/gprs/user/bind 1.0.7 用于gprs设备的绑定操作 是,客户端SDK需启用身份
对于GPRS设备的绑定需要在设备上线的10分钟内进行,否则将会绑定失败。

请求参数

参数 类型 必填 描述
homeId String 家的id,家的唯一标识
productKey String 设备所属产品productKey
deviceName String 设备deviceName

返回参数

名称 类型 描述
iotId String 已绑定设备iotId

示例

  • 请求示例
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.7"
        },
        "params":{
            "homeId":"50f5op15xxxxf2f28104512",
            "productKey":"xxx",
            "deviceName":"xxx"
        }
    }
  • 正常返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"CKuX1xxxx7Q000100"
    }

子设备绑定

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/subdevice/bind 1.0.7 接入网关的子设备绑定 是,客户端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.7"
        },
        "params":{
            "homeId":"50f5op1xxxxf2f28104512",
            "productKey":"xxx",
            "deviceName":"xxx"
        }
    }
  • 正常返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"CKuX1xxxxQ000100"
    }

解绑子设备

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/subdevice/unbind 1.0.2 解绑当前用户和指定子设备。如果当前用户是子设备的管理员,则同时自动解除当前子设备和网关的网络拓扑关系 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
productKey String 子设备所属产品productKey
deviceName String 子设备deviceName

返回参数

无业务返回参数

示例

  • 请求示例
    {
        "request": {
            "iotToken": "109049c80bcde4c06b15f6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 1508212818676,
        "params": {
            "productKey": "xxx",
            "deviceName": "xxx"
        },
        "version": "1.0"
    }
  • 正常返回示例
    {
        "id":"xxx",
        "code":200,
        "message":"success",
        "data":null
    }