联系我们

取消

空间导航

该内容对您有帮助吗？

是否

涂鸦 IoT 开发平台产品开发智能化方式生态设备接入设备开发Tuya MQTT 标准协议

Tuya MQTT 标准协议

更新时间：2022-05-24 06:04:14下载pdf

MQTT 连接说明

连接协议包含参数如下：

参数名称	参数说明
接入域名	MQTT 服务的地址，可自行选择域名。不建议写死域名，如果写死连中国域名，设备流入美国或欧洲会有合规风险！
可变报文头	包含保活时间（keepAlive），在网络不好时可以设置长一些。一般为 30s~1200s，大多数设备是 60s。一定范围内，越长对网络抖动的容错能力越强。连接超时 `connectionTimeout`，超过这个时间还是连不上，会被判定为连接失败。
mqttClientId	tuyalink_${deviceId} 例如：tuyalink_6c828cba434ff40c074wF2
mqttUsername	${deviceId}\|signMethod=hmacSha256,timestamp=${当前 10 位时间戳},secureMode=1,accessType=1;例如：6c828cba434ff40c074wF2\|signMethod=hmacSha256,timestamp=1607837283,secureMode=1,accessType=1
mqttPassword	hmacSha256(content, deviceSecret)，content 的值"deviceId=6c828cba434ff40c074wF2,timestamp=1607635284,secureMode=1,accessType=1",按照 deviceId，timestamp,secureMode,accessType 这个顺序组装明文内容。64 字符的 16 进制，不足 64，前面补零
accessType	接入类型。 1：开放协议对接
secureMode	安全模式。 1：一机一密
timestamp	时间戳，到秒级别
signMethod	签名算法，可根据硬件能力选择 `hmacSha1`、`hmacSha256` 等
示例：

    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
    });

Topic 规范

格式：

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

示例：

设备向云端上报属性
设备清除云端属性期望值

Payload 规范

Payload 默认为 JSON 格式，但也可以通过 topic 的 format 参数指定为其他格式例如：messagepack。
原则上，云端不主动使用 JSON 之外的格式，因为暂时无法确定设备端支持的消息格式，但云端在应答设备上报时应与上报消息的格式保持一致。例如：某设备通过 messagepack 格式上报了属性消息，云端处理上报后返回响应消息时也应使用 messagepack 格式。

内容构成

{
    "version":"1.0",				// 可选；协议版本，默认值为 1.0，且仅有 1.0
    "msgId":"j4sdfl39Twe3494",		// 必选；消息 ID，不超过 32 位字符长度的字符串
    "time":1234567890123,			// 必选；消息发送时间戳（10 位秒级或 13 位毫秒级）
    "sys":{				        // 可选；系统参数，属于业务数据之外的额外信息
        "ack":0,			       // 参数 ACK：0 表示消息不需要通讯对方明确的处理应答
      	"trace":1				// 参数 trace：1 表示消息诊断跟踪开启
    },
  	"code":0,		// 可选；响应状态码，当做为响应消息时代表请求处理的
  				// 结果状态。0 代表成功，非 0 代表失败，默认值为 0
    "data":{...}			// 可选；实际的业务参数/结果
}

参数说明

参数	类型	说明	必选	备注
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
sys	object	系统参数	否	属于业务数据之外的额外的系统参数。 `ACK`：0 表示消息不需要通讯对方明确的处理应答参数。 `trace`：1 表示消息诊断跟踪开启。
code	number	响应状态码	否	仅在响应消息中出现，整数结果状态。0 代表成功，非 0 代表失败，默认值为 0。
data	object	参数/结果	否	实际的业务参数/结果

消息应答

设备与云端之间的通信都是基于异步的消息，大部分时候不关注消息接收方是否收到消息、处理结果如何。但某些业务场景会有更高的可靠性诉求，需要明确根据对方的接收状态以及处理结果做出业务响应或是发起重试或是向终端用户展示信息等等，这就要求在异步的消息通讯基础之上建立一套应答机制，在这套机制中通讯双方以一个唯一的消息 ID 建立起请求/应答消息的关联关系。

注意事项

