Topology Management

If your device cannot directly connect to the internet for reasons such as resource constraints and hardware configuration, a gateway can act as a proxy between the device and the cloud and route data between them. A device that connects to the cloud through a gateway is called a sub-device.

To enable a gateway to act as a proxy for a sub-device, you must establish a topological relationship between them.

Method comparison

You have three methods to establish topology and choose one of them as needed. Make sure not to mix one method with another.

Name	Scenarios	Interface	Feature
Gateway dynamically discovers sub-devices	You do not get the information about sub-devices upfront, so it is not possible to register sub-devices to Tuya’s cloud services and flash registration information to sub-devices upfront. The gateway can dynamically discover sub-devices, register sub-devices to Tuya’s cloud services, and establish a topological relationship.	Gateway binds to sub-devices	Fully automatic
Gateway establishes topology	You get the information about sub-devices and register sub-devices to Tuya’s cloud services upfront. You flash registration information to sub-devices or gateways. The gateway discovers sub-devices and invokes Tuya’s cloud API to establish a topological relationship.	Establish topological relationship	Semi-automatic
Platform manages topology	You get the information about sub-devices and register sub-devices to Tuya’s cloud services upfront. You establish a cloud-based topological relationship between the gateway and sub-devices.	Establish topological relationship	Fully manual

This topic describes the gateway-side protocol used to manage a topology.

Gateway binds to sub-devices (dynamic discovery)

The gateway dynamically discovers sub-devices and requests the cloud to register the discovered sub-device and establish a topological relationship. This is how dynamic discovery works.

Interaction diagram

Device sends messages

If a sub-device attempts to connect to the gateway, the gateway will send the cloud the information about this sub-device.

Topic: tylink/${deviceId}/device/sub/bind

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      {
        "productId":"a123b456****",
        "clientId":"123455asdf****"
      },
      {
        "productId":"a123b457****",
        "clientId":"453455asdf****"
      }
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that requests to bind to the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	array	The list of sub-device parameters	Yes	A gateway device can bind up to 100 sub-devices.
data[].productId	string	The product ID (PID) of the sub-device.	Yes	The PID associated with the sub-device.
data[].clientId	string	The unique ID of the device	Yes	The unique identifier assigned to sub-device hardware, which must be unique under a product. The MAC address or SN can be set as the client ID. You can view the client ID in Device Management > Registration ID.

Device receives messages

The gateway receives the response to the binding request from the cloud.

Topic: tylink/${deviceId}/device/sub/bind_response

