单片机与物联网 / 系统课时
用保留消息同步最新状态
用保留消息同步最新状态
监控面板通常晚于设备上线。如果设备只在数值变化时上报,面板新建订阅后可能一直显示空白。将最新状态以 RETAIN 发布,Broker 就能保存该 Topic 的最近一次状态,让新订阅者不必等到下一次设备上报。
学习目标
- 说明保留消息的保存、覆盖与新订阅投递规则。
- 使用 Mosquitto 命令验证新订阅者立即收到最新状态。
- 清除过期的保留值,并区分状态快照与一次性业务命令。
保留的是 Topic 的最新一条状态
设备向 factory/line1/device/t01/state 发布 {"temperature":22},并设置 RETAIN=1。Broker 按完整 Topic 名称保存一条最新消息及其 QoS;随后同一 Topic 的新保留消息会替换旧值。普通的 RETAIN=0 发布不会更新或删除已有保留值。
保留消息适合设备温度、工作模式、配置版本等“现在是什么”的数据,不适合开门、扣费、触发一次蜂鸣等“执行一次”的命令。它不是历史队列:一个 Topic 不会因连续上报 22、23、24 而为新订阅者保存三条记录。
新订阅者如何获得状态快照
按时间观察:设备先发布 22 并保留;面板 A 后订阅,会立即收到 22,即使此刻设备没有再次发送。设备再以 RETAIN=1 发布 23,Broker 覆盖快照,并把这次实时消息转发给已订阅的 A;更晚加入的面板 B 则收到保留的 23。

MQTT 3.1.1 新建订阅通常会收到匹配的保留值;MQTT 5 还能用 Retain Handling 控制首次或重复订阅时是否下发。一次主题过滤器匹配多个 Topic 时,Broker 可分别发送这些 Topic 各自的保留值,不是只返回整个过滤器下的一条。
在本地发布并读取保留值
准备一个运行中的本地 Mosquitto Broker,以及可执行的 mosquitto_pub、mosquitto_sub。下例使用 127.0.0.1:1883 和 MQTT 3.1.1;若 Broker 端口不同,把 PORT 改为实际 <PORT>,生产环境还需配置身份认证和 TLS。
PORT=1883
TOPIC='factory/line1/device/t01/state'
# 先发布,再启动一次全新的订阅
mosquitto_pub -h 127.0.0.1 -p "$PORT" -V 311 -t "$TOPIC" -q 1 -r -m '{"temperature":22}'
mosquitto_sub -h 127.0.0.1 -p "$PORT" -V 311 -t "$TOPIC" -q 1 -C 1 -F 'RETAIN=%r %p'
# 新的保留值覆盖旧值,下一位订阅者直接读到23
mosquitto_pub -h 127.0.0.1 -p "$PORT" -V 311 -t "$TOPIC" -q 1 -r -m '{"temperature":23}'
mosquitto_sub -h 127.0.0.1 -p "$PORT" -V 311 -t "$TOPIC" -q 1 -C 1 -F 'RETAIN=%r %p'预期输出:
RETAIN=1 {"temperature":22}
RETAIN=1 {"temperature":23}-r 表示保留发布,-q 1 指定 QoS 1,-C 1 表示接收一条后退出,%r 展示收到消息的保留标志。两次订阅都是发布后才启动,却分别直接读到当前最新值。
删除保留值并防止旧状态误导
若设备下线后不再需要这个状态快照,可向同一 Topic 发送 RETAIN=1 且载荷长度为零的消息:
# 与上段命令在同一Shell中运行,沿用PORT和TOPIC
mosquitto_pub -h 127.0.0.1 -p "$PORT" -V 311 -t "$TOPIC" -q 1 -r -n
mosquitto_sub -h 127.0.0.1 -p "$PORT" -V 311 -t "$TOPIC" -C 1 -W 2预期结果:新的订阅在约 2 秒内没有收到状态正文,随后超时退出;不同客户端版本可能向标准错误输出超时提示。-n 发送零字节载荷,和发送文本 null 或 {} 完全不同。
MQTT 5 还可利用 Message Expiry Interval 让保留值在到期后被 Broker 删除。重要状态可选 QoS 1,但 Broker 重启后是否仍保留,还取决于其持久化配置。验收时应检查新订阅的即时结果、覆盖结果以及过期或清除后的空结果。