配网服务

更新时间:2018-10-19 11:29: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"
}

错误码

错误码 错误信息 来源 描述
28560 device not exist 业务 设备不存在
28563 ble device bind sign error 业务 蓝牙设备验签不通过

附录一.签名算法

蓝牙设备进行身份认证,蓝牙不传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:初始态,
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,
                "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"
}

错误码

错误码 错误信息 来源 描述
28551 user no register or router 业务 用户没有绑定已配网设备或路由器

本地发现设备列表信息过滤

定义描述

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

错误码

错误码 错误信息 来源 描述
28560 device not exist 业务 设备不存在
28566 product not exist 业务 产品不存在
28567 device must be gprs device 业务 必须是GPRS设备

获取秘钥

定义描述

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",
        "groupIds":["roomId123"]
    }
}

正常返回示例

{
    "code": 200,
    "data": "xxxx",
    "message": "success"
}

错误码

错误码 错误信息 来源 描述
6100 device not found 业务 设备不存在
6608 token not found 业务 设备上报的token信息不存在

网关接入子设备

定义描述

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

错误码

错误码 错误信息 来源 描述
28560 device not found 业务 设备不存在

解绑子设备

定义描述

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
}

错误码

错误码 错误信息 来源 描述
28560 device not found 业务 设备不存在

results matching ""

    No results matching ""