物模型:属性、事件、服务
物模型:属性、事件、服务
物模型(TSL)定义产品的属性、事件与服务。平台按 productKey + identifier (+ block) 校验设备上报的数据。数据类型与 identifier 命名规则见建立 MQTT 连接 → 配置物模型。
再次强调:属性/事件上报回复的
code:200只表示平台已收到并可解析 JSON,不代表逐属性校验通过;校验失败的属性会被过滤,只写入该设备的云端日志。
属性上报
Topic:/sys/{pk}/{dn}/thing/event/property/post(全等匹配)
{
"id": "1601234567890123456",
"version": "1.0",
"sys": { "ack": 1 },
"params": {
"temperature": 23.6,
"Power": { "value": "on", "time": 1700000000000 },
"workMode": 1,
"running": true,
"deviceTime": "2026-10-25 10:00:00.000",
"wifiInfo": { "ssid": "office", "rssi": -55 },
"tags": ["a", "b"],
"MCU:fwVersion": "1.0.3"
},
"method": "thing.event.property.post"
}字段规则:
| 写法 | 说明 |
|---|---|
"key": 值 | 简写,时间戳由平台按服务端当前时间填充 |
"key": {"value": 值, "time": 时间戳} | 携带采样时间;time 支持 10 位秒或 13 位毫秒(小于 10000000000 自动 ×1000) |
"block:identifier" | 自定义模块属性;不带前缀即默认模块 |
务必注意:
- 使用
{value, time}结构时time不能省略。缺省时平台取到的是 0,数据时间会落到 1970 年。 - 数值类型必须与物模型严格匹配(float/double 必须带小数点,int32 必须是整数)。
- 单次上报的属性数量没有强制上限,但建议 ≤ 32 个并控制报文 < 4 KB。
- 平台只把校验通过的属性写入属性记录与规则引擎;未通过的属性逐条写云端日志(
5092identifier 不存在、6308类型不符)。 - payload 不是合法 JSON 时回复
code: 6207;缺少params时回复仍为 200,错误码6208只写云端日志。
回复(sys.ack=1 时下发到 /sys/{pk}/{dn}/thing/event/property/post_reply,QoS1):
{ "id": "1601234567890123456", "code": 200, "method": "thing.event.property.post", "data": {}, "message": "success" }事件上报
Topic:/sys/{pk}/{dn}/thing/event/{identifier}/post(自定义模块:…/thing/event/{block}:{identifier}/post)
{
"id": "evt-20261025-01",
"version": "1.0",
"sys": { "ack": 1 },
"params": {
"value": { "temperature": 85.2, "threshold": 80 },
"time": 1700000000000
},
"method": "thing.event.overTemp.post"
}规则:
identifier取自 Topic,必须已在该产品物模型中定义,否则错误码2009000000(只写云端日志)。params.time支持秒/毫秒;缺失时按服务端当前时间。- 平台把整个
params存入事件记录,并触发事件规则引擎。 - 回复 Topic:
/sys/{pk}/{dn}/thing/event/{block:identifier}/post_reply(QoS1,sys.ack=1时):
{ "id": "evt-20261025-01", "code": 200, "data": {}, "message": "success" }批量属性
property/batch/post与历史属性property/history/post当前未实现(发送后不会入库,且会被当事件处理),请勿使用。
属性设置与回复
平台下发(后台或规则动作)Topic /sys/{pk}/{dn}/thing/service/property/set,QoS0:
{
"id": "123456789012345678",
"timestamp": 1700000000000,
"params": { "Power": "on", "temperature": 26.0 },
"method": "thing.service.property.set"
}设备应回复到 /sys/{pk}/{dn}/thing/service/property/set_reply:
{ "id": "123456789012345678", "messageId": "123456789012345678", "success": true }说明:平台回复处理逻辑读取的是 messageId 与 success,为兼容性请同时回填 id。当前版本平台不等待该回复,后台会直接返回「设置属性下发成功」,因此设备必须自行保证执行与错误上抛(可通过属性回读或事件上报体现结果)。
服务调用
后台调用前会校验设备在线,离线时报 2011000001。
同步调用(RRPC,等待 10 秒)
平台下发 Topic:/ext/rrpc/{messageId}/sys/{pk}/{dn}/thing/service/{identifier}(自定义模块结尾为 {block}:{identifier}),QoS0:
{
"id": "123456789012345678",
"params": { "Power": "on" },
"timestamp": 1700000000000,
"method": "thing.service.setPower"
}设备必须把响应发布回收到消息的同一个 Topic(原样回传),QoS1:
{
"id": "123456789012345678",
"code": 200,
"message": "success",
"params": { "result": "ok" }
}平台以响应中的 params 作为服务输出;10 秒内未收到返回错误 2011000003。设备需在 10 秒内完成处理,长耗时操作请先返回受理结果再用事件上报终态。
兼容方式:平台也识别 /sys/{pk}/{dn}/rrpc/response/{messageId} 形式的回复,但当前实现的下行统一走 /ext/rrpc/…,请优先按上面的方式订阅与回复。
异步调用
平台下发 Topic:/sys/{pk}/{dn}/thing/service/{identifier}(或 {block}:{identifier}),QoS0:
{ "id": "123456789012345678", "params": { "Power": "on" }, "timestamp": 1700000000000 }注意:异步下发报文不含 method 字段,设备不要依赖它。异步调用不等待回复,执行结果请通过属性上报或事件上报反馈。
订阅示例(ESP-IDF C)
/* 同步服务调用:messageId 每次变化,用 + 通配 */
memset(topic_buff, 0, 120);
snprintf(topic_buff, 120, "/ext/rrpc/+/sys/%s/%s/thing/service/+", product_key, device_name);
msg_id = esp_mqtt_client_subscribe(client, topic_buff, 1);收到同步调用报文示例:
TOPIC=/ext/rrpc/344342050114296994/sys/xCgOGN/a0b7658ad450/thing/service/test
DATA={"method":"thing.service.default:test","id":"344342050114296994","params":{"test1":12,"test2":12.7},"timestamp":1766307003582}收到后必须向同一 Topic 回复:
TOPIC=/ext/rrpc/344342050114296994/sys/xCgOGN/a0b7658ad450/thing/service/test
DATA={"id":"344342050114296994","code":200,"data":{}}