Sparkplug B 节点详解

有 node-red-contrib-sparkplug-b 或 node-red-contrib-mqtt-sparkplug-plus 这样的节点集。它们运行在同一个 MQTT 代理之上，但会自动处理 Sparkplug B 规范（spBv1.0/... 主题 + protobuf payload + birth/death 序列）。

网关本身已将 Sparkplug B 发送 实现为独立组件（参见 advanced/sparkplug），但在 Node-RED 中构建 接收/监控 或 模拟外部设备 时可使用这些节点。

2026.05+ 设备盒的 broker 连接信息

• Broker：127.0.0.1:1883（HiveMQ，同一容器内）
• Username / Password：app.properties 的 mqtt.server.user / mqtt.server.password — 量产设备盒由 install.sh 为每台随机生成（可在 /etc/kopens/credentials.txt 中确认）。 HiveMQ auth.properties 由 entrypoint 在每次启动时与 app.properties 自动同步。
• Group ID / Edge Node ID：留空则自动使用 edge.site_id / edge.id（例如：SITE_00001 / EDGE_00303）
• 兼容 Sparkplug 3.0.0 spec（NBIRTH seq=0、DDEATH/NDEATH bdSeq、Properties、alias 选项）

---

1. 核心概念

术语	含义
Group ID	分组（例如：Plant1）
Edge Node ID	单个网关/设备的标识符
Device ID	其下属的单台设备 — 可选
Metric	对应一个标签（Sparkplug 的指标）
Birth（NBIRTH/DBIRTH）	节点/设备一次性 publish 自身指标的“完整定义” — 订阅方可立即同步
Data（NDATA/DDATA）	日常的值变化 — 仅发送变化的指标（delta）
Death（NDEATH/DDEATH）	以 LWT 注册的存活声明消息 — 连接断开时自动发布

---

2. 基本发布流程（Edge → Cloud）

inject (5s) ─▶ 태그값 읽기 ─▶ function (Sparkplug 메트릭 변환) ─▶ sparkplug device out

function：

return {
  payload: {
    metrics: [{
      name:  msg.payload.tag_id,           // "TAG_TEST_00042"
      type:  'Int32',
      value: parseInt(msg.payload.value, 10),
      timestamp: Date.now()
    }]
  }
};

sparkplug device out（或 mqtt-sparkplug device）设置：

项目	值（示例）
Group ID	Plant1
Edge Node ID	EDGE_00303
Device ID	（可省略 — 直接以 Edge 级别 publish）
Broker	（直接复用上面 MQTT 中创建的 broker）

Birth/Death 由节点自动处理 — Deploy 时发布 NBIRTH，节点 stop/crash 时通过 LWT 发布 NDEATH。

---

3. 接收流程（Cloud / 监控 → 监视各 Edge）

sparkplug client in (Group=Plant1) ─▶ switch (msg.topic 으로 분기) ─▶ ...

一个 sparkplug client in 节点订阅整个 spBv1.0/Plant1/... 主题，并自动解析消息类型（NBIRTH/NDATA/NDEATH/DBIRTH/...），整理为 msg.command / msg.payload.metrics。

分支示例（switch）：

条件	处理
msg.command === 'NBIRTH'	设备元数据 DB 同步 — 更新指标目录
msg.command === 'NDATA'	保存时序数据到 InfluxDB / Cassandra 等
msg.command === 'NDEATH'	通知 — “EDGE_00303 断开”

---

4. 使用 Sparkplug 时的注意事项

• 指标名称在 BIRTH 与 DATA 中必须一致（名称变更后，从下一次 BIRTH 开始生效）。
• 若多个客户端同时以相同的 Group/Edge Node ID 发布，seq number 会冲突并被判定为 Stale — Edge ID 必须按网关唯一分配。
• Cloud 侧发送 Rebirth Request 时必须重新发布 NBIRTH — 库会自动处理，但自行实现时需要自己编码。

---

5. 下一步

• IIoT 示例 — Sparkplug B 发送
• 网关自带的 Sparkplug 组件：Sparkplug B（高级）