Open MQTT Protocol

MQTT parameters

To establish an MQTT connection, you must specify the following parameters.

Parameter name	Parameter description
Endpoint	Specify the endpoint for the MQTT service as needed. Avoid hard-coding the endpoint. Otherwise, risks of compliance of data might occur. For example, if the endpoint is hard-coded as a China-specific one, compliance risks might occur if a device is connected to data centers deployed in the U.S. or Europe.
Variable header	The message must include a keep-alive time period that can range from 30 to 1,200 seconds. Generally, the keep-alive time is set to 60 seconds. The higher the value, the greater the tolerance for network jitter. If a connection times out, the MQTT connection is declared a failure.
mqttClientId	tuyalink_${deviceId} For example, tuyalink_6c828cba434ff40c074wF2
mqttUsername	${deviceId}|signMethod=hmacSha256,timestamp=${10-digit timestamp},secureMode=1,accessType=1 For example, 6c828cba434ff40c074wF2|signMethod=hmacSha256,timestamp=1607837283,securemode=1,accessType=1
mqttPassword	hmacSha256(content, deviceSecret) The plaintext of content is a string concatenated with deviceId, timestamp, secureMode, and accessType in sequence. For example, content is made of deviceId=6c828cba434ff40c074wF2, timestamp=1607635284, secureMode=1, accessType=1 The password is a 64-bit hexadecimal value. Pad the left-most bits with zero if necessary.
accessType	The protocol type. 1: open protocol.
secureMode	The security mode. 1: one-key-per-device authentication mechanism.
timestamp	The timestamp, in seconds (10-digit value) or milliseconds (13-digit value).
signMethod	The signature algorithm. Valid values: HMACSHA1 and HMACSHA256.

Sample:

    ret = tuya_mqtt_init(client, &(const tuya_mqtt_config_t) {
        .host = "m1.tuyacn.com",
        .port = 8883,
        .cacert = tuya_cacert_pem,
        .cacert_len = sizeof(tuya_cacert_pem),
        .device_id = deviceId,
        .device_secret = deviceSecret,
        .keepalive = 60,
        .timeout_ms = 2000,
        .on_connected = on_connected,
        .on_disconnect = on_disconnect,
        .on_messages = on_messages
    });

MQTT topic format

Format:

tylink/${deviceId}/${domain}/${service}[/${extend}]/${action}[/?${query}]

Sample:

• Device reports properties to the cloud

  

• Device clears the desired property value from the cloud

  

MQTT payload format

The message payload is structured in JSON format by default. You can change it to other formats such as MessagePack by configuring the format parameter in a topic.
Typically, the cloud does not use a data format other than JSON because it does not know if the target device supports it. In principle, the cloud must respond in the same format as received from the device. For example, if a device reports data in MessagePack format, the cloud must respond in MessagePack.

Payload structure

{
    "version":"1.0",  			 // Optional. The protocol version, defaulting to 1.0, which is the only valid value currently.
  	"msgId":"j4sdfl39Twe3494",      // Required. The message ID, a string up to 32 bits in length.
    "time":1234567890123,  		// Required. The timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
    "sys":{  				// Optional. The system parameters.
        "ack":1,  			// Acknowledgment (ACK): `1` indicates the receiver must acknowledge the receipt of messages.
      	"trace":1  			// trace: `1` indicates message trace is enabled, which can be used to troubleshoot message sending and delivery.
    },
  	"code":0,  			// Optional. The status code, used to identify the request status.
  					//    `0` means success, the default value. Other values mean failure.
    "data":{...}  			//  Optional. The service parameters or results.
}

Parameter description

Parameters	Types	Description	Required	Notes
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 bits in length. The request and response are associated by a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
sys	object	System parameters	No	Two system parameters. ACK: 1 indicates the receiver must acknowledge the receipt of messages. trace: 1 indicates the message trace feature is enabled, which can be used to troubleshoot message sending and delivery.
code	number	Status code	No	Returns the request result in response messages. 0 means success, the default value. Other values mean failure.
data	object	Parameter/Result	No	The service parameters or results.

Request-response mechanism

