简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

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 签名算法,可根据硬件能力选择 hmacSha1hmacSha256
示例:
    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}]

示例:

  • 设备向云端上报属性

    Tuya MQTT 标准协议

  • 设备清除云端属性期望值

    Tuya MQTT 标准协议

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