English
English
简体中文
Contact Us
Register
Log In
layoutIndex

Network Pairing Management

Last Updated on : 2021-11-16 10:25:34download

With the increase of network pairing methods, the Cloud Development Platform has updated the permission management APIs to provide more network pairing methods, such as Wi-Fi pairing, Bluetooth pairing, and Bluetooth + Wi-Fi dual-module pairing.

API list

Request method API Device type API description
POST /v1.0/device/paring/token Common devices Generate a network pairing token.
GET /v1.0/device/paring/tokens/{token} Common devices Get the list of devices to be paired.
PUT /v1.0/devices/{device_id}/enabled-sub-discovery Zigbee devices Open the gateway to allow the access of sub-devices.
GET /v1.0/devices/{device_id}/list-sub Zigbee devices Get the list of paired devices.
GET /v1.0/devices/{device_id}/sub-devices Zigbee devices Get the list of sub-devices under the gateway.

Generate a network pairing token

API description

Before the device is discovered, you need to apply for a temporary token, and perform pairing through the Tuya client SDK. After receiving the token, the device can automatically complete the discovery and account binding. It currently supports Wi-Fi paring and BLE + Wi-Fi pairing.

Note: You need to scan the device QR code to get the unique ID for the network pairing of BLE devices.

API address

POST /v1.0/device/paring/token

Request parameter

Parameter name Data type Parameter type Required Description
paring_type String body Yes Pairing types, including BLE, AP, and EZ.
uid String body Yes The unique user identifier.
time_zone_id String body Yes The ID of the user’s time zone.
home_id String body No Family ID. If left blank, it refers to the user’s default family.
extension Object<extension> body No Extension information. When the pairing type is BLE, the device UUID must be passed in.

Description of extension

Parameter name Data type Parameter type
uuid String The unique device ID.

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Data type Description
expire_time Long The expiration time of the token
region String The current availability zones, including AY, EU, and US
token String Pairing token
secret String Key
extension Object<extention> Extension information

Note: To use the Tuya pairing SDK, you need to assemble the parameter result and set region, token, and secret as an authToken to initialize the SDK. The device will disassemble the authToken once received, and after that, you can use a token to query the pairing result.

Description of extension

Parameter name Data type Description
encrypt_key String Encryption key
random String Encrypted string

Request example

POST /v1.0/device/paring/token
{ "uid": "ay155********2G0fA", "time_zone_id":"Asia/Shanghai", "paring_type":"BLE", "extension":{ "uuid":"5682bceac872****" } }

Return example

{ "result": { "expire_time": 300, "extension": { "encrypt_key": "101********189f", "random": "fa2f********cb38c" }, "region": "AY", "secret": "pr_0", "token": "H73H8u7A" }, "success": true, "t": 1591257455025 }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
1106 Illegal permission

Poll the pairing result

API description

Device pairing is an asynchronous process, and the network quality is inconsistent. As a result, the devices access the network at different time points. Therefore, the developer needs to poll the interface until the device list is queried or the timeout period is reached. The polling cycle is once per second, and the timeout period is recommended to be 100 seconds.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
token String URI Yes Device pairing token

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
true: succeed
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> Return result

Description of result

Parameter name Data type Description
success Array The list of paired devices
success.device_id String Device ID
success.product_id String Product ID
success.name String Device name
success.category String Device type
failed Array The list of devices failed in pairing
failed.device_id String Device ID
failed.code String Error code
failed.msg String Description
failed.name String Device name

Request example

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

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
1106 Illegal permission

Open the gateway to allow the access of sub-devices

API description

Sub-devices require a gateway to connect to the network due to its incapability of networking. When the gateway is available for network access, you can add sub-devices to the local network of the gateway to get received.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Device ID.
duration Int URL No Gateway discovery time.
Value range: 0–3600 s. When it is set to 0, the gateway stops discovering devices. The default value is 100 seconds.

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Boolean The returned result.

Request example

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

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
1106 Illegal permission

Get the list of reported sub-devices

API description

Sub-device network pairing is an asynchronous process. During the process, sub-devices will join the gateway according to the number of devices and the network status. Therefore, you need to poll the API on the first discovery time to get the sub-device list. We recommend that you poll once a second until 100 seconds.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Gateway ID
discovery_time Long URL Yes Gateway discovery time of sub-devices, which is accurate to seconds.

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Data type Description
id String Device number
name String Device name
owner_id String Device owner ID
active_time Long Device activation time
update_time Long Device update time
category String Product category
product_id String Product ID
online Boolean Online status of the device

Request example

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

Return example

{ "result":[ { "active_time":1566973357, "update_time":1566973363, "owner_id":"5583425******", "product_id":"tob46aoq******", "name":"moke detector", "online":true, "id":"xxxxx", "category":"ywbj" } ], "t":1566973373639, "success":true }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
1106 Illegal permission

Get the list of sub-devices under the gateway

API description

Get the list of sub-devices through the device IDs under the gateway.

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
device_id String URI Yes Device ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
true: succeeded
false: failed
msg String The message returned if the request fails. It will return null if the request succeeds.
result Object<result> The returned result.

Description of result

Parameter name Data type Description
id String ID
product_id String Product ID
owner_id String Device owner ID
online Boolean Online status of the device
name String Device name
update_time Long The update time of device status
active_time Long The last pairing time of the device
category String Category

Request example

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

Java SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN); BatchDevices batchDevices = client.gatewaySubList(devIds); System.out.println("Get device details in batches: "); System.out.println(JSONObject.toJSONString(batchDevices));

Return example

{ "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":"Example sensor", "online":false, "id":"6caabb588****0db3d7gbl", "category":"sj" } ] }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code Description
500 System error
1106 Illegal permission