设备属性、动作与事件

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

属性上报

设备发送消息

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

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/property/post

HTTP POST：/device/v1/property/post?accessToken=xxx&tenantId=xxx&productKey=xxx&deviceKey=xxx

json

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

支持不带时间戳，默认使用设备上报时间。

json

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

参数说明

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

设备接收消息

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

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/property/post_reply

json

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

参数说明

参数	类型	说明	必选	备注
${productKey}	string	设备 ID	是	属性上报的来源设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性上报的来源设备 Key。
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：things/down/${tenantId}/${productKey}/${deviceKey}/property/set

json

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

参数说明

参数	类型	说明	必选	备注
${productKey}	string	设备 ID	是	属性下发的目标设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性下发的目标设备 Key。
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：things/down/${tenantId}/${productKey}/${deviceKey}/function/set_reply

json

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

参数说明

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

动作执行

设备接收消息

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

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/function/set

json

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

参数说明

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

设备发送消息

设备在处理动作执行之后，总是会对动作执行消息进行响应。

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/function/set_reply

json

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

参数说明

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

事件上报

设备发送消息

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

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/event/post

HTTP POST：/device/v1/event/post?accessToken=xxx&tenantId=xxx&productKey=xxx&deviceKey=xxx

json

{
	"msgId":"45lkj3551234***",
  	"time":1626197189638,
	"data":{
      	"key":"testEvent",
      	"time":1626197189630,   //10 位秒级或 13 位毫秒级事件发生时间戳
      	"value": 123
	}
}

参数说明

参数	类型	说明	必选	备注
${productKey}	string	设备 ID	是	事件上报的目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	事件上报的目标设备的 Key。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	事件上报参数	是	事件上报参数。
data.key	string	事件 key	是	事件的模型定义 key。
data.time	number	事件发生时间	否	事件发生时间的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data.value	object	事件模型值	否	事件模型的值。

设备接收消息

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

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/event/post_reply

json

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

参数说明

参数	类型	说明	必选	备注
${productKey}	string	设备 ID	是	事件上报的目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	事件上报的目标设备的 Key。
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 个。

批量上报

批量上报是指网关设备一次请求中可以同时上报多个事件和属性，包含子设备的事件和属性。

设备发送消息

设备主动向云端上报多个事件和属性，包含子设备的事件和属性。

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/batch/post

json

{
	"msgId":"45lkj3551234***",
  	"time":1626197189638,
	"data":{
      "properties":{
    	"color":{
        	"value":"red",
          	"time": 1626197189638 
        }
      },
      "events":{
		"event1":{
					"value": "",
					"time":1626197189001
				},
		"event2":{
					"value": "value1",
					"time":1626197189001
				}
      },
      "subDevices":[
		{
			"product":"th453452***", 
			"device":"asd453452***", 
			"properties":{
				"color":{
					"value":"red",
					"time": 1626197189638 
				}, 
				"brightness":{
						"value":80,
						"time": 1626197189638
				}
			},
			"events":{
				"event1":{
					"value": "",
					"time":1626197189001
				}
			}
		}
	  ]
	}
  	
}

参数说明

参数	类型	说明	必选	备注
${productKey}	string	设备 ID	是	属性上报的来源设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性上报的来源设备 Key。
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.$	object	属性上报对象	是	key 为属性的 code。
data.properties.${key}.time	number	属性变更时间戳	是	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.properties.${key}.value	object	属性上报值	是	具体的属性值。
data.events	object	批量上报的事件集合	否	key 为事件 code，value 为事件参数和发生时间。
data.events.$	object	事件上报对象	是	code 为事件的 code。
data.events.${key}.time	number	事件发生时间	是	Unix 时间戳，10 位秒级或 13 位毫秒级。
data.events.${key}.value	object	事件输出参数	是	事件输出的参数集合。
data.subDevices	array	子设备上报数据列表	否	子设备个数上限不能超过 20 个。
data.subDevices[]	object	子设备上报数据	是	每个元素代表一个子设备的数据。
data.subDevices[].product	string	子设备所属产品 Key	是	上报的子设备所属产品 Key。
data.subDevices[].device	string	子设备 Key	是	上报的子设备 Key。
data.subDevices[].properties	object	子设备批量上报的属性集合	否	结构定义与 data.properties 类似。
data.subDevices[].events	object	子设备批量上报的事件集合	否	结构定义与 data.events 类似。

设备接收消息

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

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/batch/post_reply

json

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

参数说明

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

设备属性、动作与事件 ​

属性上报 ​

设备发送消息 ​

设备接收消息 ​

属性下发 ​

设备接收消息 ​

设备发送消息 ​

动作执行 ​

设备接收消息 ​

设备发送消息 ​

事件上报 ​

设备发送消息 ​

设备接收消息 ​

批量上报 ​

设备发送消息 ​

设备接收消息 ​

设备属性、动作与事件

属性上报

设备发送消息

设备接收消息

属性下发

设备接收消息

设备发送消息

动作执行

设备接收消息

设备发送消息

事件上报

设备发送消息

设备接收消息

批量上报

设备发送消息

设备接收消息