智能制造与工业软件 / 系统课时
规划 MQTT 主题与统一消息载荷
规划 MQTT 主题与统一消息载荷
同一工厂往往同时接入 Modbus、OPC UA 和模拟设备。如果主题随意命名、载荷字段各不相同,平台就无法按产线订阅或统一入库。本课为一台设备定义可扩展的 MQTT 主题、遥测 JSON 契约,并用本地发布订阅验证两者是否匹配。
学习目标
- 按工厂、产线、设备、数据类别设计固定层级的 MQTT 主题。
- 统一设备标识、事件时间、点位集合、质量和消息版本字段。
- 使用订阅过滤器与测试消息检查路由及载荷的一致性。
用固定层级组织主题
采用六级主题 iiot/v1/{factoryId}/{lineId}/{deviceId}/{category}。例如 iiot/v1/f01/l02/machine01/telemetry 表示工厂 f01、产线 l02 上的 machine01 正在上传遥测数据。前两级是命名空间与路由契约大版本;设备实际采集协议不进入主题。
末级类别约定为 telemetry(连续测点)、event(离散事件)、status(设备当前状态)。温度、转速等测点名应放进负载的 points,不要为每个测点额外建立主题,否则批量采样会变成大量分散消息。

主题大小写敏感,统一用小写 ASCII、数字和短横线,避免空格、前导斜杠和随意新增层级。+、# 只能写在订阅过滤器中,发布主题不能包含通配符。设备标识应稳定且不包含密钥等敏感信息。
让每条遥测使用同一载荷
将下列内容保存为 UTF-8 文件 telemetry.json。这里把多个测点放在同一次采样记录内,保持数值和布尔类型,不把所有值转换成字符串。
{
"schemaVersion": 1,
"messageId": "machine01-000042",
"deviceId": "machine01",
"eventTime": "2026-10-12T00:00:05.000Z",
"points": {
"temperatureC": {"value": 36.4, "quality": "GOOD"},
"running": {"value": true, "quality": "GOOD"}
}
}schemaVersion 标识 JSON 载荷结构的版本,与主题中的 v1 作用不同;messageId 是设备侧生成的唯一消息标识,供下游去重。eventTime 使用带 Z 的 UTC ISO 8601 时间,表达现场采样时刻而非入库时刻;上面的时间和标识仅为示例,实际发送时需更新。
每个点位统一为 value 和 quality,约定质量枚举 GOOD、UNCERTAIN、BAD;temperatureC 的单位在点位字典中固定为摄氏度,不能在不同设备上同名异义。上报前至少检查 deviceId 与主题第五级一致、时间可解析、schemaVersion 被支持、每个点位的数据类型符合点位字典。单点坏质量不应直接伪装成正常值。
用订阅过滤器控制消费范围
订阅 iiot/v1/f01/l02/+/telemetry 可以接收该产线所有设备的遥测,+ 只匹配一个层级;订阅 iiot/v1/f01/# 则覆盖该工厂后续所有层级。生产平台优先使用限定产线与类别的过滤器,避免过宽的 # 让消费端处理无关数据。
连续遥测通常按需求选 QoS 0 或 QoS 1;关键事件可用 QoS 1,但它允许重复投递,消费端应根据 messageId 去重。status 当前状态可按业务需要使用 retained 消息,历史遥测和一次性事件通常不要 retained。代理 ACL 还应限制每台网关只能发布其获授权的设备主题。
在本地验证主题和负载
前置条件是本机已有可连接的 MQTT 测试 Broker,监听 127.0.0.1:1883,并安装 Mosquitto 命令行客户端。此端口是实验取值,实际主机、端口及认证参数以环境配置为准;生产环境应启用认证与 TLS。先在终端 A 执行订阅:
# 只接收一条匹配的遥测,-v 同时打印主题
mosquitto_sub -h 127.0.0.1 -p 1883 -q 1 -t 'iiot/v1/f01/l02/+/telemetry' -C 1 -v预期结果:终端 A 等待符合过滤器的消息,收到一条后自动退出。保持其运行,再在存放 telemetry.json 的目录打开终端 B:
# 从文件读取 JSON 作为原始 MQTT 负载发布
mosquitto_pub -h 127.0.0.1 -p 1883 -q 1 -t 'iiot/v1/f01/l02/machine01/telemetry' -f telemetry.json预期输出(终端 A,主题前缀后紧跟文件中的 JSON):
iiot/v1/f01/l02/machine01/telemetry {
"schemaVersion": 1,
"messageId": "machine01-000042",
"deviceId": "machine01",
"eventTime": "2026-10-12T00:00:05.000Z",
"points": {
"temperatureC": {"value": 36.4, "quality": "GOOD"},
"running": {"value": true, "quality": "GOOD"}
}
}将订阅过滤器末级改为 event 后重试,应该收不到这条 telemetry 消息;测试时可用 Ctrl+C 结束等待。如果收不到预期消息,依次检查 Broker 连接、订阅是否先启动、主题层级大小写以及 ACL。联调验收以“主题能准确筛选、载荷能按约定解析、设备标识一致”为准。