智能制造与工业软件 / 系统课时
使用 Sparkplug B 上报设备生死状态
使用 Sparkplug B 上报设备生死状态
普通 MQTT 连接成功不代表平台掌握设备数据是否仍然有效。本篇以 GW01 网关管理 Machine01 设备为例,通过 Sparkplug B 的上线、变化和离线报文,让平台识别网关与设备各自的在线状态,并把失效测点标记为 STALE。
学习目标
- 根据
spBv1.0主题判断消息属于网关还是设备。 - 区分 NBIRTH、DBIRTH、NDATA、DDATA、DDEATH、NDEATH 的触发时机。
- 发出一轮可验证的上下线消息,并正确处理设备失联与网关断线。
主题命名与生死报文
Sparkplug B 在 MQTT 之上规定主题层级、Protobuf 载荷以及设备生命周期。普通 MQTT 消费者只订阅数据值可能误把断线前的温度当成实时值;Sparkplug Host 则通过 BIRTH 建立指标清单,通过 DEATH 将关联值标为 STALE(过期质量)。
网关主题是 spBv1.0/FactoryA/NBIRTH/GW01,设备主题是 spBv1.0/FactoryA/DBIRTH/GW01/Machine01。依次对应命名空间、组 ID、消息类型、边缘节点 ID,设备消息末尾再增加设备 ID;相同的 Machine01 可以位于不同网关下。
| 消息 | 发送方与作用 | 本例主题中的消息类型 |
|---|---|---|
| NBIRTH | 网关上线,声明节点所有指标及当前值 | NBIRTH |
| DBIRTH | 网关代设备上线,声明设备所有指标及当前值 | DBIRTH |
| NDATA / DDATA | 节点 / 设备指标变化时上报增量 | NDATA / DDATA |
| DDEATH | 网关仍在线,但下挂设备数据不再可信 | DDEATH |
| NDEATH | 网关会话结束;网关及下挂设备均离线 | NDEATH |
会话顺序与序号规则
在一次 MQTT 会话中,网关先注册 NDEATH 遗嘱(Will),再连接 Broker、订阅 NCMD,随后发出 NBIRTH 和 DBIRTH。传感器变化时发 DDATA;设备轮询失败时发 DDEATH。网关主动关闭连接前必须自己发布 NDEATH,不能只发送 MQTT DISCONNECT,因为正常 DISCONNECT 不会触发遗嘱。

