Sparkplug B Node

There are node sets such as node-red-contrib-sparkplug-b or node-red-contrib-mqtt-sparkplug-plus. They operate on the same MQTT broker but automatically handle the Sparkplug B specification (spBv1.0/... topic + protobuf payload + birth/death sequence).

The gateway already implements Sparkplug B transmission as its own component (see advanced/sparkplug), but this is used when you need to create reception/monitoring or simulate an external device in Node-RED.

Broker connection info for 2026.05+ boxes

• Broker: 127.0.0.1:1883 (HiveMQ, in the same container)
• Username / Password: app.properties / mqtt.server.user of mqtt.server.password — For production boxes, install.sh generates a random one per box (check /etc/kopens/credentials.txt). The HiveMQ auth.properties entrypoint automatically syncs with app.properties on every boot.
• Group ID / Edge Node ID: If left blank, edge.site_id / edge.id are used automatically (e.g., SITE_00001 / EDGE_00303)
• Sparkplug 3.0.0 spec compatible (NBIRTH seq=0, DDEATH/NDEATH bdSeq, Properties, alias option)

---

1. Core Concepts

Term	Meaning
Group ID	A grouping (e.g., Plant1)
Edge Node ID	Identifier for a single gateway/device
Device ID	Individual equipment under that — optional
Metric	Corresponds to one tag (a Sparkplug metric)
Birth (NBIRTH/DBIRTH)	A node/device publishes its “full definition” of all metrics at once — subscribers synchronize immediately
Data (NDATA/DDATA)	Normal value changes — only changed metrics (delta)
Death (NDEATH/DDEATH)	A message registered as an LWT to announce it is alive — automatically published when connection is lost

---

2. Basic Publish Flow (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 (or mqtt-sparkplug device) settings:

Item	Value (example)
Group ID	Plant1
Edge Node ID	EDGE_00303
Device ID	(Optional — publish directly at the Edge level)
Broker	(Reuse the broker created above MQTT as-is)

Birth/Death are handled automatically by the node — NBIRTH is published at Deploy time, and NDEATH is published via LWT when the node stops or crashes.

---

3. Receive Flow (Cloud / Monitoring → Monitor Edge Nodes)

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

A single sparkplug client in node subscribes to the entire spBv1.0/Plant1/... topic and automatically parses message types (NBIRTH/NDATA/NDEATH/DBIRTH/...) and organizes them into msg.command / msg.payload.metrics.

Branch example (switch):

Condition	Handling
msg.command === 'NBIRTH'	DB synchronization of device metadata — update metric catalog
msg.command === 'NDATA'	Store time series data in InfluxDB / Cassandra, etc.
msg.command === 'NDEATH'	Alarm — “EDGE_00303 disconnected”

---

4. Cautions When Using Sparkplug

• Metric names must match between BIRTH and DATA (if a name changes, it starts from the next BIRTH).
• If multiple clients publish with the same Group/Edge Node ID simultaneously, the seq number collides and messages are treated as Stale — make Edge IDs unique per gateway.
• When the Cloud side sends Rebirth Request, NBIRTH must be re-published — the library handles this automatically, but if you build it yourself, you need to implement it.

---

5. Next Steps

• IIoT Example — Sparkplug B Transmission
• Gateway's own Sparkplug component: Sparkplug B (Advanced)