Sparkplug Data

Every message the node publishes or receives sits under the Sparkplug B namespace, built from your Group ID, the message type, and your Node ID:

For GROUP_ID=Plant1 and NODE_ID=Line1, a device named press_002 publishes on spBv1.0/Plant1/DDATA/Line1/press_002. The device segment is the DeviceHub device name, or the Digital Twin instance's Sparkplug device ID; node-level messages have no device segment.

NDEATH is registered as the MQTT Will Message when the node connects, at QoS 1 and not retained, so the broker publishes it if the node disappears without warning — that is what makes an unplugged device visible to host applications. On a clean shutdown the node publishes NDEATH itself, so the message arrives once either way.

Host applications reject data for a node they have not seen born, so ordering is strict:

The node holds its publish lock until the broker acknowledges each birth message, so no data message can overtake the birth set. Nothing is published at all while the birth set is being rebuilt.

Two counters appear in payloads, and host applications check both.

seq orders messages within one session. NBIRTH carries 0, each following data or birth message increments by one, and the value wraps to 0 after 255. NDEATH carries no seq at all. The node consumes a sequence number only for a message it actually sends — a tag update that produces no publishable metric does not advance the counter, which is what keeps host applications from reporting a gap.

bdSeq identifies the session itself. The NBIRTH that opens a session and the NDEATH that closes it carry the same value, and the next session uses the next value, wrapping after 255. It is stored at <CONFIG_PATH>/seqNum/<group>-<node>_bdSeq.txt, which must survive restarts — see Deployment. A rebirth requested over NCMD reuses the current bdSeq, because the MQTT session has not changed.

Birth messages declare every metric with a name, a numeric alias, and a datatype. Data messages then carry only the alias and the value, omitting names and datatypes entirely; a null value is sent as the alias with the null flag set.

Aliases come from stable identities — the device and tag IDs for DeviceHub, the device and metric key for Digital Twins — so a metric keeps its alias across a rebirth, and a host application can keep resolving in-flight data after a topology change. They are assigned per process, so a restarted node reassigns them and host applications must re-read them from each new NBIRTH rather than caching them across sessions.

Each DeviceHub device becomes one Sparkplug device, and each of its tags becomes one metric on that device. The node reads device and tag metadata from the Litmus Edge API to build birth certificates, then publishes values as they arrive.

The Sparkplug device ID is the DeviceHub device name, trimmed of surrounding whitespace; a device with no name falls back to its Litmus Edge device ID. That name is the last segment of the device's topics, so renaming a device in DeviceHub changes its topic and host applications see a new device.

Tag metrics keep the tag name as configured in DeviceHub, so a tag named Bearing Temp publishes as Tags/Bearing Temp. Tag metadata entries defined in DeviceHub travel with the metric as properties, named metadata_<key> with non-alphanumeric characters in the key replaced by _.

Litmus Edge tag types map to Sparkplug datatypes as follows. Matching is case-insensitive.

A tag whose Count property is greater than 1 publishes as the matching array type instead: BooleanArray, UInt32Array, UInt64Array, FloatArray, DoubleArray, or StringArray.

A tag with a value type the node does not recognize is left out of the birth certificate, so it never appears in the host application. A tag whose name contains no alphanumeric characters, or is not valid UTF-8, is also skipped, with an error logged naming the tag.

Tag updates arrive from the Litmus Edge NATS broker and publish as DDATA on the device's topic, carrying the alias declared at birth and the value. Each update publishes as it arrives; the node adds no batching delay of its own. The metric timestamp is the event time supplied by Litmus Edge, so history in your host application reflects when the value was read rather than when it was published.

The node also subscribes to Litmus Edge lifecycle events:

Paired events are de-duplicated, so a device that reports both disabled and disconnected produces one DDEATH. Litmus Edge sometimes emits an event before the API reflects the change, so the node re-checks shortly afterwards, comparing the new topology against the old one and publishing nothing when nothing changed.

Host applications do not reliably retire a metric that simply disappears from a later birth certificate. So when a tag set shrinks, the node publishes DDEATH for the affected device first, then a fresh NBIRTH and DBIRTH with the current tags, and no data for that device in between. The result is a brief gap rather than a stale tag that keeps reporting good quality.

