涂鸦开发者平台产品开发生态设备接入设备开发Tuya MQTT 标准协议设备属性、动作与事件

设备属性、动作与事件

更新时间：2024-04-07 08:25:00下载pdf

涂鸦云端通过物模型描述设备的功能定义，将设备功能抽象为属性、动作与事件。

本文介绍这三种设备能力的通讯机制和协议格式。具体平台操作说明，可查看功能定义进行了解。

属性上报

交互示意图

设备属性、动作与事件

设备发送消息

设备主动向云端上报设备属性值。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	属性上报的来源设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
sys	object	系统参数	否	控制消息的系统行为。
sys.ack	number	属性上报应答行为	否	默认情况下设备属性上报后云端不会返回应答消息，但可以通过 `ack` 参数改变这一默认行为。 `0`：不做应答，默认值。 `1`：处理之后返回应答消息。
data	object	上报的属性值集合	是	`key` 为属性 code，`value` 为属性值和属性变更时间戳。
data.${key}	object	属性上报对象	是	`key` 为属性 code。
data.${key}.time	number	属性变更时间戳	是	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.${key}.value	object	属性上报值	是	具体的属性值。

设备接收消息

云端处理上报后，默认不对属性上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。

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

{
	"msgId":"45lkj3551234***",
    "time":1626197189640,
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	属性上报的来源设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的上报消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。

状态码说明

状态码	说明
0	默认状态，代表成功。
1003	数据格式错误。
1004	设备不存在。
2002	设备关联的模型未定义。
2003	设备关联的属性未定义。
2006	数据校验失败。

属性下发

交互示意图

设备属性、动作与事件

设备接收消息

设备接收云端发送的属性设置消息。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	属性下发的目标设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
sys	object	系统参数	否	控制消息的系统行为。
sys.ack	number	属性下发应答行为	否	默认情况下设备属性下发后设备不会返回应答消息，但可以通过 `ack` 参数改变这一默认行为。 `0`：不做应答，默认值。 `1`：处理之后返回应答消息。
data	object	下发的属性值集合	是	下发属性值的集合，`key` 为属性 code，`value` 为属性值。

设备发送消息

设备在处理属性设置之后，默认不对属性设置消息进行响应，除非云端在设置消息中显式指定 ack 为 1。

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

{
	"msgId":"45lkj3551234***",
    "time":1626197189640,
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	属性下发的目标设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的属性设置消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。

动作执行

交互示意图

设备属性、动作与事件

设备接收消息

设备接收云端发送的动作执行消息。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	执行设备动作的目标设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	动作执行参数	是	包含动作 code 与执行参数。
data.actionCode	string	动作 code	是	动作的模型定义 code。
data.inputParams	object	动作输入参数	否	动作执行的输入参数，`key` 为参数 code，`value` 为参数值。

设备发送消息

当设备执行完动作之后，总是会向云端发送执行结果响应消息。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	执行设备动作的目标设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的动作执行消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
data	object	动作执行结果	否	包含动作 code 和输出参数集合。
data.actionCode	string	动作 code	否	动作的模型定义 code。
data.outputParams	object	动作输出参数	否	动作执行的输出参数，`key` 为参数 code，`value` 为参数值。

事件上报

交互示意图

设备属性、动作与事件

设备发送消息

设备主动向云端上报设备事件触发的消息。

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

{
	"msgId":"45lkj3551234***",
  	"time":1626197189638,
	"data":{
      	"eventCode":"testEvent",
      	"eventTime":1626197189630,   //10 位秒级或 13 位毫秒级事件发生时间戳
      	"outputParams": {			// 事件输出参数
          "outputParam1":"value1", 
          "outputParam2":"value2"
    	}
	}
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	触发事件的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
sys	object	系统参数	否	控制消息的系统行为。
sys.ack	number	事件触发应答作为	否	默认情况事件上报后云端不会返回应答消息，但可以通过 `ack` 参数改变这一默认行为。 `0`：不做应答，默认值。 `1`：处理之后返回应答消息。
data	object	事件触发参数	是	包含事件 code 与输出参数。
data.eventCode	string	事件code	是	事件的模型定义 code。
data.outputParams	object	事件输出参数	否	事件出参，`key` 为参数code，`value` 为参数值。

设备接收消息

云端接收事件消息之后，默认不对消息进行响应，除非设备在上报消息中显式指定 ack 为 1。

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

{
	"msgId":"45lkj3551234***",
    "time":1626197189640,
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	触发事件的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的事件触发消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。

状态码说明

状态码	说明
0	默认状态，代表成功。
1003	数据格式错误。
1004	设备不存在。
2002	设备关联的模型未定义。
2004	设备关联的事件未定义。
2006	数据校验失败。

设备批量上报

通过批量上报功能，设备可以一次性向云端上报多个事件、属性数据，同时网关设备还支持同时上报多个子设备的数据。一次性传输内容更多，效率更高。

使用限制：

网关设备一次可同时上报的子设备数量不能超过 20 个。
受 MQTT 网关限制，最终产生 MQTT 消息报文大小不能超过 64KB 大小，因此需要控制好一次上报的消息大小。
涂鸦云端尽可能地接收上报的数据，如果部分数据验证或处理失败，会返回 2121 状态码。如果所有数据都处理失败，会返回 2122。更多错误情况，请查看状态码说明。

设备发送消息

设备向云端批量上报属性、事件数据或者网关设备代替子设备批量上报。

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
                           }
              		}
            }
	]
	}
  	
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	批量上报的来源设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
sys	object	系统参数	否	控制消息的系统行为。
sys.ack	number	批量上报应答行为	否	默认情况下设备批量上报后云端不会返回应答消息，但可以通过 `ack` 参数改变这一默认行为。 `0`：不做应答，默认值。 `1`：处理之后返回应答消息。
data	object	上报的数据集合	是	包含设备自身的批量上报数据和子设备的上报数据。
data.properties	object	批量上报的属性集合	否	`key` 为属性 code，`value` 为属性值和属性变更时间戳。
data.properties.${key}	object	属性上报对象	是	`key` 为属性的 code。
data.properties.${key}.time	number	属性变更时间戳	是	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.properties.${key}.value	object	属性上报值	是	具体的属性值。
data.events	object	批量上报的事件集合	否	`key` 为事件 code，`value` 为事件参数和发生时间。
data.events.${key}	object	事件上报对象	是	`code` 为事件的 code。
data.events.${key}.eventTime	number	事件发生时间	是	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.events.${key}.outputParams	object	事件输出参数	是	事件输出的参数集合。
data.subDevices	array	子设备上报数据列表，子设备个数上限不能超过 20 个	否	当设备为网关时，可以为子设备批量上报数据，每一个列表元素代表一个子设备的数据。
data.subDevices[]	object	子设备上报数据	是	每个元素代表一个子设备的数据。
data.subDevices[].deviceId	string	子设备 ID	是	上报的子设备 ID。
data.subDevices[].properties	object	子设备批量上报的属性集合	否	结构定义与 `data.properties` 类似。
data.subDevices[].events	object	子设备批量上报的事件集合	否	结构定义与 `data.events` 类似。