Generally, the two-way communication between devices and the cloud is asynchronous messaging. Both parties do not take care of the receipt of messages or the result of action execution. For some applications that require high reliability, the results of message delivery/receipt or action execution determine the proceeding operations such as retry attempts or status display. This requires a message ID-based request-response mechanism on top of the asynchronous messaging.

Things to note

• A response topic must be constructed by attaching the suffix response to the request topic. For example:

  • The request topic for property setting: tylink/.../thing/property/set
  • The corresponding response topic: tylink/.../thing/property/set_response

• An acknowledgment (ACK) mechanism requires more traffic and system resources. In the protocol configuration, you can enable or disable the ACK feature for a specific topic as needed. For example, the ACK mechanism for messaging properties is disabled by default unless the ACK is set to sys:{"ack":1}.

• If the receiver does not respond within a timeout, retransmission with exponential backoff will be triggered. The retry configuration will try up to five times with an initial backoff of two seconds, a multiplier of two.

Sample

Message 1: The cloud sends a control command to the device

topic: tylink/6cd3f429bef1c1e767ruln/thing/action/execute
payload:
{
"msgId": "34Fewg345ggsetavt5671343gqwe0001",   
"time": 1626140638045,
/*
 * The ACK mechanism for action execution is enabled by default.
 *"sys": {
 *  "ack":1
 * },
 *
 */
"data":{
        "actionCode":"adjustAngle",
        "inputParams":{
        "direction":"left" // The input parameter
        }
    }
}

Message 2: The device returns the result of action execution

topic: tylink/6cd3f429bef1c1e767ruln/thing/action/execute_response
payload:
{
"msgId": "34Fewg345ggsetavt5671343gqwe0001",   
"time": 1626140638046,
"code": 0,
"data":{
        "actionCode":"adjustAngle",
        "outputParams":{    
        "angle":95   // The output parameter
        }
    }
}

MQTT topics

Topic name	Message type	Message direction	Description	Notes
tylink/${deviceId}/thing/model/get	thing.model.get	Device-to-cloud	The device requests the definition of the device model.	/
tylink/${deviceId}/thing/model/get_response	thing.model.get.response	Cloud-to-device	The cloud returns the definition of device model.	/
tylink/${deviceId}/thing/property/report	thing.property.report	Device-to-cloud	The device positively reports its properties.	/
tylink/${deviceId}/thing/property/report_response	thing.property.report.response	Cloud-to-device	The cloud responds to property reporting.	/
tylink/${deviceId}/thing/property/set	thing.property.set	Cloud-to-device	The cloud sends property setting to the device.	/
tylink/${deviceId}/thing/property/set_response	thing.property.set.response	Device-to-cloud	The device responds to the property setting.	/
tylink/${deviceId}/thing/property/get	thing.property.get	Cloud-to-device	The cloud positively queries device properties.	/
tylink/${deviceId}/thing/property/get_response	thing.property.get.response	Device-to-cloud	The device responds to the property query.	/
tylink/${deviceId}/thing/property/desired/get	thing.property.desired.get	Device-to-cloud	The device requests the desired property.	/
tylink/${deviceId}/thing/property/desired/get_response	thing.property.desired.get.response	Cloud-to-device	The cloud responds to the desired property request.	/
tylink/${deviceId}/thing/property/desired/delete	thing.property.desired.delete	Device-to-cloud	The device requests deleting the desired property.	/
tylink/${deviceId}/thing/property/desired/delete_response	thing.property.desired.delete.response	Cloud-to-device	The cloud responds to the deletion request.	/
tylink/${deviceId}/thing/data/batch_report	thing.data.batch.report	Device-to-cloud	The device reports data in bulk.	/
tylink/${deviceId}/thing/data/batch_report_response	thing.data.batch.report.response	Cloud-to-device	The cloud responds to bulk reporting.	/
tylink/${deviceId}/thing/event/trigger	thing.event.trigger	Device-to-cloud	The device triggers event messages.	/
tylink/${deviceId}/thing/event/trigger_response	thing.event.trigger.response	Cloud-to-device	The cloud responds to event messages.	/
tylink/${deviceId}/thing/action/execute	thing.action.execute	Cloud-to-device	The cloud sends action commands to the device.	/
tylink/${deviceId}/thing/action/execute_response	thing.action.execute.response	Device-to-cloud	The device returns the result of action execution.	/
tylink/${deviceId}/device/sub/login	device.sub.login	Device-to-cloud	The gateway reports the online status of its connected sub-device.	/
tylink/${deviceId}/device/sub/logout	device.sub.logout	Device-to-cloud	The gateway reports the offline status of its connected sub-device.	/
tylink/${deviceId}/device/sub/bind	device.sub.bind	Device-to-cloud	The gateway requests activating the discovered sub-device and establishing topological relationships.	/
tylink/${deviceId}/device/sub/bind_response	device.sub.bind.response	Cloud-to-device	The cloud responds to sub-device activation.	/
tylink/${deviceId}/device/topo/add	device.topo.add	Device-to-cloud	The gateway adds the device topology.	/
tylink/${deviceId}/device/topo/add_response	device.topo.add.response	Cloud-to-device	The cloud responds to adding device topology.	/
tylink/${deviceId}/device/topo/delete	device.topo.delete	Device-to-cloud	The gateway deletes the device topology.	/
tylink/${deviceId}/device/topo/delete_response	device.topo.delete.response	Cloud-to-device	The cloud responds to deleting device topology.	/
tylink/${deviceId}/device/topo/get	device.topo.get	Device-to-cloud	The gateway queries topology relationships.	/
tylink/${deviceId}/device/topo/get_response	device.topo.get.response	Cloud-to-device	The cloud responds to the topology relationships query.	/