Each enabled Digital Twin instance becomes one Sparkplug device, and each of its dynamic attributes becomes one metric. Unlike a DeviceHub tag, a twin attribute has no inherent datatype, so the node decides every metric's datatype from the twin's model before any value flows — and never changes it because of a runtime sample.

The birth certificate declares the metric names, aliases, and datatypes; runtime payloads then supply values for metrics that already exist. A field that appears in a payload but not in the contract is ignored, which keeps a host application's tag list stable.

An instance is published only when it is enabled and has a topic. One whose contract compiles to no metrics at all is skipped, and counted by le_sparkplug_digital_twin_quarantine_total.

A twin's Sparkplug device ID is namespaced separately from DeviceHub device names, so a twin and a device can share a display name without colliding.

Four sources are tried in order. The first that yields a scalar type wins, and the winner is recorded on the metric as the typeSource property.

untyped is the honest "not stated anywhere" result rather than a guess: values serialize as text, nothing is dropped, and no datatype is inferred from a name or a unit.

Birth metrics carry flat, scalar properties so an operator can tell where a metric came from without server-side lookups. Reading declaredDataType=json together with typeSource=untyped, for instance, names exactly which field to fix in the model.

Compatible shapes are coerced rather than rejected: "true", 0, and 1 all satisfy a Boolean, and "12.5" satisfies a Double. A value that cannot convert is dropped rather than sent, because a mismatched datatype makes a host application reject the whole payload. Drops are counted by le_sparkplug_digital_twin_attribute_value_mismatch_total, labelled with what was expected and what arrived.

Metric timestamps use the value's own timestamp when the payload carries one, then the payload's top-level timestamp, then publish time.

The node polls Litmus Edge for twin changes every 10 seconds, stretching to 60 seconds while nothing changes and returning to 10 seconds as soon as something does. Instance lifecycle events trigger a refresh immediately.

When a contract changes — an attribute added, removed, retyped, or moved — the node publishes DDEATH for that device and then a fresh birth certificate, so the host application rebuilds its tag list instead of holding a stale one. A change in values alone publishes data only.

The node subscribes for commands on every connect, at QoS 1: spBv1.0/{group}/NCMD/{node} for the node, and spBv1.0/{group}/DCMD/{node}/# for any of its devices. It accepts three command metrics, each taking effect when its boolean value is true.

Every NBIRTH declares the two node commands, and every DBIRTH declares the device command, so a host application discovers them from the birth set. A command metric may be addressed by name or by the alias declared at birth.

Rebirth is how a host application recovers when it has lost track of the node's metrics, after its own restart or an alias it cannot resolve. The node refreshes DeviceHub and Digital Twin metadata first, then publishes the birth set as one unit, with data publishing closed for that window so nothing arrives referencing aliases the host has not read yet. The session's bdSeq does not change, because the MQTT session has not changed. Overlapping requests are suppressed rather than queued: while a birth set is publishing, further requests are counted by le_sparkplug_rebirth_suppressed_total{reason="active"} and dropped, so a host application requesting rebirths in a tight loop cannot stall the node.

Next Server moves the node to the next broker in MQTT_SERVERS: it publishes NDEATH, disconnects, and connects to the next entry, starting a new session with the next bdSeq. With a single broker configured, it reconnects to that same broker.

Any other command metric is ignored and counted by le_sparkplug_ncmd_total{type="unknown"}, with the metric name and value logged at debug level. A malformed metric — no name and no alias — is logged as an error and skipped. Because commands are counted as they arrive, those counters show whether the node received a command a host application believes it sent.

Signed 8-bit and 16-bit integers publish as `Float`, and `int32`, `int64`, and `dint` publish as `Double`. If your host application expects integer datatypes for those tags, expect floating-point metrics instead.A wave of `untyped` metrics on a new instance means its attributes carry no type signal. Fix it in the model editor: bind the attribute to a DeviceHub tag, or set its `dataType` to a real scalar. `le_sparkplug_digital_twin_attribute_fallback_total` counts these per attribute.Writing values back to devices is not supported. `DCMD` handles `Device Control/Rebirth` only — there is no path from a Sparkplug command to a DeviceHub tag write.