How to Map OPC UA Nodes to Sparkplug Metrics

Back to Blog

Enumerate the Nodes and Fix the Metric Set

Sparkplug requires the birth to declare every metric the node will ever report, so the first job is to settle the complete list of OPC UA nodes this Sparkplug edge node will carry. Browse the OPC UA address space and pick the exact nodes, because the birth is a closed contract - you cannot add a metric later in a data message without a fresh birth. Understanding the source structure helps; see the OPC UA address space information model.

This fixed set is the foundation of a correct birth. The birth-then-data discipline it feeds is covered in configuring Sparkplug metric birth certificates. Decide the metric set deliberately, because every consumer downstream builds its model from exactly this list and nothing you leave out will ever appear.

Translate the Data Types Deliberately

OPC UA and Sparkplug both have rich type systems, and the mapping between them must be exact because the Sparkplug consumer decodes every value using the type declared at birth. Translate an OPC UA integer to the corresponding Sparkplug integer metric, a float to a float, a boolean to a boolean. A loose or wrong translation corrupts the value silently, since the consumer trusts the birth type without question.

Watch the edge cases: an OPC UA type that has no exact Sparkplug equivalent must be mapped to the closest type that preserves the value's meaning, decided explicitly rather than by default. Get this wrong and you will see the classic garbage-value symptom downstream, whose cause and cure are the birth type - the same failure discussed in configuring the birth. Pin every mapping in a table you can review.

Carry the OPC UA Quality Into the Metric

OPC UA carries a quality code with every value, and that quality must survive the mapping, or a Sparkplug consumer will treat a stale or bad OPC UA value as trustworthy. Represent the quality in the Sparkplug metric - through the metric's own quality field or a companion metric - so downstream systems can tell good data from bad. Dropping quality at the bridge is a subtle but serious data-integrity fault.

The OPC UA quality model is more detailed than a simple good-or-bad flag, so decide how much of that detail to preserve. The substatus that carries the nuance is in the OPC quality code substatus. At minimum, a value that is bad or uncertain on the OPC UA side must not arrive on the Sparkplug side looking good.

Build the Birth Then Stream the Data

Assemble the birth from the fixed metric set, each metric with its translated type, an alias, and an initial value read from the OPC UA node. Publish that birth when the Sparkplug edge node comes online, before any data. Then, as OPC UA data-change notifications arrive, publish Sparkplug data messages carrying only the changed metrics by alias, with quality attached.

Keep the birth deterministic so a rebirth reproduces the same metric-to-alias mapping every time, which is what lets a late-joining or resynchronizing consumer recover. If the OPC UA subscription is properly deadbanded, the Sparkplug data stream is naturally lean. The reconnection and rebirth handling this enables is discussed in fixing a Sparkplug stale metric after reconnect.

Verify Against a Sparkplug Consumer

Bring the edge node online and watch a Sparkplug consumer build its model from the birth: every mapped OPC UA node should appear as a metric with the correct type and a sensible initial value. Then change a value on the OPC UA server and confirm the consumer decodes the resulting Sparkplug data message correctly by alias, including the quality. This proves the type mapping and quality carry both work.

Force a bad quality on the OPC UA side and confirm it shows as bad on the Sparkplug side, not good - the quality-carry check that a healthy-looking value would hide. And force a rebirth to confirm the mapping is deterministic. A mapping that survives all three checks decodes reliably; one that fails any of them corrupts data in a way that is hard to trace later.

Common Mistakes

The dominant mistake is a data-type mismatch between the OPC UA node and the declared Sparkplug metric, which silently corrupts every value for that metric. The second is a metric missing from the birth that the bridge later tries to publish, which the consumer rejects.

Another is dropping OPC UA quality so bad values arrive looking good - a data-integrity failure that surfaces as bad decisions downstream, not an obvious error. And do not let the birth be non-deterministic; if aliases shift between sessions, every rebirth confuses consumers. Pin the metric-to-alias mapping so it is identical each time the node comes up.

Frequently Asked Questions