请求响应消息的 topic 应成对，响应 topic 在请求 topic 基础之上增加 response 后缀。例如：
- 属性设置 topic：tylink/.../thing/property/set
- 属性设置响应 topic：tylink/.../thing/property/set_response
Ack 机制对消息流量和系统资源都是有开销的，非必要场景可以不用 ACK，因此在进行协议设计时可以事先确定默认是否需要 ACK，在实际的消息发送时可以通过 ACK 系统参数来灵活的控制。例如：属性的上报和下发默认情况下都是不需要 ACK 的，除非显式的指明 sys:{"ack":1} 才需要对方发送 ACK 消息。
当等待接收对方应答超时后可以进行消息重发，每次重发需要增加延迟时间，从第 1 次 2 秒延时开始以指数退避的方式，每重试一次延时增加 1 倍，一般总重试次数不超过 5 次。

示例

消息 1：云端下发动作执行的消息

topic: tylink/6cd3f429bef1c1e767ruln/thing/action/execute
payload：
{
"msgId": "34Fewg345ggsetavt5671343gqwe0001",   
"time": 1626140638045,
/*
 * 动作执行默认就是需要对方 ACK，所以不需要显式的指定 ACK 参数
 *"sys": {
 *  "ack":1 
 * },
 *
 */
"data":{
        "actionCode":"adjustAngle",
        "inputParams":{ 
        "direction":"left" //入参
        }
    } 
}

消息 2：设备响应动作执行结果

topic: tylink/6cd3f429bef1c1e767ruln/thing/action/execute_response
payload：
{
"msgId": "34Fewg345ggsetavt5671343gqwe0001",   
"time": 1626140638046,
"code": 0, 
"data":{ 
        "actionCode":"adjustAngle",
        "outputParams":{    
        "angle":95   //出参结果
        }
    }
}

MQTT 协议

MQTT Topic 名称	消息类型	方向	描述	备注
tylink/${deviceId}/thing/model/get	thing.model.get	设备上报	设备获取设备模型定义	/
tylink/${deviceId}/thing/model/get_response	thing.model.get.response	云端响应	云端响应返回设备模型定义	/
tylink/${deviceId}/thing/property/report	thing.property.report	设备上报	设备主动属性上报	/
tylink/${deviceId}/thing/property/report_response	thing.property.report.response	云端响应	云端响应属性上报	/
tylink/${deviceId}/thing/property/set	thing.property.set	云端下发	云端设置设备属性	/
tylink/${deviceId}/thing/property/set_response	thing.property.set.response	设备响应	设备响应属性设置	/
tylink/${deviceId}/thing/property/get	thing.property.get	云端下发	云端主动查询设备属性	/
tylink/${deviceId}/thing/property/get_response	thing.property.get.response	设备响应	设备响应属性查询请求	/
tylink/${deviceId}/thing/property/desired/get	thing.property.desired.get	设备上报	设备获取设备期望属性	/
tylink/${deviceId}/thing/property/desired/get_response	thing.property.desired.get.response	云端响应	云端响应设备期望属性查询	/
tylink/${deviceId}/thing/property/desired/delete	thing.property.desired.delete	设备上报	设备删除期望属性	/
tylink/${deviceId}/thing/property/desired/delete_response	thing.property.desired.delete.response	云端响应	云端响应删除	/
tylink/${deviceId}/thing/data/batch_report	thing.data.batch.report	设备上报	设备批量或为子设备上报	/
tylink/${deviceId}/thing/data/batch_report_response	thing.data.batch.report.response	云端响应	云端响应批量上报	/
tylink/${deviceId}/thing/event/trigger	thing.event.trigger	设备上报	设备触发事件消息	/
tylink/${deviceId}/thing/event/trigger_response	thing.event.trigger.response	云端响应	云端响应事件消息	/
tylink/${deviceId}/thing/action/execute	thing.action.execute	云端下发	云端调用执行设备动作	/
tylink/${deviceId}/thing/action/execute_response	thing.action.execute.response	设备响应	设备端响应执行结果	/
tylink/${deviceId}/device/sub/login	device.sub.login	设备上报	网关代理子设备上线	/
tylink/${deviceId}/device/sub/logout	device.sub.logout	设备上报	网关代理子设备下线	/
tylink/${deviceId}/device/sub/bind	device.sub.bind	设备上报	网关发现子设备，请求激活子设备并建立拓扑关系	/
tylink/${deviceId}/device/sub/bind_response	device.sub.bind.response	云端响应	云端响应子设备绑定	/
tylink/${deviceId}/device/topo/add	device.topo.add	设备上报	网关添加设备拓扑关系	/
tylink/${deviceId}/device/topo/add_response	device.topo.add.response	云端响应	云端响应添加设备拓扑关系	/
tylink/${deviceId}/device/topo/delete	device.topo.delete	设备上报	网关删除设备拓扑关系	/
tylink/${deviceId}/device/topo/delete_response	device.topo.delete.response	云端响应	云端响应删除设备拓扑关系	/
tylink/${deviceId}/device/topo/get	device.topo.get	设备上报	网关请求云端查询拓扑关系	/
tylink/${deviceId}/device/topo/get_response	device.topo.get.response	云端响应	云端响应拓扑关系查询	/

