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

配网前准备 设备配网 设备绑定（推荐） 历史设备绑定API（不推荐）

获取发现设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/enrollee/list/get 1.0.2 分页查询发现设备列表 是，客户端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.2 根据过滤规则从客户端通过本地通讯发现的本地设备列表中，过滤出还未被用户绑定的设备信息
说明 当使用正式环境的AppKey时无法列出正在开发中的产品，需使用测试环境的AppKey进行请求才能获取到开发中的产品。
是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotDevices JSON List 是 本地发现的设备信息列表

iotDevices的列表结构如下

字段名 字段类型 必填 详细描述
productKey String 是 产品PK
deviceName String 是 设备名称

返回参数

参数 类型 描述
productKey String 产品PK（与入参一致）
deviceName String 设备名称（与入参一致）
productName String 产品名称
netType Integer 入网类型
  • 0：LORA
  • 3：WIFI
  • 4：ZIGBEE
  • 5：BT
  • 6：CELLULAR
  • 7：ETHERNET
  • 8：NET_OTHER
nodeType Integer 节点类型 ，0-DEVICE；1-GATEWAY
categoryKey String 品类标识符
categoryName String 品类名称
categoryId Long 归属品类id

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params":{
        "iotDevices": [{
            "productKey": "a1v12d34vm"，
            "deviceName": "xxxxxx"
        },
        {
            "productKey": "a1v12d77bb"，
            "deviceName": "xxxxxx"
        }]
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data":[{
                "productKey":"a1v12d34vm",
                "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.3 根据token校验并绑定设备 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
productKey String 是 待配网设备productKey
deviceName String 是 待配网设备deviceName
token String 是 设备上报的token

返回参数

参数 类型 描述
data String 已配网设备iotId

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.3",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx",
        "deviceName": "xxx",
        "token":"xxx"
    }
}
  • 正常返回示例 
    {
    "id":"xxx",
    "code":200,
    "message":"success",
    "data":"xxxxxxxxxxxxx"
}

基于时间窗口的方式绑定设备

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/time/window/user/bind 1.0.3 根据时间窗口（600秒）校验并绑定设备 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
productKey String 是 待配网设备productKey
deviceName String 是 待配网设备deviceName

返回参数

参数 类型 描述
data String 已配网设备iotId

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.3",
        "iotToken": "token"
    },
    "params": {
        "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 是 接入时间窗口，单位：秒

返回参数

无业务返回参数

示例

  • 请求示例 
    {
    "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.2 用于wifi设备的绑定操作 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
productKey String 是 设备所属产品productKey
deviceName String 是 设备deviceName
token String 是 设备上报的token

返回参数

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

示例

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

蓝牙设备绑定

定义描述

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

请求参数

参数 类型 必填 描述
deviceName String 是 设备deviceName
productId String 是 productId为16进制字符串
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***)

返回参数

名称 类型 描述
iotId String 蓝牙设备的iotId

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "deviceInfoForCipher": {
            "deviceName": "xxxx",
            "productId": "001e7",
            "sign": "xxxxxxx",
            "signMethod": "hmacSha1",
            "signParams": {
                "mac":"xxx"
            }
        }
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

GPRS设备绑定

定义描述

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

请求参数

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

返回参数

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

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx"，
        "deviceName": "xxx"
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

子设备绑定

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/subdevice/bind 1.0.2 接入网关的子设备绑定 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

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

返回参数

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

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "productKey": "xxx"，
        "deviceName": "xxx"
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

解绑子设备

定义描述

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
}