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

配网前准备 设备配网 设备绑定(推荐) 历史设备绑定API(不推荐)

获取发现设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/awss/enrollee/list/get 1.0.2 分页查询发现设备列表 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
pageSize Integer 分页大小
pageNum Integer 页编号

返回参数

参数 子键 类型 必有 描述
totalNum ​Integer 总数
items List 对象数组
gmtCreate Date 创建时间
gmtModified Date 修改时间
identityId String 用户身份
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 Byte 配网过程状态(0:初始态

示例

  • 请求示例
    {
        "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,
                    "identityId":"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 根据过滤规则从客户端通过本地通讯发现的本地设备列表中,过滤出还未被用户绑定的设备信息 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotDevices List 本地发现的设备信息列表
列表结构
字段名 字段类型 必填 详细描述
productKey String 产品PK
deviceName String 设备名称(deviceNmae)

返回参数

参数 类型 必有 描述
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": [{
            "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/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.2 获取秘钥 是,客户端SDK需启用身份的鉴权,进行身份认证,仅WiFi和以太网需要使用

请求参数

参数 子键 类型 必填 描述
deviceInfoForCipher JSON对象
deviceName String deviceName
productKey String productKey,非蓝牙设备必传,蓝牙设备不用传
productId String productId,productKey的十六进制字符串,蓝牙设备必传,非蓝牙设备不用传
cipherType Integer 生成秘钥的类型,如果为空默认一型一密(详见附录)
random String 随机数(32字节16进制字符串)
params JSON 扩展参数(蓝牙设备需要传mac,非蓝牙设备传空map)

返回参数

名称 类型 必有 描述
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"
    }
              

秘钥生成规则

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)
      

网关接入子设备

定义描述

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 加签扩展参数

返回参数

名称 类型 必有 描述
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"
    }
              

签名算法

蓝牙设备进行身份认证,蓝牙不传pk传的是productId
验签是将productKey + deviceName + map里的参数  按照字典进行升序排序,然后组成kv串即为待加密的签名
支持hmacSha1,hmacSha256,hmacMd5 忽略大小写
sign规则 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***)
      

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
    }