使用物模型通信
使用物模型通信
设备通过物模型 Topic 与平台进行属性、事件、服务的上下行通信。本文介绍属性上报、属性设置与服务调用的报文格式和操作方法。完整的 Topic 总表与字段说明,请参见Topic 与报文约定。
前提条件
- 已定义物模型。具体操作,请参见为产品定义物模型。
- 已通过 MQTT 客户端连接平台(如使用 MQTT.fx 接入),下文以
{ProductKey}、{DeviceName}代指实际三元组。
报文公共格式
上行报文统一使用如下 JSON 信封:
| 字段 | 说明 |
|---|---|
id | 消息 ID(字符串),平台回复时原样返回,用于请求-响应配对 |
version | 协议版本,固定 1.0 |
sys.ack | 1:平台回复;0:不回复。属性/事件默认 0,日志类默认 1 |
params | 业务数据 |
method | 请求方法,便于排查,平台按 Topic 分发,不参与判定 |
注意
回复中的 code: 200 只表示「平台已收到并可解析 JSON」,不代表每个属性都校验通过。类型不匹配或未在物模型中定义的属性会被过滤,仅写入设备的云端日志。
属性上报
请求 Topic:/sys/{ProductKey}/{DeviceName}/thing/event/property/post
{
"id": "123",
"version": "1.0",
"sys": { "ack": 1 },
"params": {
"Power": { "value": "on", "time": 1524448722000 },
"WF": 23.6
},
"method": "thing.event.property.post"
}params 支持两种写法:
- 简写:
"WF": 23.6,时间由平台按服务端时间填充。 - 携带采样时间:
"Power": {"value": "on", "time": 1524448722000},time为毫秒时间戳(10 位秒级时间戳会自动换算)。使用该写法时time不能省略,否则数据时间会落到 1970 年。
自定义模块属性标识符格式为 {模块标识}:{属性标识},例如 "MCU:fwVersion": "1.0.3"。
回复 Topic:/sys/{ProductKey}/{DeviceName}/thing/event/property/post_reply(sys.ack=1 时下发)
{ "code": 200, "data": {}, "id": "123", "message": "success", "method": "thing.event.property.post", "version": "1.0" }上报后可在控制台设备详情的属性记录与云端日志中查看结果。
事件上报
请求 Topic:/sys/{ProductKey}/{DeviceName}/thing/event/{事件标识符}/post
{
"id": "124",
"version": "1.0",
"sys": { "ack": 1 },
"params": {
"value": { "temperature": 85.2 },
"time": 1700000000000
},
"method": "thing.event.overTemp.post"
}params.value为事件输出参数,params.time为事件发生时间(毫秒),缺失时按服务端时间。- 事件标识符必须已在物模型中定义,否则不会入库(错误码
2009000000,见云端日志)。
回复 Topic:/sys/{ProductKey}/{DeviceName}/thing/event/{事件标识符}/post_reply
属性设置(平台下行)
在控制台设备详情的属性配置中对设备执行 设置,平台向设备下发:
下行 Topic:/sys/{ProductKey}/{DeviceName}/thing/service/property/set(QoS 0)
{
"id": "123456789012345678",
"version": "1.0",
"params": { "temperature": "26.0" },
"method": "thing.service.property.set"
}设备执行后应回复:
回复 Topic:/sys/{ProductKey}/{DeviceName}/thing/service/property/set_reply
{ "id": "123456789012345678", "messageId": "123456789012345678", "success": true }提示
- 平台当前不等待该回复即返回「下发成功」,设置是否真正生效以设备执行后的属性上报为准。
- 下发使用 QoS 0,设备需保证订阅了该 Topic(平台不自动订阅),并按
id做幂等。
服务调用
在控制台设备详情的「远程调用」中执行服务调用。平台调用前会校验设备在线,离线时报 2011000001。
同步调用(RRPC)
平台下发 Topic(messageId 由平台生成,每次不同):
/ext/rrpc/{messageId}/sys/{ProductKey}/{DeviceName}/thing/service/{服务标识符}下发报文:
{ "id": "344342050114296994", "params": { "Power": 1 }, "timestamp": 1766307003582, "method": "thing.service.setPower" }设备必须把响应发布回收到消息的同一个 Topic(原样回传):
{ "id": "344342050114296994", "code": 200, "data": {} }- 平台等待 10 秒,超时未收到回复报
2011000003;回复中的params会作为服务输出返回给调用方。 - 设备订阅时用通配符匹配:
/ext/rrpc/+/sys/{ProductKey}/{DeviceName}/thing/service/+(注意+只匹配一层)。
异步调用
平台下发 Topic:/sys/{ProductKey}/{DeviceName}/thing/service/{服务标识符}(自定义模块为 {模块标识}:{服务标识符})
{ "id": "181658324017416411", "params": {}, "timestamp": 1766324587364 }注意
异步下发报文不含 method 字段,设备不要依赖它。异步调用不等待回复,执行结果请通过属性上报或事件上报反馈。
验收清单
| # | 检查项 | 预期 |
|---|---|---|
| 1 | 属性上报(ack=1) | 收到 post_reply,code: 200,控制台属性记录有值 |
| 2 | 上报未定义的属性 | 属性记录无该键,云端日志出现错误码 5092 / 6308 |
| 3 | 上报类型不符的值(如 double 传整数) | 该属性被过滤,云端日志 6308 |
| 4 | 控制台设置属性 | 客户端收到 property/set,随后上报新值生效 |
| 5 | 同步调用服务 | 控制台显示设备返回的 params;不回复则报 2011000003 |
| 6 | 异步调用服务 | 设备收到无 method 的报文,通过上报反馈结果 |
下一步
需要自由格式的上下行数据时,可使用自定义 Topic,参见使用自定义 Topic 通信。