Open MQTT Protocol

Last Updated on : 2021-12-09 14:53:22download

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

    Open MQTT Protocol

  • Device clears the desired property value from the cloud

    Open MQTT Protocol

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.