{
    "msgId":"45lkj3551234****",
    "time":1626197189640,
    "version":"1.0",
    "code":0,
	"data":[
      {
        "productId":"a123b456****",
        "clientId":"123455****",
        "deviceId":"6c828cba434ff40c07****"
      },
      {
        "productId":"a123b457****",
        "clientId":"123456****",
        "deviceId":"6c828cba434ff40c07****"
      }
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that requests to bind to the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Status code	No	0: Success, which is the default value. Other values: Failure
data	array	The list of bound sub-devices	Yes	-
data[].productId	string	The PID	Yes	The PID of the sub-device.
data[].clientId	string	The unique identifier of sub-device hardware	Yes	It must be unique under a product.
data[].deviceId	string	The unique device ID assigned to each sub-device	Yes	If one clientId is bound to the same gateway device repeatedly, the same device ID is generated each time. Otherwise, a new device ID is generated.

The description of status codes

Status code	Description
0	The default status, indicating success.
1001	Service exception.
1002	The request parameter is invalid.
1004	Device does not exist.
2401	The product does not exist.
2402	The gateway has bound to multiple device groups.
2403	The information about the topology and sub-device does not exist.
2404	Failed to get the license due to no license available.
2405	Failed to get the device group of the gateway.
2406	The sub-device must be unbound before being registered again.
2410	A gateway device can bind up to 2,000 sub-devices.

Gateway deletes sub-devices

A gateway can request to delete a sub-device that is registered through dynamic discovery from the cloud. After receiving the delete request, the cloud checks and deletes the specified sub-device and the corresponding topological relationship. The delete request initiated by the gateway device can directly delete a sub-device that has been bound with a home or an asset.

Interaction diagram

Device sends messages

Topic: tylink/${deviceId}/device/sub/delete

Message content

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the gateway that requests to delete a sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	array	The list of sub-device IDs to be deleted	Yes	Up to 10 sub-devices are allowed.

Device receives messages

Topic: tylink/${deviceId}/device/sub/delete_response

Message content

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the gateway that requests to delete a topology.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Response status code	No	0 means success, the default value. Other values mean failure.
data	array	The list of sub-device IDs deleted	Yes	/

The description of status codes

Status code	Description
0	The default status, indicating success.
1001	Service exception.
1004	The device record does not exist.
2407	The list of sub-devices is empty.
2408	The number of sub-devices reaches the upper limit.

Establish topological relationship

After you register sub-devices to Tuya’s cloud services, you flash the registration information to the sub-device. The gateway dynamically discovers sub-devices and requests the cloud to register the discovered sub-device and establish a topological relationship. This is how the gateway establishes a topology.

Interaction diagram

Device sends messages

Topic: tylink/${deviceId}/device/topo/add

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      {
        "productId":"a123b456****",
        "deviceId":"123455asdf****",
        "sign":"adstewq35324ds****",
        "signMethod":"HmacSHA256",
        "timestamp":"16067836521"
      },
      {
        "productId":"a123b457****",
        "deviceId":"123456****",
        "sign":"adstewq35324ds****",
        "signMethod":"HmacSHA256",
        "timestamp":"16067836521"
      }
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that requests to establish a topology.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	array	The list of sub-device parameters	Yes	Up to 100 sub-devices are allowed.
data[].productId	string	The PID of the sub-device.	Yes	-
data[].deviceId	string	The device ID of the sub-device.	Yes	The unique device ID assigned to each sub-device when it is registered to the cloud.
data[].signMethod	string	Signature algorithm	Yes	Only the HMAC-SHA256 algorithm is supported currently.
data[].timestamp	string	Timestamp	Yes	The signature timestamp, in seconds (10-digit value) or milliseconds (13-digit value).
data[].sign	string	Signature	Yes	signMethod is used to sign the content. For example, HmacSHA256 (content, deviceSecret). content contains: productId= a123b456****|deviceId=123455asdf****|timestamp=${Signature Timestamp}. deviceSecret is the value of the DeviceSecret in the registration information on the Tuya Developer Platform.

Device receives messages

Topic: tylink/${deviceId}/device/topo/add_response

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      {
        "productId":"a123b456****",
        "deviceId":"6c828cba434ff40c07****"
      },
      {
        "productId":"a123b457****",
        "deviceId":"6c828cba434ff40c07****"
      }
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that requests to establish a topology.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Status code	No	0: Success, which is the default value. Other values: Failure
data	array	The list of established topological relationships.	Yes	-
data[].productId	string	The PID of the sub-device.	Yes	-
data[].deviceId	string	The device ID of the sub-device.	Yes	-

The description of status codes

Status code	Description
0	The default status, indicating success.
1001	Service exception.
1004	The device record does not exist.
2407	The list of sub-devices is empty.
2408	The number of sub-devices reaches the upper limit.
2409	Signature verification failed.
2410	A gateway device can bind up to 2,000 sub-devices.

Delete topological relationship

The gateway requests the cloud to delete its topological relationship with a specified sub-device. The cloud returns the result of the request. This request does not delete the sub-device. The sub-device still can establish a topological relationship with this gateway or other gateways.

Interaction diagram

Device sends messages

Topic: tylink/${deviceId}/device/topo/delete

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that requests to delete a topology.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	array	The list of sub-device IDs to be deleted	Yes	Up to 100 sub-devices are allowed.

Device receives messages

Topic: tylink/${deviceId}/device/topo/delete_response

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that requests to delete a topology.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Status code	No	0: Success, which is the default value. Other values: Failure
data	array	The list of sub-device IDs deleted	Yes	-

The description of status codes

Status code	Description
0	The default status, indicating success.
1001	Service exception.
1004	The device record does not exist.
2407	The list of sub-devices is empty.
2408	The number of sub-devices reaches the upper limit.

Query topological relationship

The gateway requests the cloud to query the topological relationship. The cloud returns the result of the request.

Interaction diagram

Device sends messages

Topic: tylink/${deviceId}/device/topo/get

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":{
      "startId": 0,
      "pageSize": 20,
      "devIds":[
        "devId123455as****",
        "devId123456ty****"
      ]
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that queries the topological relationship.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Status code	No	0: Success, which is the default value. Other values: Failure
data.startIndexId	number	The starting value of the sub-device list to be queried	No	It defaults to 0, meaning that the query is started from the first entry. To query the second page, the starting value should be the index ID of the last entry on the first page returned, and so on.
data.pageSize	number	The number of devices per query	No	The default and maximum number of devices are 100.
data.devIds	array	The list of sub-device IDs in this query	No	Up to 100 sub-devices are allowed.

Device receives messages

Topic: tylink/${deviceId}/device/topo/get_response

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      {
        "productId":"a123b456****",
        "deviceId":"6c828cba434ff40c074***",
        "indexId": 1
      },
      {
        "productId":"a123b457****",
        "deviceId":"6c828cba434ff40c074***",
        "indexId": 2
      }
    ]
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that queries topology relationships.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Status code	No	0: Success, which is the default value. Other values: Failure
data	array	The list of sub-devices	Yes	-
data[].productId	string	The PID of the sub-device.	Yes	-
data[].deviceId	string	The device ID of the sub-device.	Yes	-
data[].indexId	number	Index ID	Yes	The index ID of the last entry on each page acts as the startIndexId of the query for the next page.

The description of status codes

Status code	Description
0	The default status, indicating success.
1001	Service exception.
1004	Device does not exist.
2408	The number of sub-devices reaches the upper limit.

Receive notifications of topology changes

When there are changes in topological relationships in the cloud, such as new sub-devices added to or existing devices deleted from the topology, the gateway will be notified of such topology updates.

Interaction diagram

Device receives messages

topic: tylink/${deviceId}/device/topo/change

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
	"data":{
      "addDevIds":[
           "devId123asdf****",
           "devId456tyiy****"
        ],
       "delDevIds":[
           "devId789****",
           "devIdyiy****"
        ]
    }
}

Description

Parameters	Type	Description	Required	Notes
${deviceId}	string	The device ID.	Yes	The ID of the gateway that has a change in topology relationships.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	The unique ID of a message, up to 32 characters in length.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	Business data	Yes	-
data.addDevIds	array	The list of sub-device IDs added	No	Up to 100 sub-devices are allowed.
data.delDevIds	array	The list of sub-device IDs deleted	No	Up to 100 sub-devices are allowed.