设备属性、功能与事件

通过物模型描述设备数字化属性和能力，将设备功能抽象为属性、功能(服务、方法)与事件。

属性上报

设备发送消息

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

接口	主题
MQTT	`things/up/${tenantId}/${productKey}/${deviceKey}/property/post`

json

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "property/post",
	"sys" :{
		"ack": 1
	},
	"data":{
    	"color":{
        	"value":"red",
          	"time": 1626197189638  
        }, 
        "brightness":{
            "value":80,
            "time": 1626197189638
        }
	}
}

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

json

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "property/post",
	"data":{
    	"color":"red",
        "brightness":80
	}
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	产品 ID	是	属性上报的来源设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性上报的来源设备 Key。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
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。

接口	主题
MQTT	`things/down/${tenantId}/${productKey}/${deviceKey}/property/post_reply`

json

{
	"msgId":"45lkj3551234",
    "time":1626197189640,
	"method": "property/post_reply",
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	产品 ID	是	属性上报的来源设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性上报的来源设备 Key。
${deviceSecret}	string	设备 ID	是	属性上报的来源设备密码。
msgId	string	消息 ID	是	与对应的上报消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值。非 0 代表失败。

状态码说明

状态码	说明
0	默认状态，代表成功。
201003	数据格式错误。
201004	设备不存在。
202002	设备关联的模型未定义。
202003	设备关联的属性未定义。
202006	数据校验失败。

属性下发

设备接收消息

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

接口	主题
MQTT	`things/down/${tenantId}/${productKey}/${deviceKey}/property/set`

json

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "property/set",
	"data":{
    	"color":"green", 
        "brightness":50
	}
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	属性下发的目标设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性下发的目标设备 Key。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
sys	object	系统参数	否	控制消息的系统行为。
sys.ack	number	属性下发应答行为	否	默认情况下设备属性下发后设备不会返回应答消息，但可以通过 ack 参数改变这一默认行为。 0：不做应答，默认值。 1：处理之后返回应答消息。
data	object	下发的属性值集合	是	下发属性值的集合，key 为属性 code，value 为属性值。

设备发送消息

设备在处理属性设置之后，需要设备对属性设置消息进行回复。

接口	主题
MQTT	`things/up/${tenantId}/${productKey}/${deviceKey}/property/set_reply`

json

{
	"msgId":"45lkj3551234",
    "time":1626197189640,
	"method": "property/set_reply",
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	属性下发的目标设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性下发的目标设备 Key。
msgId	string	消息 ID	是	与对应的属性设置消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值。非 0 代表失败。

功能调用

设备接收消息

设备接收云端发送的功能调用消息。

接口	主题
MQTT	`things/down/${tenantId}/${productKey}/${deviceKey}/function/set`

json

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "function/set",
	"data":{
      	"key": "testAction",
      	"input": {
          "inputParam1":"value1", 
          "inputParam2":"value2"
    	}
	}
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	功能调用目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	功能调用目标设备的 Key。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
data	object	功能调用参数	是	功能调用参数。
data.key	string	动作 code	是	动作的模型定义 code。
data.input	object	动作输入参数	否	功能调用的输入参数，key 为模型Key，value 为模型值。

设备发送消息

设备在处理功能调用之后，总是会对功能调用消息进行响应。

接口	主题
MQTT	`things/up/${tenantId}/${productKey}/${deviceKey}/function/set_reply`

json

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

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	功能调用目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	功能调用目标设备的 Key。
msgId	string	消息 ID	是	与对应的功能调用消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值。非 0 代表失败。
data	object	功能调用结果	否	功能调用的结果
data.key	string	动作 key	是	动作的模型定义 key。
data.output	object	动作输出参数	否	功能调用的输出参数，key 为参数 Key，value 为参数值。

事件上报

设备发送消息

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

接口	主题
MQTT	`things/up/${tenantId}/${productKey}/${deviceKey}/event/post`

json

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

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	事件上报的目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	事件上报的目标设备的 Key。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
data	object	事件上报参数	是	事件上报参数。
data.key	string	事件 key	是	事件的模型定义 key。
data.time	number	事件发生时间	否	事件发生时间的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data.value	object	事件模型值	否	事件模型的值。

设备接收消息

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

接口	主题
MQTT	`things/down/${tenantId}/${productKey}/${deviceKey}/event/post_reply`

json

{
	"msgId":"45lkj3551234",
    "time":1626197189640,
	"method": "event/post_reply",
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	事件上报的目标设备的所属产品 Key。
${deviceKey}	string	设备 ID	是	事件上报的目标设备的 Key。
msgId	string	消息 ID	是	与对应的事件触发消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值。非 0 代表失败。

状态码说明

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

批量上报

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

设备发送消息

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

接口	主题
MQTT	`things/up/${tenantId}/${productKey}/${deviceKey}/batch/post`

json

{
	"msgId":"45lkj3551234",
  	"time":1626197189638,
	"method": "batch/post",
	"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
				}
			}
		}
	  ]
	}
  	
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	属性上报的来源设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性上报的来源设备 Key。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
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}.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。

接口	主题
MQTT	`things/down/${tenantId}/${productKey}/${deviceKey}/batch/post_reply`

json

{
	"msgId":"45lkj3551234",
	"time":1626197189640,
	"method": "batch/post_reply",
	"code":0
}

参数说明

参数	类型	说明	必选	备注
${tenantId}	string	租户 ID	是	云平台分配的租户ID。
${productKey}	string	设备 ID	是	属性上报的来源设备所属产品 Key。
${deviceKey}	string	设备 ID	是	属性上报的来源设备 Key。
msgId	string	消息 ID	是	与对应的批量上报消息的 msgId 保持一致，通过 msgId 来标识应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
method	string	消息类型	否	消息类型，http和mqtt传输非必填，Websocket、TCP和UDP传输必填。
code	number	响应状态码	否	0 代表成功，默认值；非 0 代表失败。

设备属性、功能与事件 ​

属性上报 ​

设备发送消息 ​

设备接收消息 ​

属性下发 ​

设备接收消息 ​

设备发送消息 ​

功能调用 ​

设备接收消息 ​

设备发送消息 ​

事件上报 ​

设备发送消息 ​

设备接收消息 ​

批量上报 ​

设备发送消息 ​

设备接收消息 ​

设备属性、功能与事件

属性上报

设备发送消息

设备接收消息

属性下发

设备接收消息

设备发送消息

功能调用

设备接收消息

设备发送消息

事件上报

设备发送消息

设备接收消息

批量上报

设备发送消息

设备接收消息