配网服务

更新时间：2019-05-22 22:24:34

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

蓝牙设备绑定

定义描述

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***)

获取发现设备列表

定义描述

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"
}

错误码

请参考错误码字典

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/cipher/get 1.0.2 获取秘钥 是，客户端SDK需启用身份的鉴权

请求参数

参数 子键 类型 必填 描述
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=5 一厂一密：根据model查询manufacturer的accessKey&accessSecret（目前model新增时需要手动录入），密钥算法sha256(contentByteArray)。
contentByteArray=accessSecret.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)

wi-fi设备绑定

定义描述

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 版本 描述 是否需要用户身份的鉴权
/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
}

错误码

请参考错误码字典

子设备绑定

定义描述

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
}

错误码

请参考错误码字典

基于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"
}

错误码

请参考错误码字典

results matching ""

    No results matching ""