设备接收消息

云端处理批量上报后，默认不对上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	批量上报的来源设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的批量上报消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。

状态码说明

状态码	说明
0	默认状态，代表成功。
1003	数据格式错误。
2121	批量上报部分数据处理失败。
2122	批量上报完全处理失败。
2123	批量上报子设备个数超过限制，目前子设备个数上限不能超过 20 个。

设备历史上报

设备向云端批量上报历史数据，或者网关设备代替子设备上报历史数据。

适用场景

可用于设备短时间产生大量上报数据的情况，将多次上报请求合并在一次上报中，以便提高效率。
也可用于离线或周期间隔上报的情况下，同时又要保留设备历史变化的场景。设备可在本地暂存过程历史数据，上报时将暂存的数据批量上报到云端。

使用限制

网关设备一次可同时上报的子设备数量不能超过 20 个。
受 MQTT 网关限制，最终产生 MQTT 消息报文大小不能超过 64KB 大小，因此需要控制一次上报的消息大小。
一次上报的历史数据量不超过 500 条，换言之， [属性数组 size + 事件数组 size + 子设备（属性数组 size + 事件数组 size）] < 500。
涂鸦 IoT 云尽可能地接收上报的数据，如果部分数据验证/处理失败，会返回 2121 状态码。如果所有数据都处理失败，会返回 2122。更多错误情况，请查看状态码说明部分。

注意事项

设备上报历史数据应按时间升序排序，存入属性数组或者事件数组中。
涂鸦 IoT 云按顺序遍历属性数组或者事件数组，进行数据处理。
属性最终存储的状态值以一次上报时序最新的数据为准，因此历史数据中应尽量带上时间戳。

设备发送消息

