设备MQTT接入协议¶
主题概览¶
以下主题用于设备与云端通讯：
| 消息类型 | 主题 | 发布/订阅 |
|---|---|---|
| 设备上报属性 | attributes/{username} | 设备发布 |
| 设备上报属性的响应 | attributes_response/{username} | 设备订阅 |
| 设备获取云端属性 | attributes_get/{username} | 设备发布 |
| 设备获取云端属性的响应 | attributes_get_response/{username} | 设备订阅 |
| 云端下发属性至设备 | attributes_push/{username} | 设备订阅 |
| 设备上报事件 | event_report/{username} | 设备发布 |
| 设备上报事件的响应 | event_response/{username} | 设备订阅 |
| 云端下发命令至设备 | command_send/{username} | 设备订阅 |
| 云端下发命令至设备的响应 | command_reply/{username} | 设备发布 |
| 设备上报自定义数据 | data/{username}/{identifier} | 设备发布 |
| 云端下发自定义数据至设备 | data_set/{username}/{identifier} | 设备订阅 |
💡 提示
以上自定义数据相关主题中的
identifier，是指自定义数据流标识符。
各主题的使用方法¶
下面我们逐个介绍各个主题的使用方法。
设备上报属性¶
设备上报属性使用如下主题：
attributes/{username}
一个简单的属性上报消息如下：
设备发布以上消息后，控制台的设备详情页会实时更新显示设备属性的最新值。
设备上报属性的响应¶
如果我们想知道属性上报是否被云平台成功接受，设备可以订阅如下主题：
attributes_response/{username}
当设备上报属性后，便会通过该主题收到来自云平台的响应消息，如果云平台接收成功，响应消息如下：
如果云平台未成功接收，响应消息中会包含错误原因，例如：
{
"error_code": -1,
"error_msg": "Device message frequency too fast, please wait for a moment",
"ts": 1750234507181
}
该错误表示属性上报间隔太短，所以云平台会自动忽略过于频繁的属性上报消息。
⚠️ 注意
此响应消息默认
不开启，需要时可在此处开启：设备类型详情页 >设置>云端响应。
设备获取云端属性¶
当设备希望从云平台获取属性当前值时，发送消息到如下主题：
attributes_get/{username}
消息内容格式如下：
这表示获取所有属性，也可以指定个别属性，如下：
设备获取云端属性的响应¶
请确保设备已经订阅了如下主题：
attributes_get_response/{username}
当设备发送获取属性的消息后，便会通过以上订阅主题，收到如下的响应消息：
云端下发属性至设备¶
除了设备主动获取属性以外，我们也需要让设备可以实时接收云平台下发的属性。
确保设备已订阅如下主题：
attributes_push/{username}
当云平台下发属性给设备时，设备会通过以上订阅主题，收到 JSON 结构的消息，例如：
这个示例消息显然是通知设备关闭某个开关，设备通过自身的程序实现该功能后，可以接着向云平台上报属性或上报事件，让云平台得到确认。
设备上报事件¶
通过事件，设备可以向云端报告消息，而不需要上报任何属性。
一个事件由如下内容组成：
- 事件名称
可以理解为函数名，是事件的唯一表示。
- 事件参数
可以理解为函数的参数，是 JSON 格式的结构体，包含若干参数。
设备可以随时向云平台上报事件，只需将事件消息发布到如下主题：
event_report/{username}
发布的事件消息格式如下：
例如，工厂生产线上的 AI 视觉传感器捕捉到产品数量后，上报事件给云平台，那么消息可能是这样的：
{
"method": "productFound",
"params": {
"count": 3,
"location": "REGION.B43",
"tags": "RED",
"detail": ["100474", "100475", "100342"]
}
}
设备上报事件的响应¶
如果我们想知道事件上报是否被云平台成功接收，可以订阅如下主题：
event_response/{username}
当设备上报事件后，便会通过该主题收到来自云平台的响应消息，如果云平台接收成功，响应消息如下：
💡 提示
响应消息中的成功，只代表云平台成功收到了事件上报，并不代表对事件进行业务处理的结果。
云平台收到设备的事件上报后，如何处理事件呢？规则引擎便派上用场了，通过规则引擎，您可以将事件实时推送到第三方，或通过规则引擎的云函数实现告警策略，当然还可以实现对其它设备的联动控制。
⚠️ 注意
此响应消息默认
不开启，需要时可在此处开启：设备类型详情页 >设置>云端响应。
云端下发命令至设备¶
与事件相反，命令是由云平台向设备主动下发的一组消息，用来实时通知设备执行某个特定的功能。
设备在MQTT连接云平台后，确保订阅如下主题：
command_send/{username}
订阅成功后，设备便处于等待接收命令的状态。当云平台下发命令时，设备便会收到命令消息。
命令消息的格式也是基于 JSON 的结构体，如下：
它和事件消息格式非常类似，只是多了一个 id。您可以认为它就是从云平台向设备的一个远程调用（RPC）。
云端下发命令至设备的响应¶
设备回复命令发布的主题如下：
command_reply/{username}
设备收到命令消息后，通过自身的代码逻辑实现特定的功能前，可以回复命令，也可以不回复命令。
云平台会自动接收回复命令，并和下发命令进行匹配，一次下发命令只能接收一次回复命令，它们的匹配正是通过使用一致的id来保证。
设备回复命令消息的格式如下：
它和命令下发的消息内容完全一样。
设备上报自定义数据¶
详情浏览 自定义数据流的 MQTT 主题。
云端下发自定义数据至设备¶
详情浏览 自定义数据流的 MQTT 主题。