序列号 seq 在同一网关会话里跨 NBIRTH、DBIRTH、NDATA、DDATA、DDEATH 递增,取值为 0~255,超过 255 回到 0;本例依次为 0、1、2、3。NDEATH 不带 seq,只带 bdSeq 指标,以匹配当前会话的 NBIRTH。bdSeq 在每次新的 MQTT CONNECT 时递增,重连不能永远复用 0。
构建并发送最小序列
准备 Python 3.10+ 和本地测试 MQTT Broker(本例监听 127.0.0.1:1883)。使用 Paho MQTT 2.x 与 Eclipse Tahu 的 sparkplug_b.proto,由 Protobuf 编码生成二进制载荷,不能把下面的指标对象直接以 JSON 发布到 Sparkplug 主题。
python -m pip install "paho-mqtt>=2,<3" protobuf grpcio-tools
curl -fL -o sparkplug_b.proto https://raw.githubusercontent.com/eclipse-tahu/tahu/master/sparkplug_b/sparkplug_b.proto
python -m grpc_tools.protoc -I. --python_out=. sparkplug_b.proto预期结果:当前目录生成 sparkplug_b_pb2.py,命令正常结束,无额外输出要求。把下方完整程序保存为同目录的 demo.py。bdSeq=0 只适用于首次实验连接;实际系统要将它持久化,并在每次新连接时递增。
import time
from threading import Event
import paho.mqtt.client as mqtt
from sparkplug_b_pb2 import Payload
GROUP, NODE, DEVICE = "FactoryA", "GW01", "Machine01"
BD_SEQ = 0 # 首次会话示例;生产中每次 CONNECT 均需递增并持久化
ready = Event()
def pack(seq=None, metrics=()):
p = Payload()
if seq is not None:
p.timestamp = int(time.time() * 1000)
p.seq = seq
p.metrics.extend(metrics)
return p.SerializeToString()
bd = Payload.Metric(name="bdSeq", datatype=4, long_value=BD_SEQ)
rebirth = Payload.Metric(name="Node Control/Rebirth", datatype=11, boolean_value=False)
temp0 = Payload.Metric(name="Temperature", datatype=9, float_value=23.5)
running = Payload.Metric(name="Running", datatype=11, boolean_value=True)
temp1 = Payload.Metric(name="Temperature", datatype=9, float_value=24.0)
ndeath = pack(metrics=[bd])
def on_connect(client, userdata, flags, reason_code, properties):
if reason_code == 0:
client.subscribe(f"spBv1.0/{GROUP}/NCMD/{NODE}", qos=1)
def on_subscribe(client, userdata, mid, reason_codes, properties):
ready.set()
client = mqtt.Client(
mqtt.CallbackAPIVersion.VERSION2, client_id="gw01-demo",
protocol=mqtt.MQTTv311, clean_session=True
)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.will_set(f"spBv1.0/{GROUP}/NDEATH/{NODE}", ndeath, qos=1, retain=False)
client.connect("127.0.0.1", 1883, keepalive=15)
client.loop_start()
if not ready.wait(5):
client.loop_stop()
raise RuntimeError("NCMD 订阅未完成")
def publish(kind, seq, metrics=()):
topic = f"spBv1.0/{GROUP}/{kind}/{NODE}"
if kind.startswith("D"):
topic += f"/{DEVICE}"
client.publish(topic, pack(seq, metrics), qos=0, retain=False).wait_for_publish()
print(f"{kind} seq={seq}")
try:
publish("NBIRTH", 0, [bd, rebirth])
publish("DBIRTH", 1, [temp0, running])
publish("DDATA", 2, [temp1])
# 设备失联而网关仍在线,只发 DDEATH
publish("DDEATH", 3)
# 主动下线要先发 NDEATH;异常断线则由 Broker 发遗嘱
client.publish(
f"spBv1.0/{GROUP}/NDEATH/{NODE}", ndeath, qos=1, retain=False
).wait_for_publish()
print("NDEATH bdSeq=0")
finally:
client.disconnect()
client.loop_stop()在终端运行:
python demo.py预期输出:
NBIRTH seq=0
DBIRTH seq=1
DDATA seq=2
DDEATH seq=3
NDEATH bdSeq=0示例先把温度 23.5 与运行位 true 放进 DBIRTH,再仅通过 DDATA 更新温度到 24.0。设备失联由 DDEATH 表示,最后主动让网关离线。程序通过 wait_for_publish() 等待消息交给 MQTT 客户端网络层,但 QoS 0 不保证 Broker 最终收到;以上输出是程序发送顺序,不是 Host 确认记录。
在订阅端验证与处理边界
在启动 demo.py 之前,另开终端执行以下命令;要求安装 Mosquitto 客户端工具 mosquitto_sub:
mosquitto_sub -h 127.0.0.1 -p 1883 -t 'spBv1.0/FactoryA/#' -F '%t'Broker 正常且订阅先建立时,预期按顺序看到主题:
spBv1.0/FactoryA/NBIRTH/GW01
spBv1.0/FactoryA/DBIRTH/GW01/Machine01
spBv1.0/FactoryA/DDATA/GW01/Machine01
spBv1.0/FactoryA/DDEATH/GW01/Machine01
spBv1.0/FactoryA/NDEATH/GW01mosquitto_sub -F '%t' 只验证主题出现;需要核对 seq、bdSeq、指标类型和值时,应由 Sparkplug Host 或用 sparkplug_b_pb2.Payload.FromString() 解码二进制。验收时还要检查下面两种状态变化:
- 收到 DDEATH:仅
Machine01离线,温度及运行位均标为 STALE,GW01仍在线;设备恢复须重新发 DBIRTH。 - 收到 NDEATH:
GW01及其全部下挂设备离线,原指标均标为 STALE;恢复后以新的bdSeq开始 NBIRTH、DBIRTH 序列。
只有在 Host 同时核对生命周期报文和指标质量时,断线前的最后一个温度值才不会被误当作仍然有效的实时读数。