设备获取设备模型定义

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

{
  "msgId": "45lkj3551234001",
  "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：完整版本

云端响应返回设备模型定义

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	查询设备模型的具体设备
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
code	number	响应状态码	否	0 代表成功，非 0 代表失败，默认值为 0
data	object	结果	否	设备模型定义的精简格式

状态码说明

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

设备主动属性上报

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 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，vaue 为属性值和属性变更时间戳
data.${key}	object	属性上报对象	是	key 为属性 code
data.${key}.time	number	属性变更时间戳	是	Unix 时间戳（10 位秒级或 13 位毫秒级）
data.${key}.value	object	属性上报值	是	具体的属性值

云端响应属性上报

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

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

参数说明

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

云端设置设备属性

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 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，vaue 为属性值

设备响应属性设置

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

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

参数说明

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

云端主动查询设备属性

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	要查询设备模型的具体设备
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	查询的属性 code 列表	否	查询的属性 code 列表，如果为空代表查询所有

设备响应属性查询请求

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	要查询设备模型的具体设备
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
code	number	响应状态码	否	0 代表成功，非 0 代表失败，默认值为 0
data	object	查询返回的属性值集合	是	key 为属性 code，vaue 为属性值和属性变更时间戳
data.${key}	object	属性上报对象	是	key 为属性 code
data.${key}.time	number	属性变更时间戳	是	Unix 时间戳（10 位秒级或 13 位毫秒级）
data.${key}.value	object	属性上报值	是	具体的属性值

云端调用执行设备动作

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

{
  "msgId": "45lkj3551234001",
  "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 为参数值

设备端响应执行结果

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

  "msgId": "45lkj3551234001",
  "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	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
code	number	响应状态码	否	0 代表成功，非 0 代表失败，默认值为 0
data	object	动作执行参数	是	包含动作 code 和输出参数集合
data.actionCode	string	动作 code	是	动作的模型定义 code
data.inputParams	object	动作输入参数	否	动作执行的输入参数，key 为参数 code，value 为参数值

设备触发事件消息

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

{
	"msgId":"45lkj3551234001",
  	"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 为参数值

云端响应事件消息

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

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

参数说明

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

设备批量或为子设备上报

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

参数说明

参数	类型	说明	必选	备注
${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，vaue 为属性值和属性变更时间戳
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	子设备上报数据列表	否	当设备为网关时可以为子设备批量上报数据，每一个列表元素代表一个子设备的数据
data.subDevices[]	object	子设备上报数据	是	每个元素代表一个子设备的数据
data.subDevices[].deviceId	string	子设备 ID	是	上报的子设备 ID
data.subDevices[].properties	object	子设备批量上报的属性集合	否	结构定义与 data.properties 类似
data.subDevices[].events	object	子设备批量上报的事件集合	否	结构定义与 data.events 类似

云端响应批量上报

tylink/${deviceId}/thing/data/batch_report_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

设备获取设备期望属性

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 列表

云端响应设备期望属性查询

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，vaue 为属性值和版本号
data.properties.${key}	object	期望属性对象	是	key 为属性 code
data.properties.${key}.version	number	期望属性的版本号	是	云端每次对期望属性做修改都会导致期望属性版本号自增
data.properties.${key}.value	object	属性期望值	是	具体的期望值

设备删除期望属性

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，vaue 为期望属性值的版本号
data.properties.${key}	object	期望属性清除参数	是	key 为属性 code
data.properties.${key}.version	number	期望属性的版本号	是	云端每次对期望属性做修改都会导致期望属性版本号自增

云端响应删除期望值

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
data	object	结果	是	key 为属性 code，vaue 为属性值和版本号

网关发现子设备，请求激活子设备并建立拓扑关系

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	清除期望属性的设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	子设备绑定参数列表	是	多个子设备绑定参数
data[].productId	string	子设备的产品 ID	是	/
data[].nodeId	string	子设备的节点 ID	是	子设备的节点 ID，至少保证网关下唯一，将显示在设备管理 > 设备详情 > 子设备节点ID 字段
data[].clientId	string	设备端唯一 ID	否	可使用设备 MAC 地址或 SN 码，至少保证产品下唯一，将显示在设备管理 > 注册 ID 字段

云端响应子设备绑定

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起子设备绑定的网关设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	子设备绑定结果列表	是	/
data[].productId	string	产品 ID	是	/
data[].nodeId	string	子设备的节点 ID	是	子设备的节点 ID，至少保证网关下唯一，将显示在设备管理 > 设备详情 > 子设备节点 ID 字段
data[].deviceId	string	云端分配的唯一设备 ID	是	网关的 deviceId + 子设备的 nodeId 不变，多次绑定使用同一个 deviceId，否则重新生成一个新的 deviceId

网关添加设备拓扑关系

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起拓扑关系创建的网关设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	子设备参数列表	是	多个子设备拓扑参数
data[].productId	string	子设备的产品 ID	是	/
data[].deviceId	string	子设备的 deviceId	是	注册设备时，获取的 deviceId，云端分配的唯一 ID
data[].sign	string	签名	是	使用 signMethod 对内容进行签名。例如，`hmacSha1（content, deviceSecret）`，content 的内容是：`productId=a123b457,deviceId=123456,timestamp=16067836521
data[].signMethod	string	签名算法	是	签名算法，比如 hmacSha1
data[].timestamp	string	时间戳	是	/

云端响应添加设备拓扑关系

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

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

参数说明

参数	类型	说明	必选	备注
${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	array	拓扑关系创建结果列表	是	/
data[].productId	string	产品 ID	是	/
data[].deviceId	string	设备 ID	是	/

网关删除设备拓扑关系

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起拓扑关系删除的网关设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	待删除的子设备 deviceId 列表	是	多个子设备的 deviceId 列表

云端响应删除设备拓扑关系

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

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

参数说明

参数	类型	说明	必选	备注
${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	array	待删除的子设备 deviceId 列表	是	多个子设备的 deviceId 列表

网关请求云端查询拓扑关系

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起拓扑关系查询的网关设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）

云端响应拓扑关系

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

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

参数说明

参数	类型	说明	必选	备注
${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	array	子设备列表	是	/
data[].productId	string	子设备的产品 ID	是	/
data[].deviceId	string	子设备的设备 ID	是	/

网关代理子设备上线

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起子设备上线的网关设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	上线的子设备 deviceId 列表	是	多个子设备的 deviceId 列表

网关代理子设备下线

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起子设备上线的网关设备 ID
version	string	协议版本	否	默认值为 1.0，且仅有 1.0
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）
data	array	上线的子设备 deviceId 列表	是	多个子设备的 deviceId 列表

该内容对您有帮助吗？

是否

上一篇设备开发

下一篇C Tuya IoT Core SDK

产品开发

IoT 开发包

MCU 开发工具

电工产品零代码开发

照明产品零代码开发

传感产品零代码开发

IPC 产品零代码开发

网关产品零代码开发

TuyaOS

垂直品类设备开发

边缘计算网关

设备驱动开发

Link SDK

App 开发

行业 App SDK

智能生活 App SDK

垂直品类扩展 SDK

UI 业务包

IoT 微信小程序 SDK

面板 SDK

面板工作台

All in One App

OEM App

IoT 微信小程序

云开发

IoT Core 连接服务

全球物联卡服务

设备日志服务

数据分析

数据星象仪

实时音视频

邮件服务

语音消息服务

短信服务

天气服务

更多云服务

设备振动分析

设备监控

设备分布

工业能耗分析

房屋安全报警

环境健康

客流统计

智慧会议预约

智慧办公

智慧零售

智慧节能

智慧校园

智慧地产

文档中心

5 分钟产品智能化

云开发快速入门

云开发操作指南

涂鸦 IoT App 开发

智能化方式

Demo

涂鸦 Wind IDE

模组调试助手

视频教程

硬件产品测试

硬件产品认证

工业设计

涂鸦 IoT 开发平台

Tuya MQTT 标准协议

MQTT 连接说明

Topic 规范

Payload 规范

内容构成

参数说明

消息应答

注意事项

示例

MQTT 协议

设备获取设备模型定义

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

云端响应返回设备模型定义

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

设备主动属性上报

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

云端响应属性上报