tylink/${deviceId}/thing/model/get

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
  	"data":{
    	"format":"simple"
    }
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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	Parameters requested	No	/
data.format	string	The data format of the device model	No	simple (default): the lightweight data format information with fields irrelevant to the device operation excluded such as name and description. complete: the complete data format information.

tylink/${deviceId}/thing/model/get_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0,
    "data":{
      "modelId":"0000001yq9",
      "services":[
          {
              "code":"",
              "properties":[
                  {
                      "abilityId":1,
                      "code":"foodRemaining",
                      "accessMode":"ro",
                      "typeSpec":{
                          "type":"value",
                          "min":0,
                          "max":2000,
                          "step":1,
                          "unit":"g",
                          "scale":0
                      }
                  }
              ],
              "events":[
                  {
                      "abilityId":101,
                      "code":"feedEvent",
                      "outputParams":[
                          {
                              "code":"time",
                              "typeSpec":{
                                  "type":"date"
                              }
                          },
                          {
                              "code":"quantity",
                              "typeSpec":{
                                  "type":"value",
                                  "min":0,
                                  "max":2000,
                                  "step":1,
                                  "unit":"g",
                        		  "scale":0
                              }
                          }
                      ]
                  }
              ],
              "actions":[
                  {
                     "abilityId":101,
                      "code":"feed",
                  }
              ]
          }
      ]
	}
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	object	Result	No	The lightweight device model definition.

The description of status code

Status code	Description
0	Success, the default status
1001	Service exception
1002	Invalid parameter
1003	Incorrect message format
1004	Device does not exist

tylink/${deviceId}/thing/property/report

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"color":{
        	"value":"red",
          	"time": 1626197189638  
        },
        "brightness":{
              "value":80,
              "time": 1626197189638
        }
	}
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
sys	object	System parameters	No	A system operation on messaging.
sys.ack	number	Response to property reporting	No	By default, the cloud does not respond to a property reporting message. You can enable the ACK mechanism as needed. 0: No acknowledgment returned. 1: Acknowledgment returned.
data	object	A collection of property values reported	Yes	key represents the property code. value represents the property value and the timestamp when the property value is changed.
data.${key}	object	The property object	Yes	key represents the property code.
data.${key}.time	number	The timestamp when the property value is changed.	Yes	The Unix timestamp, in seconds (10-digit value) or milliseconds (13-digit value).
data.${key}.value	object	The property value reported	Yes	The specific property value.

tylink/${deviceId}/thing/property/report_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.

tylink/${deviceId}/thing/property/set

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"color":"green",
        "brightness":50
	}
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
sys	object	System parameters	No	A system operation on messaging.
sys.ack	number	Response to property reporting	No	By default, the cloud does not respond to a property reporting message. You can enable the ACK mechanism as needed. 0: No acknowledgment returned. 1: Acknowledgment returned.
data	object	A collection of property values sent to the device	Yes	key represents the property code. value represents the property value.

