Properties, Actions, and Events
Last Updated on : 2024-04-07 07:49:14download
A cloud-based things data model describes the functions defined for a concrete device in terms of the property, action, and event.
This topic describes how the device and the cloud communicate about these three interaction patterns as well as the topics and data structures used. For more information, see Function Definition.
Report property values
Interaction diagram
Device sends messages
The device proactively reports its property value to the cloud.
Topic: tylink/${deviceId}/thing/property/report
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"color":{
"value":"red",
"time": 1626197189638
},
"brightness":{
"value":80,
"time": 1626197189638
}
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The device ID. | Yes | The ID of the device that reports data. |
| version | string | Protocol version | No | The protocol version defaults to 1.0, which is the only valid value currently. |
| msgId | string | Message ID | Yes | A string up to 32 characters in length. The request and response are associated with 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 set the ack parameter to enable acknowledgment.
|
| 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. |
Device receives messages
By default, the cloud does not return a response after it processes the reported property value unless the ack is set to 1.
Topic: tylink/${deviceId}/thing/property/report_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The device ID. | Yes | The ID of the device that reports data. |
| version | string | Protocol version | No | The protocol version defaults to 1.0, which is the only valid value currently. |
| msgId | string | Message ID | Yes | The value of this parameter must be the same as the msgId of reporting property values. |
| 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 |
|
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1003 | Data format error. |
| 1004 | Device does not exist. |
| 2002 | The model associated with the device is not defined. |
| 2003 | The property associated with the device is not defined. |
| 2006 | Incorrect data check. |
Send property values
Interaction diagram
Device receives messages
The device receives property updates from the cloud.
Topic: tylink/${deviceId}/thing/property/set
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"color":"green",
"brightness":50
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The device ID. | Yes | The ID of the target device. |
| version | string | Protocol version | No | The protocol version defaults to 1.0, which is the only valid value currently. |
| msgId | string | Message ID | Yes | A string up to 32 characters in length. The request and response are associated with 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 the received message | No | By default, the device does not respond to a property update. You can set the ack parameter to enable acknowledgment.
|
| data | object | A collection of property values sent to the device | Yes | key represents the property code. value represents the property value. |
Device sends messages
By default, the device does not return a response after it processes the received property update unless the ack is set to 1.
Topic: tylink/${deviceId}/thing/property/set_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The device ID. | Yes | The ID of the target 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 | The value of this parameter must be the same as the msgId of receiving property update. |
| 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 |
|
Perform actions
Interaction diagram
Device receives messages
The device receives a message about performing an action from the cloud.
Topic: tylink/${deviceId}/thing/action/execute
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"actionCode": "testAction",
"inputParams": {
"inputParam1":"value1",
"inputParam2":"value2"
}
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The device ID. | Yes | The ID of the target device that performs 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 characters in length. The request and response are associated with 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 the device model. |
| data.inputParams | object | Input parameters | No | key represents the parameter code. value represents the property value. |
Device sends messages
The device responds to the cloud with the result after it performs the specified action.
Topic: tylink/${deviceId}/thing/action/execute_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0,
"data":{
"actionCode": "testAction",
"outputParams": {
"outputParam1":"value1",
"outputParam2":"value2"
}
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The device ID. | Yes | The ID of the target device that performs 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 | The value of this parameter must be the same as the msgId of performing an action. |
| 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 |
|
| data | object | The result of performing an action | No | The data includes action code and a collection of output parameters. |
| data.actionCode | string | Action code | No | The action code defined by the device model. |
| data.outputParams | object | Output parameters | No | key represents the parameter code. value represents the property value. |
Report events
Interaction diagram
Device sends messages
The device proactively reports the event-triggered message to the cloud.
Topic: tylink/${deviceId}/thing/event/trigger
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"eventCode":"testEvent",
"eventTime":1626197189630, // The event timestamp in seconds or milliseconds.
"outputParams": { // The output parameters.
"outputParam1":"value1",
"outputParam2":"value2"
}
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The 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 characters in length. The request and response are associated with 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 message. You can set the ack parameter to enable acknowledgment.
|
| data | object | Event parameters | Yes | The data includes event code and output parameters. |
| data.eventCode | string | Event code | Yes | The event code defined by the device model. |
| data.outputParams | object | Output parameters | No | key represents the parameter code. value represents the property value. |
Device receives messages
By default, the cloud does not return a response after it receives an event message unless the ack is set to 1.
Topic: tylink/${deviceId}/thing/event/trigger_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The 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 | The value of this parameter must be the same as the msgId of reporting an event-triggered message. |
| 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 |
|
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1003 | Data format error. |
| 1004 | Device does not exist. |
| 2002 | The model associated with the device is not defined. |
| 2004 | The event associated with the device is not defined. |
| 2006 | Incorrect data check. |
Report data in bulk
This feature allows a device to report multiple events or properties in one go. For a gateway device, it can report data of multiple sub-devices at the same time. This way, transfer efficiency is increased.
Limitations:
- A gateway device can report data of up to 20 sub-devices in one go.
- Due to the limitation of the MQTT gateway, the payload size of a message cannot exceed 64 KB.
- If some data fails to be verified or processed, the code 2121 is returned. If all the data fails to be processed, the code 2122 is returned. For more information about errors, see the description of status codes.
Device sends messages
The device reports properties or events to the cloud in bulk, or the gateway device reports data of multiple sub-devices.
Topic: tylink/${deviceId}/thing/data/batch_report
{
"msgId":"45lkj3551234***",
"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":"asd453452***",
"properties":{
"color":{
"value":"red",
"time": 1626197189638
},
"brightness":{
"value":80,
"time": 1626197189638
}
},
"events":{
"event1":{
"outputParams": {
"outputParam1":"value1",
"outputParam2":"value2"
},
"eventTime":1626197189001
}
}
}
]
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The 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 characters in length. The request and response are associated with 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 bulk data reporting. You can set the ack parameter to enable acknowledgment.
|
| 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 | Data of sub-devices to be reported. Up to 20 sub-devices can be reported in one go. | 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 to be reported in bulk | No | The structure definition is similar to data.properties. |
| data.subDevices[].events | object | A collection of events of sub-devices to be reported in bulk | No | The structure definition is similar to data.events. |
Device receives messages
By default, the cloud does not return a response after it processes the data reported in bulk unless the ack is set to 1.
Topic: tylink/${deviceId}/thing/data/batch_report_response
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The 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 | The value of this parameter must be the same as the msgId of reporting data in bulk. |
| 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 |
|
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1003 | Data format error. |
| 2121 | Some of the data reported in bulk fails to be processed. |
| 2122 | All the data reported in bulk fails to be processed. |
| 2123 | The number of sub-devices to be reported in bulk exceeds the limit of 20. |
Report historical data
The device reports historical data to the cloud in bulk, or the gateway device reports the historical data of sub-devices.
Scenarios
- When a device has a lot of data to report within a short time period, it can report them in one request for better efficiency.
- A device reports data periodically or reports the stranded data in case of device offline, while retaining the historical data. The device can stage the historical process data in the local storage and report the staged data to the cloud in bulk.
Limitations
- A gateway device can report data of up to 20 sub-devices in one go.
- Due to the limitation of the MQTT gateway, the payload size of a message cannot exceed 64 KB.
- Up to 500 pieces of historical data can be reported in one request. That is, the size of property arrays + the size of event arrays + the size of sub-devices (the size of property arrays + the size of event arrays) must be less than 500.
- If some data fails to be verified or processed, the code 2121 is returned. If all the data fails to be processed, the code 2122 is returned. For more information about errors, see the description of status codes.
Things to note
- The historical data is stored in a property or event array in ascending order by time.
- The cloud traverses the property or event arrays in order and then processes data.
- In the same request, the latest status of a property or event prevails. The timestamp should be included in the historical data if possible.
Device sends messages
The device reports historical data to the cloud in bulk, or the gateway device reports the historical data of sub-devices.
topic: tylink/${deviceId}/thing/data/history_report
{
"msgId":"45lkj3551234001",
"time":1626197189638,
"data":{
"properties":[
{
"color":{
"value":"red",
"time":1626197190000
},
"brightness":{
"value":80,
"time":1626197190000
}
},
{
"color":{
"value":"blue",
"time":1626197189000
},
"brightness":{
"value":79,
"time":1626197189000
}
}
],
"events":[
{
"event1":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
},
"event2":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
}
},
{
"event1":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
},
"event2":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
}
}
],
"subDevices":[
{
"deviceId":"asd453452444",
"properties":[
{
"color":{
"value":"red",
"time":1626197190000
},
"brightness":{
"value":80,
"time":1626197190000
}
},
{
"color":{
"value":"blue",
"time":1626197189000
},
"brightness":{
"value":79,
"time":1626197189000
}
}
],
"events":[
{
"event1":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
},
"event2":{
"outputParams":{
"outputParam1":"value11",
"outputParam2":"value21"
},
"eventTime":1626197190000
}
},
{
"event1":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
},
"event2":{
"outputParams":{
"outputParam1":"value10",
"outputParam2":"value20"
},
"eventTime":1626197189000
}
}
]
}
]
}
}
Description
| Parameter | Type | Description | Required | Remark |
|---|---|---|---|---|
| ${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 characters in length. A message ID is used to correlate responses and requests. |
| time | number | Message timestamp | Yes | The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value). |
| data | object | A collection of historical data for bulk reporting | Yes | The historical data can come from both the device itself and sub-devices. |
| data.properties | array | A collection of historical properties for bulk reporting | No | / |
| data.properties[] | object | A collection of properties for bulk reporting | Yes | The array is stored in ascending order by update time of property. key represents the property code. value represents the property value and the timestamp when the property value is updated. |
| data.properties[].${key} | object | The property object | Yes | key represents the property code. |
| data.properties[].${key}.time | object | The timestamp when the property value is changed. | No | 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 | array | A collection of historical events for bulk reporting | No | / |
| data.events[] | object | A collection of events for bulk reporting | Yes | The array is stored in ascending order by occurrence time of event. key represents the event code. value represents the event parameter and occurrence time. |
| data.events[].${key} | object | The event object | Yes | code represents the event code. |
| data.events[].${key}.time | object | The timestamp when the event occurs. | No | 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 list 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 | array | A collection of historical properties of sub-devices for bulk reporting | No | The structure definition is similar to data.properties. |
| data.subDevices[].events | array | A collection of historical events of sub-devices for bulk reporting | No | The structure definition is similar to data.events. |
Device receives messages
By default, the cloud does not return a response after it processes the data unless the ack is set to 1.
topic: tylink/${deviceId}/thing/data/history_report_response
{
"msgId":"45lkj3551234001",
"time":1626197189640,
"code":0
}
Description
| Parameter | Type | Description | Required | Remark |
|---|---|---|---|---|
| ${deviceId} | string | Device ID | Yes | The ID of the device that reports the historical data. |
| version | string | Protocol version | No | The protocol version defaults to 1.0, which is the only valid value currently. |
| msgId | string | Message ID | Yes | The value of this parameter must be the same as the msgId of reporting the historical data. |
| 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. |
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1003 | Data format error. |
| 2121 | Some of the reported historical data fails to be processed. |
| 2122 | All the reported historical data fails to be processed. |
| 2123 | The number of sub-devices to be reported exceeds the limit of 20. |
| 2124 | The size of historical data exceeds the limit of 500. |
Get the model
Device sends messages
The device requests the device model from the cloud.
Topic: tylink/${deviceId}/thing/model/get
{
"msgId":"45lkj3551234***",
"time":1626197189638,
"data":{
"format":"simple"
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The 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 characters in length. The request and response are associated with 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 |
|
Device receives messages
The device gets the device model from the response message.
The following code snippet shows the lightweight data structure of the device model, with the fields irrelevant to the device operation excluded such as name and description.
Topic: tylink/${deviceId}/thing/model/get_response
{
"msgId":"45lkj3551234***",
"time":1626197189640,
"code":0,
"data":{
"modelId":"0000001***",
"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",
}
]
}
]
}
}
Description
| Parameters | Type | Description | Required | Notes |
|---|---|---|---|---|
| ${deviceId} | string | The 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 | The value of this parameter must be the same as the msgId of requesting the device model. |
| 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 |
|
| data | object | Result | No | The data structure of the device model in JSON. |
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1001 | Service exception. |
| 1002 | Invalid parameter. |
| 1003 | Incorrect message format. |
| 1004 | Device does not exist. |
Get desired property
Scenarios
- When the device is offline, you cannot send a command to it directly. In this case, commands can be cached in the cloud so that the device can proactively request and execute them when it goes online.
- Low power devices sleep and wake up regularly. When the device wakes up, it can proactively request cached commands from the cloud.
Interaction diagram
Device sends messages
The device requests the desired property values from the cloud.
Topic: tylink/${deviceId}/thing/property/desired/get
{
"msgId":"45lkj3551234001",
"time":1626197189638,
"data":{
"properties":[
"color",
"brightness"
]
}
}
Description
| Parameter | Type | 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 characters in length. A message ID is used to correlate responses and requests. |
| time | number | Message timestamp | Yes | The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value). |
| data | object | Parameters of desired property | No | - |
| data.properties | array | List of specified desired properties | No | If the list is empty, it means all desired properties are requested. |
Device receives messages
The device receives the response to the desired property from the cloud.
Topic: tylink/${deviceId}/thing/property/desired/get_response
{
"msgId":"45lkj3551234001",
"time":1626197189640,
"data":{
"properties":{
"color":{
"value":"red",
"version":1
},
"brightness":{
"value":80,
"version":2
}
}
}
}
Description
| Parameter | Type | 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 characters in length. A message ID is used to correlate responses and requests. |
| time | number | Message timestamp | Yes | The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value). |
| code | number | Response status code | No | 0 means success, the default value. Other values mean failure. |
| data | object | Return result | No | - |
| data.properties | object | Collection of desired properties | Yes | key represents the property code. value represents the property value and the version number. |
| data.properties.${key} | object | Object of desired property | Yes | The property code. |
| data.properties.${key}.version | number | Version of desired property | Yes | Whenever the cloud updates the desired property, its version number will be automatically incremented. Deleting the desired property will also clear this parameter. |
| data.properties.${key}.value | object | Desired property value | Yes | The specific desired property value. |
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1001 | Service exception. |
| 1003 | Incorrect message format. |
Delete desired property
Device sends messages
After successfully updating the value of a desired property, the device will send a message to the cloud to delete that desired property.
Topic: tylink/${deviceId}/thing/property/desired/delete
{
"msgId":"45lkj3551234001",
"time":1626197189600,
"data":{
"properties": {
"color":{
"version":1
},
"brightness":{
"version":2
}
}
}
}
Description
| Parameter | Type | 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 characters in length. A message ID is used to correlate responses and requests. |
| time | number | Message timestamp | Yes | The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value). |
| data | object | Parameters to be deleted | Yes | - |
| data.properties | object | Collection of desired properties to be deleted | Yes | key represents the property code. value represents the property value and the version number. |
| data.properties.${key} | object | Parameters of desired property | Yes | The property code. |
| data.properties.${key}.version | number | Version of desired property | Yes | When deleting a desired property, make sure to include the version number returned from the query. The deletion is successful only if the version number of the delete request matches the version number stored in the cloud. |
Device receives messages
The device receives the response to the deletion of the desired property.
Topic: tylink/${deviceId}/thing/property/desired/delete_response
{
"msgId":"45lkj3551234001",
"time":1626197189640,
"code":0
}
Description
| Parameter | Type | 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 characters in length. A message ID is used to correlate responses and requests. |
| time | number | Message timestamp | Yes | The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value). |
| code | number | Response status code | No | 0 means success, the default value. Other values mean failure. |
The description of status codes
| Status code | Description |
|---|---|
| 0 | The default status, indicating success. |
| 1001 | Service exception. |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedbackMarketing Cooperation
Business Cooperation
Customer Service
Media Inquiry
© 2024 Tuya Inc.