简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

配网管理

更新时间:2021-11-16 10:25:34下载pdf

随着产品配网方式丰富度的提高,云开发平台对主流配网能力进行了迭代,提供了权限管理接口来满足不同配网方式的诉求,例如 Wi-Fi 配网、蓝牙配网、蓝牙 & Wi-Fi 双模配网等方式。

API 列表

请求方式 API 设备类型 接口说明
POST /v1.0/device/paring/token 普通设备 生成配网令牌。
GET /v1.0/device/paring/tokens/{token} 普通设备 获取配网设备列表。
PUT /v1.0/devices/{device_id}/enabled-sub-discovery Zigbee 设备 开放网关允许子设备入网。
GET /v1.0/devices/{device_id}/list-sub Zigbee 设备 获取当前入网的子设备列表。
GET /v1.0/devices/{device_id}/sub-devices Zigbee 设备 获取网关下的子设备列表。

生成配网令牌

接口说明

发现设备之前,需要先申请一个临时令牌,经过涂鸦客户端 SDK 进行配网,设备接到配网令牌后可自动完成发现和账号绑定。当前支持 Wi-Fi 配网和 BLE + Wi-Fi 配网方式,更多能力持续拓展中。

说明:BLE 设备需扫描设备二维码获取设备唯一 ID 用于配网。

接口地址

POST /v1.0/device/paring/token

请求参数

参数名 类型 参数类型 必填 说明
paring_type String body 配网类型,支持 BLE、AP、EZ。
uid String body 用户唯一标识。
time_zone_id String body 用户所在时区 ID。
home_id String body 家庭 ID,不填则为用户默认家庭。
extension Object<extension> body 扩展信息,配网类型是 BLE 时需传入设备 UUID。


extension 说明

参数名 类型 参数类型
uuid String 设备唯一 ID

返回参数

参数名 类型 说明
code Integer 响应码,详见 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
expire_time Long 令牌过期时间
region String 当前可用区,当前支持:AY、EU、US
token String 配网令牌
secret String 密钥
extension Object<extention> 扩展信息

说明:使用涂鸦配网 SDK 时,您需要组装 result 参数,将 regiontokensecret 作为 authToken 用于涂鸦配网 SDK 初始化。设备收到后会自动拆解 authToken,您再使用 token 查询配网结果。

extension 说明

参数名 类型 说明
encrypt_key String 加密 key
random String 加密字符串

请求示例

POST /v1.0/device/paring/token
{ "uid": "ay155xxxxxxxx2G0fA", "time_zone_id":"Asia/Shanghai", "paring_type":"BLE", "extension":{ "uuid":"5682bceac872cfe7" } }

返回示例

{ "result": { "expire_time": 300, "extension": { "encrypt_key": "101xxxxxxx189f", "random": "fa2fxxxxxxxxcb38c" }, "region": "AY", "secret": "pr_0", "token": "H73H8u7A" }, "success": true, "t": 1591257455025 }

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法

轮询配网结果

接口说明

由于设备配网是一个异步流程,根据网络质量的不同,设备成功入网的时间不定,故需要开发者轮询该接口直至查询到设备列表或到超时停止轮询(轮询周期为 1 秒一次,超时时间建议为 100 秒)。

接口地址

GET /v1.0/device/paring/tokens/{token}

请求参数

参数名 类型 参数类型 必填 说明
token String URI 设备配网令牌

返回参数

参数名 类型 说明
code Integer 响应码,详见 错误码
success Boolean 判断请求是否成功
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值
result Object<result> 返回结果

result 说明

参数名 类型 说明
success Array 配网成功设备列表
success.device_id String 设备 ID
success.product_id String 产品 ID
success.name String 设备名称
success.category String 设备类型
failed Array 配网失败设备列表
failed.device_id String 设备 ID
failed.code String 失败错误码
failed.msg String 失败错误说明
failed.name String 设备名称

请求示例

GET /v1.0/device/paring/tokens/23sdsrsdgfd

返回示例

{ "result":{ "failed":[ ], "success":[ { "category":"td", "device_id":"6c4b088a4116ae16c****", "name":"华硕", "product_id":"sfclyxhrfnys****" } ] }, "success":true, "t":1591872112140 }

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法

开放网关允许子设备入网

接口说明

由于子设备不具备直接的联网能力,故而添加子设备需要网关加入。网关进入允许入网状态后,子设备可以加入网关的本地网络,通过网关完成入库。

接口地址

PUT /v1.0/devices/{device_id}/enabled-sub-discovery

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 设备 ID。
duration Int URL 网关发现时间。
取值范围:0~3600 秒。取值 0 秒为停止发现,默认值为 100 秒。

返回参数

参数名 类型 说明
code Integer 响应码,详见 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Boolean 返回结果 。

请求示例

PUT /v1.0/devices/23sdsrsdgfdxxxxxx/enabled-sub-discovery?duration=100

返回示例

{
    "success":true,
    "t":1551863646940,
    "result":true
}

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法

获取入网子设备列表

接口说明

子设备配网是一个异步流程,配网时会根据设备数量以及网络情况陆续将子设备加入网关。因此需要根据初次发现时间轮询此接口获取子设备列表,可结合自身业务结束发现流程,建议每次轮询 1 秒直至 100 秒结束。

接口地址

GET /v1.0/devices/{device_id}/list-sub

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 网关 ID
discovery_time Long URL 网关发现子设备时间,精确到秒

返回参数

参数名 类型 说明
code Integer 响应码,详见 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
id String 设备编号
name String 名称
owner_id String 设备拥有者 ID
active_time Long 设备激活时间
update_time Long 设备更新时间
category String 产品类别
product_id String 产品 ID
online Boolean 设备在线状态

请求示例

GET /v1.0/devices/23sdsrsdgfd******/list-sub?discovery_time=1566973348

返回示例

{ "result":[ { "active_time":1566973357, "update_time":1566973363, "owner_id":"5583425******", "product_id":"tob46aoq******", "name":"烟雾报警器", "online":true, "id":"xxxxx", "category":"ywbj" } ], "t":1566973373639, "success":true }

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法

获取网关下的子设备列表

接口说明

通过网关设备 ID,获取子设备列表。

接口地址

GET /v1.0/devices/{device_id}/sub-devices

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 设备 ID

返回参数

参数名 类型 说明
code Integer 响应码,错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
id String ID
product_id String 产品 ID
owner_id String 设备拥有者 ID
online Boolean 设备在线状态
name String 设备名称
update_time Long 设备状态更新时间
active_time Long 设备上次配网时间
category String 分类

请求示例

GET /v1.0/devices/6ca345543******6875z88d/sub-devices

Java SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN); BatchDevices batchDevices = client.gatewaySubList(devIds); System.out.println("批量获取设备详细信息: "); System.out.println(JSONObject.toJSONString(batchDevices));

返回示例

{ "success":true, "t":1565917936198, "result":[ { "active_time":1565857222, "update_time":1565857227, "owner_id":"52****57", "product_id":"Mco****jXh", "name":"mcs", "online":false, "id":"6cac4bd83****6875z88d", "category":"mcs" }, { "active_time":1565857222, "update_time":1565857227, "owner_id":"52****57", "product_id":"ez****rjm", "name":"海曼XX传感器", "online":false, "id":"6caabb588****0db3d7gbl", "category":"sj" } ] }

错误码

以下为该接口常见的业务异常,更多的异常错误,请参考 全局错误码

错误码 说明
500 系统错误
1106 权限非法