Topology Management

Last Updated on : 2022-12-02 11:10:09

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.

Assume that a gateway has established a topological relationship with a sub-device through dynamic discovery. If this gateway establishes the relationship with the same sub-device again using another method, this is the case of mixing methods and can pose issues in actual use.

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

Topology Management

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.

The delete operation deletes a sub-device physically, with its license recycled.

Interaction diagram

Topology Management

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

Topology Management

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 IoT Development 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

Topology Management

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

Topology Management

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

Topology Management

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.