tylink/${deviceId}/thing/property/set_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.

tylink/${deviceId}/thing/property/get

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":[
    	"color",
        "brightness"
	]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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 property codes	No	If the list is empty, it means that all properties are queried.

tylink/${deviceId}/thing/property/get_response

{
	"msgId":"45lkj3551234001",
  	"time":1626197189640,
  	"code":0,
	"data":{
    	"color":{
        	"value":"red",
          	"time": 1626197189638
        },
        "brightness":{
              "value":80,
              "time": 1626197189638
        }
	}
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	object	A collection of property values	Yes	key represents the property code. value represents the property value and the timestamp when the property value is changed.
data.${key}	object	The property object	Yes	key represents the property code.
data.${key}.time	number	The timestamp when the property value is changed	Yes	The Unix timestamp, in seconds (10-digit value) or milliseconds (13-digit value).
data.${key}.value	object	The property value reported	Yes	The specific property value.

tylink/${deviceId}/thing/action/execute

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
      	"actionCode": "testAction",
      	"inputParams": {
          "inputParam1":"value1",
          "inputParam2":"value2"
    	}
	}
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that executes the specified action.
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 bits in length. The request and response are associated by a message ID.
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	The action parameters	Yes	The data includes action code and execution parameters.
data.actionCode	string	Action code	Yes	The action code defined by device model.
data.inputParams	object	Input parameters	No	key represents the parameter code. value represents the property value.

tylink/${deviceId}/thing/action/execute_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0,
  	"data":{
      	"actionCode": "testAction",
      	"outputParams": {
          "outputParam1":"value1",
          "outputParam2":"value2"
    	}
    }
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that executes the specified action.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	object	The action parameters	Yes	The data includes action code and a collection of output parameters.
data.actionCode	string	Action code	Yes	The action code defined by device model.
data.inputParams	object	Input parameters	No	key represents the parameter code. value represents the property value.

tylink/${deviceId}/thing/event/trigger

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
      	"eventCode":"testEvent",
      	"eventTime":1626197189630,   //  A timestamp when an event occurs, in seconds (10-digit value) or milliseconds (13-digit value).
      	"outputParams": {  		 // The output parameters.
          "outputParam1":"value1",
          "outputParam2":"value2"
    	}
	}
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that triggers the event.
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 bits in length. The request and response are associated by a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
sys	object	System parameters	No	A system operation on messaging.
sys.ack	number	Response to an event	No	By default, the cloud does not respond to an event reporting message. You can enable the ACK mechanism as needed. 0: No acknowledgment returned. 1: Acknowledgment returned.
data	object	Event parameters	Yes	The data includes event code and output parameters.
data.eventCode	string	Event code	Yes	The event code defined by device model.
data.outputParams	object	Output parameters	No	key represents the parameter code. value represents the property value.

tylink/${deviceId}/thing/event/trigger_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The device that requests the device model.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.

