Pair Device Management

With the increase in the richness of product distribution methods, Tuya currently supports: Wi-Fi distribution network, Bluetooth distribution network, Bluetooth + Wi-Fi dual-mode distribution network, etc. Tuya open platform has iterated on the current distribution network capabilities, Introduced the permission interface capability to meet the demands of different distribution methods,

Developers who have access to the original Wi-Fi single product distribution network can still use the original distribution network. Tuya will continue to maintain it. For new product access, it is recommended to use the distribution network interface recommended in this article for distribution network business development.

The original Wi-Fi distribution network interface document temporarily moves https://docs.tuya.com/en/clouddevhistory/cloud-developing-platform/pair-device-management?id=K9pos1j47x5ac.

pairing device

Generate a paring token

Interface Description

Before discovering the device, you need to apply for a temporary token and distribute it through the tuya App SDK. After the device receives the token, it can automatically complete the discovery and account binding.

The BLE device needs to scan the two-dimensional code of the device to obtain the unique ID of the device for network distribution.

Interface Address

POST /v1.0/device/paring/token

Request Parameter

extension Description

Return Data

result Description

Notes:It should be noted that, using the tuya mini sdk, you need to assemble the result parameter: region+token+secret as the assembleToken for initialization!

After the device is received, the assembleToken is automatically disassembled, and the third-party cloud uses the token to query the paring result.

extension Description

Request Example

POST /v1.0/device/paring/token

{
    "uid": "ay155xxxxxxxx2G0fA",
    "time_zone_id":"Asia/Shanghai",
    "paring_type":"BLE",
    "extension":{
    	"uuid":"5682bceac872cfe7"
    }
}

Return Example

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

Erroe Code

The following are the common business exceptions of this interface. For more exception errors, please refer to the global erroe code。

Get a list of paring devices

Interface Description Because the device paring is an asynchronous process, depending on the network quality, the time for the device to successfully access the network is uncertain. Therefore,developer needs to poll the interface until the device list is queried or the polling time is stopped (The polling period is 1s once. The timeout is recommended to be 100s).

Interface Address

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

Request Parameter

Return Data

result Description

Request Example

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

Return Example

{
    "result":{
        "failed":[

        ],
        "success":[
            {
                "category":"td",
                "device_id":"6c4b0116ae16cXXXX",
                "name":"Smart Plug",
                "product_id":"sfclfnysXXXX"
            }
        ]
    },
    "success":true,
    "t":1591872112140
}

Erroe Code

The following are the common business exceptions of this interface. For more exception errors, please refer to the global erroe code。

Zigbee device

Open gateway allows sub-devices to access the network

Interface Description

Beacuse the sub-device does not have the direct lan networking capability, the sub-device needs to be added by the gateway.

After the gateway enters the allowed network access state, the sub-device can join the local network of the gateway and complete the storage through the gateway.

Interface Address

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

Request Parameter

Return Data

Request Example

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

SDK Example

Pending support

Return Example

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

Erroe Code

The following are the common business exceptions of this interface. For more exception errors, please refer to the global erroe code。

Get the list of sub-devices currently connected to the network

Interface Description Because the sub-device paring is an asynchronous process, the sub-devices will join the gateway according to the number of sub-devices and the network. Therefore, it is necessary to poll the interface to obtain the sub-device list according to the initial discovery time. Poll every 1s until the end of 100s.

Interface Address

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

Request Parameter

Return Data

result Description

Request Example

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

SDK Example

Pending support

Return Example

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

Erroe Code

The following are the common business exceptions of this interface. For more exception errors, please refer to the global erroe code。

Get the list of sub devices under the gateway

Function Description

According to device id, get the list of sub devices under the gateway

Interface address

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

Request paramter

Return message

result Description

Request example

GET /v1.0/devices/6ca345543XXXXXX6875z88d/sub-devices

SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
BatchDevices batchDevices = client.getDeviceListInfo(devIds);
System.out.println("batch devices: ");
System.out.println(JSONObject.toJSONString(batchDevices));

Response example

{
    "success":true,
    "t":1565917936198,
    "result":[
        {
            "active_time":1565857222,
            "update_time":1565857227,
            "owner_id":"52XXX57",
            "product_id":"McoXXjXh",
            "name":"mcs",
            "online":false,
            "id":"6cac4bd83XXXXXX6875z88d",
            "category":"mcs"
        },
        {
            "active_time":1565857222,
            "update_time":1565857227,
            "owner_id":"52XXX57",
            "product_id":"ezXXXrjm",
            "name":"􏰸􏺠XX􏳸􏶀􏵋",
            "online":false,
            "id":"6caabb588XXXX0db3d7gbl",
            "category":"sj"
        }
    ]
}

ErrorCode

The following are common service exceptions on the interface. For more exception errors, see Global Error Codes.