设备向云端批量上报历史数据，或者网关设备代替子设备上报历史数据。

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
                        }
                    }
                ]
            }
        ]
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	清除期望属性的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	批量上报的历史数据集合	是	包含设备自身的批量上报历史数据和子设备的上报历史数据。
data.properties	array	批量上报的历史属性集合	否	/
data.properties[]	object	批量上报的属性集合	是	数组按照属性变更时间升序存储，元素的 key 为属性 code，value 为属性值和属性变更时间戳。
data.properties[].${key}	object	属性上报对象	是	key 为属性的 code。
data.properties[].${key}.time	object	属性变更时间戳	否	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.properties[].${key}.value	object	属性上报值	是	具体的属性值。
data.events	array	批量上报的历史事件集合	否	/
data.events[]	object	批量上报的事件集合	是	数组按照事件发生的时间升序存储，元素的 key 为事件 code，value 为事件参数和发生时间。
data.events[].${key}	object	事件上报对象	是	code 为事件的 code。
data.events[].${key}.time	object	事件发生时间	否	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.events[].${key}.outputParams	object	事件输出参数	是	事件输出的参数集合。
data.subDevices	array	子设备上报数据列表	否	当设备为网关时，可以为子设备批量上报数据。每一个列表元素代表一个子设备的数据。
data.subDevices[]	object	子设备上报数据	是	每个元素代表一个子设备的数据。
data.subDevices[].deviceId	string	子设备 ID	是	上报的子设备 ID。
data.subDevices[].properties	array	子设备批量上报的历史属性集合	否	结构定义与 `data.properties` 类似。
data.subDevices[].events	array	子设备批量上报的历史事件集合	否	结构定义与 `data.events` 类似。

设备接收消息

云端处理上报后，默认不对上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。

Topic: tylink/${deviceId}/thing/data/history_report_response

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	历史上报的来源设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的历史上报消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，非 `0` 代表失败，默认 `0`。

状态码说明

状态码	说明
0	默认状态，代表成功。
1003	数据格式错误。
2121	历史上报部分数据处理失败。
2122	历史上报完全处理失败。
2123	历史上报子设备个数超过限制，目前子设备个数上限不能超过 20 个。
2124	历史数据量超过限制，目前数据量上限不能超过 500。

获取模型

设备发送消息

设备向云端发送设备模型查询请求。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	要查询设备模型的具体设备。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	查询参数	否	-
data.format	string	设备模型的格式类型	否	`simple`：（默认）精简版本，去除了 `name`、`description` 等与设备运行无关的属性。 `complete`：完整版本。

设备接收消息

云端查询设备的模型定义，然后通过响应消息返回给设备端。
以下示例返回的设备模型定义结构是经过精简后、去除 name、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",
                  }
              ]
          }
      ]
	}
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	查询设备模型的具体设备。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	与对应的查询请求消息的 `msgId` 保持一致，通过 `msgId` 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
data	object	结果	否	设备模型定义的 JSON 格式。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1002	参数不合法。
1003	消息格式错误。
1004	设备不存在。

获取期望属性

适用场景

设备处于离线状态，无法直接下发指令。希望在云端提供暂存指令的能力，当设备上线时可以主动查询，然后执行状态更新。
低功耗类设备周期性的休眠/唤醒。当设备被唤醒时，可以主动查询云端是否有需要执行的指令。

交互示意图

设备发送消息

设备向云端发送获取期望属性值的请求消息。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	查询期望属性的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	期望属性查询参数	否	-
data.properties	array	筛选指定的期望属性列表	否	为空代表返回当前设备所有的期望属性，否则只返回被筛选的属性 Code 列表。

设备接收消息

设备接收云端发送的期望属性响应。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	查询期望属性的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，非 `0` 代表失败，默认 `0`。
data	object	返回结果	否	-
data.properties	object	期望属性集合	是	`key` 为属性的 Code，`value` 为属性值和版本号。
data.properties.${key}	object	期望属性对象	是	属性 Code。
data.properties.${key}.version	number	期望属性的版本号	是	云端每次对期望属性做修改都会导致期望属性版本号自增，清除期望属性时也需要该值。
data.properties.${key}.value	object	属性期望值	是	具体的期望值。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1003	消息格式错误。

清除期望属性

设备发送消息

设备接收期望属性后，更新本地状态成功，然后向云端发送清除期望属性的消息。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	清除期望属性的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	清除参数	是	-
data.properties	object	清除的期望属性集合	是	`key` 为属性 code，`value` 为期望属性值的版本号。
data.properties.${key}	object	期望属性清除参数	是	属性 code。
data.properties.${key}.version	number	期望属性的版本号	是	当清除期望属性时需要带上查询时获取的版本号。只有当清除请求的版本号等于云端记录的版本号时，才能清除成功。

设备接收消息

设备接收云端返回的期望属性删除响应。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	清除期望属性的设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	`0` 代表成功，非 `0` 代表失败，默认 `0`。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。

上一篇MQTT 主题概览

下一篇拓扑关系管理