tylink/${deviceId}/thing/data/batch_report

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
      "properties":{
    	"color":{
        	"value":"red",
          	"time": 1626197189638
        }
      },
       "events":{
          "event1":{
                      "outputParams": {
                        "outputParam1":"value1",
                        "outputParam2":"value2"
                      },
                      "eventTime":1626197189001
              		},
          "event2":{
                      "outputParams": {
                        "outputParam1":"value1",
                        "outputParam2":"value2"
                      },
                      "eventTime":1626197189001
                    }
      },
      "subDevices":[
    		{
              "deviceId":"asd453452444",
              "properties":{
                "color":{
                    "value":"red",
                    "time": 1626197189638
                },
                "brightness":{
                      "value":80,
                      "time": 1626197189638
                }
              },
               "events":{
                  "event1":{
                              "outputParams": {
                                "outputParam1":"value1",
                                "outputParam2":"value2"
                              },
                              "eventTime":1626197189001
                           }
              		}
            }
	]
	}
  	
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that triggers the event.
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 bits in length. The request and response are associated by a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
sys	object	System parameters	No	A system operation on messaging.
sys.ack	number	Response to bulk reporting	No	By default, the cloud does not respond to a bulk reporting message. You can enable the ACK mechanism as needed. 0: No acknowledgment returned. 1: Acknowledgment returned.
data	object	A collection of data reported	Yes	The data includes the device data and its sub-device data.
data.properties	object	A collection of properties for bulk reporting	No	key represents the property code. value represents the property value and the timestamp when the property value is changed.
data.properties.${key}	object	The property object	Yes	key represents the property code.
data.properties.${key}.time	number	The timestamp when the property value is changed	Yes	The Unix timestamp, in seconds (10-digit value) or milliseconds (13-digit value).
data.properties.${key}.value	object	The property value reported	Yes	The specific property value.
data.events	object	A collection of events for bulk reporting	No	key represents the event code. value represents the event value and the timestamp when the event occurs.
data.events.${key}	object	The event object	Yes	code represents the event code.
data.events.${key}.eventTime	number	The timestamp when the event occurs	Yes	The Unix timestamp, in seconds (10-digit value) or milliseconds (13-digit value).
data.events.${key}.outputParams	object	Output parameters	Yes	A collection of output parameters.
data.subDevices	array	The list of sub-device data	No	If the device is a gateway, it can report the data of its connected sub-devices in bulk. Each element represents the data of one sub-device.
data.subDevices[]	object	The sub-device data	Yes	Each element represents the data of one sub-device.
data.subDevices[].deviceId	string	Sub-device ID	Yes	The ID of the sub-device whose data is reported.
data.subDevices[].properties	object	A collection of properties of sub-devices	No	The structure definition is similar to data.properties.
data.subDevices[].events	object	A collection of events of sub-devices	No	The structure definition is similar to data.events.

tylink/${deviceId}/thing/data/batch_report_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that reports data in bulk.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.

tylink/${deviceId}/thing/property/desired/get

