Using Sparkplug B Nodes in Depth

There is a node set such as node-red-contrib-sparkplug-b or node-red-contrib-mqtt-sparkplug-plus. It runs on the same MQTT broker but automatically handles the Sparkplug B spec (spBv1.0/... topic + protobuf payload + birth/death sequence).

The gateway already implements Sparkplug B publishing as its own component (see advanced/sparkplug), but you use these nodes when building reception/monitoring in Node-RED or emulating an external device.

Broker connection details for 2026.05+ boxes

• Broker: 127.0.0.1:1883 (HiveMQ, inside the same container)
• Username / Password: mqtt.server.user / mqtt.server.password in app.properties — on production boxes, install.sh generates these randomly per box (check in /etc/kopens/credentials.txt). HiveMQ auth.properties is automatically synced with app.properties by the entrypoint on every boot.
• Group ID / Edge Node ID: leave blank to use edge.site_id / edge.id automatically (e.g. SITE_00001 / EDGE_00303)
• Sparkplug 3.0.0 spec compliant (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 of a single gateway/device
Device ID	An individual piece of equipment under it — optional
Metric	Corresponds to one tag (a Sparkplug metric)
Birth (NBIRTH/DBIRTH)	The node/device publishes the “full definition” of its metrics at once — subscribers sync immediately
Data (NDATA/DDATA)	Ordinary value changes — only the changed metrics (delta)
Death (NDEATH/DDEATH)	The message registered as an LWT to indicate liveness — published automatically when the connection drops

---

2. Basic Publishing 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	(can be omitted — publish directly at the Edge level)
Broker	(reuse the broker created in MQTT above as-is)

Birth/Death are handled by the node itself — NBIRTH is published at Deploy time, and if the node stops or crashes, NDEATH is published as the LWT.

---

3. Reception Flow (Cloud / Monitoring → Monitoring the Edges)

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 the message type (NBIRTH/NDATA/NDEATH/DBIRTH/...), organizing it into msg.command / msg.payload.metrics.

Branching example (switch):

Condition	Handling
msg.command === 'NBIRTH'	Sync device metadata to the DB — update the metric catalog
msg.command === 'NDATA'	Store the time series in InfluxDB / Cassandra, etc.
msg.command === 'NDEATH'	Notification — “EDGE_00303 disconnected”

---

4. Cautions When Using Sparkplug

• Metric names must match between BIRTH and DATA (if a name changes, it takes effect from the next BIRTH).
• If multiple clients publish simultaneously under the same Group/Edge Node ID, the seq number collides and the data is treated as Stale — keep Edge IDs unique per gateway.
• When the cloud side sends Rebirth Request, NBIRTH must be published again — the library handles this automatically, but you must implement it yourself if you build it manually.

---

5. Next Steps

• IIoT Examples — Publishing with Sparkplug B
• The gateway's own Sparkplug component: Sparkplug B (Advanced)