{
    "msgId":"45lkj3551234001",
    "time":1626197189638,
    "data":{
        "properties":[
            "color",
            "brightness"
        ]
    }
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that queries the desired property.
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 bits in length. The request and response are associated by a message ID.
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	The parameter of desired property	No	/
data.properties	array	The list of specified desired properties	No	If the list is empty, it means all desired properties are requested.

tylink/${deviceId}/thing/property/desired/get_response

{
    "msgId":"45lkj3551234001",
    "time":1626197189640,
    "data":{
        "properties":{
            "color":{
                "value":"red",
                "version":1
            },
            "brightness":{
                "value":80,
                "version":2
            }
        }
    }
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that queries the desired property.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	object	The data requested	Yes	/
data.properties	object	A collection of desired properties	Yes	key represents the property code. value represents the property value and the version number.
data.properties.${key}	object	The object of desired property	Yes	key represents the property code.
data.properties.${key}.version	number	The version number of desired property	Yes	Each time the cloud changes the desired property, the version number of the property will be automatically incremented.
data.properties.${key}.value	object	The desired property value	Yes	The specific desired property value.

tylink/${deviceId}/thing/property/desired/delete

{
    "msgId":"45lkj3551234001",
    "time":1626197189600,
    "data":{
        "properties":{
            "color":{
                "version":1
            },
            "brightness":{
                "version":2
            }
        }
    }
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that requests deleting the desired property.
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 bits in length. The request and response are associated by a message ID.
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	Parameters	Yes	/
data.properties	object	A collection of desired properties to be deleted	Yes	key represents the property code. value represents the version number of the desired property value.
data.properties.${key}	object	The parameters of desired property	Yes	key represents the property code.
data.properties.${key}.version	number	The version number of desired property	Yes	Each time the cloud changes the desired property, the version number of the property will be automatically incremented.

tylink/${deviceId}/thing/property/desired/delete_response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that requests deleting the desired property.
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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	object	Result	Yes	key represents the property code. value represents the property value and the version number.

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189600,
	"data":[
      {
        "productId":"a123b456",
        "nodeId":"123455",
        "clientId":"123455asdf"
      },
      {
        "productId":"a123b457",
        "nodeId":"123456",
        "clientId":"453455asdf"
      }
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the device that requests deleting the desired property.
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 bits in length. The request and response are associated by a message ID.
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-devices to be bound	Yes	The parameters of sub-devices to be bound.
data[].productId	string	The PID of a sub-device	Yes	/
data[].nodeId	string	The node ID of a sub-device	Yes	The node ID of a sub-device, the unique one in one topology.
data[].clientId	string	The unique ID of the device	No	/

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
    "code":0,
	"data":[
      {
        "productId":"a123b456",
        "nodeId":"123455",
        "deviceId":"6c828cba434ff40c074wF2"
      },
      {
        "productId":"a123b457",
        "nodeId":"123456",
        "deviceId":"6c828cba434ff40c074wE3"
      }
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that requests binding sub-devices.
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 bits in length. The request and response are associated by a message ID.
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 bound sub-devices	Yes	/
data[].productId	string	The product ID (PID)	Yes	/
data[].nodeId	string	The node ID of a sub-device	Yes	The node ID of a sub-device, the unique one in one topology.
data[].deviceId	string	Unique device ID assigned to each sub-device	Yes	If the deviceId of the gateway and nodeId of the sub-device is not changed, the deviceId of the sub-device remains unchanged.

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189600,
	"data":[
      {
        "productId":"a123b456",
        "deviceId":"123455asdf",
        "sign":"adstewq35324ds",
        "signMethod":"hmacSha1",
        "timestamp":"16067836521"
      },
      {
        "productId":"a123b457",
        "deviceId":"123456",
        "sign":"adstewq35324ds",
        "signMethod":"hmacSha1",
        "timestamp":"16067836521"
      }
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that initiates 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 bits in length. The request and response are associated by a message ID.
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	The topology parameters of multiple sub-devices
data[].productId	string	The PID of a sub-device	Yes	/
data[].deviceId	string	The deviceId of a sub-device	Yes	The unique deviceId of a sub-device assigned by the cloud.
data[].sign	string	Signature	Yes	signMethod is used to sign the content. For example, hmacSha1(content, deviceSecret), the content includes productId=a123b457, deviceId=123456, and timestamp=16067836521.
data[].signMethod	string	Signature algorithm	Yes	The signature algorithm, such as HMACSHA1 .
data[].timestamp	string	Timestamp	Yes	/

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
  	"code":0,
	"data":[
      {
        "productId":"a123b456",
        "deviceId":"6c828cba434ff40c074wF2"
      },
      {
        "productId":"a123b457",
        "deviceId":"6c828cba434ff40c074wE3"
      }
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that initiates 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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	array	The list of topology relationships	Yes	/
data[].productId	string	The product ID (PID)	Yes	/
data[].deviceId	string	Device ID	Yes	/

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189600,
	"data":[
      "123455asdf",
      "123456tyiy"
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that requests deleting 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 bits in length. The request and response are associated by a message ID.
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 deviceId to be deleted	Yes	The list of sub-devices.

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
  	"code":0,
	"data":[
      "123455asdf",
      "123456tyiy"
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that initiates 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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	array	The list of deviceId to be deleted	Yes	The list of sub-devices.

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189600

}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	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 bits in length. The request and response are associated by a message ID.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).

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

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
  	"code":0,
	"data":[
      {
        "productId":"a123b456",
        "deviceId":"6c828cba434ff40c074wF2"
      },
      {
        "productId":"a123b457",
        "deviceId":"6c828cba434ff40c074wE3"
      }
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	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 bits in length. The request and response are associated by a message ID.
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 means success, the default value. Other values mean failure.
data	array	The list of sub-devices	Yes	/
data[].productId	string	The PID of a sub-device	Yes	/
data[].deviceId	string	The device ID of a sub-device	Yes	/

tylink/${deviceId}/device/sub/login

{
	"msgId":"45lkj3551234001",
    "time":1626197189600,
	"data":[
      "123455asdf",
      "123456tyiy"
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that reports online status of 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 bits in length. The request and response are associated by a message ID.
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 online deviceId	Yes	The list of sub-devices.

tylink/${deviceId}/device/sub/logout

{
	"msgId":"45lkj3551234001",
    "time":1626197189600,
	"data":[
      "123455asdf",
      "123456tyiy"
    ]
}

Parameter description

Parameters	Types	Description	Required	Notes
${deviceId}	string	Device ID	Yes	The ID of the gateway that reports online status of 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 bits in length. The request and response are associated by a message ID.
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 online deviceId	Yes	The list of sub-devices.