Sparkplug Gateway Qualification: Test Birth and Data as One Edge-Node Ledger

A two-device Sparkplug gateway can pass each device’s isolated test while failing when both publish together. Independent device adapters may reuse sequence values or metric aliases that belong to one edge-node-wide contract. Qualify the assembled publisher with a shared ledger before accepting a convincing dashboard demonstration.

This article follows Eclipse Sparkplug 3.0.0. An original Python 3.12.14 checker exercised eleven cases over simplified publisher records. It checks selected ordering, alias and connection relationships only. It does not encode Protobuf, connect to MQTT, implement a host or replace the official compatibility test kit.

Define the qualification boundary

Use one inert gateway fixture with a fixed startup inventory: devices A and B are both available when the edge establishes its session. Capture the edge’s outgoing publication order before broker transport.

Retain the configured group and edge identity, device inventory, gateway build, serializer version and relevant MQTT connection record. Decode the publication payload without discarding the original bytes. The evidence should identify the owner of each definition and subsequent value.

Keep subscriber-arrival order separate. A publisher-order checker is not a host message-reordering algorithm. Feeding incomplete subscriber traces directly into this checker could wrongly blame the gateway for a capture gap or transport observation problem.

Use an edge-wide sequence ledger

The Sparkplug 3.0.0 specification contains inconsistent NBIRTH wording: sections 4.2.1 and 12.13 require sequence zero, while 6.4.19 gives a zero-to-255 range. This fixture uses zero to satisfy the stricter clause. Subsequent sequenced edge messages increment across device boundaries and wrap from 255 to zero; the startup births precede data.

Begin the synthetic trace with NBIRTH zero, DBIRTH for A at one and DBIRTH for B at two. Publish NDATA at every sequence from three through 254, then DDATA for A at 255 and DDATA for B at zero. The executable fixture retains every intermediate record; the diagram abbreviates them.

A device-local counter would fail this scenario even if it increased perfectly within each device’s topic. The qualification owner should therefore review where sequence allocation occurs in the assembled gateway and whether concurrent adapters share that allocation safely.

Original synthetic publisher-ledger diagram. Selected logical checks were executed; no MQTT or equipment trace is shown.

Review aliases across the assembled inventory

Section 6.4.6 defines alias uniqueness across the edge node’s entire metric set. When using aliases, birth definitions associate names with aliases, while data messages use the established alias form. Reserved control metrics need their own applicable rules; this fixture covers ordinary measurement and diagnostic metrics.

Assign alias one to an edge diagnostic, two to A’s temperature and three to B’s pressure. Build a registry containing alias, owner identity and metric name. Reviewing only a device’s own dictionary would miss A and B accidentally choosing the same number.

For every decoded data metric, resolve its alias through that registry and verify the intended owner. A valid alias pointing at another device can attach a plausible value to the wrong machine.

Store the registry beside its birth trace so the mapping remains independently reviewable.

Keep the connection relationship independent

Sections 5.4 and 5.17 require NBIRTH’s bdSeq to match the preceding CONNECT Will value. A new CONNECT advances that connection value; a same-session rebirth retains it. Payload seq and bdSeq consequently need separate ledger entries.

The synthetic connection uses bdSeq seven while NBIRTH uses seq zero. A later same-session NBIRTH again uses seq zero and retains bdSeq seven. A separate new-CONNECT check expects bdSeq eight after seven. The distinct fields expose accidental reuse of one variable for both responsibilities.

The rebirth check starts at the new NBIRTH. It does not simulate delivery of a rebirth command, stopping in-flight data publication or the host’s reconstruction behavior. Those remain integration-test obligations.

Use negative cases to test the checker

The eleven executed cases include three accepted paths: the two-device rollover trace, a new birth sequence within the existing connection and an incremented connection value. Eight negative cases reject a nonzero NBIRTH under the conservative profile, a repeated device-local sequence, a cross-device alias collision, data before the fixed birth inventory completes, a birth/Will mismatch, rollover that skips zero, an alias targeting another device and reuse of the old value on a new CONNECT.

The checker consumes normalized selected fields. Required timestamps, datatypes, reserved metrics and binary serialization are deliberately outside its input model. Passing it means those selected invariants held for the supplied records, not that the record was a complete conforming Sparkplug payload.

Keep each deliberate mutation isolated. If one malformed record contains several faults, the first rejection cannot demonstrate that every relevant check works. Save the fixture input, expected rule and observed result so future refactoring can rerun the same acceptance logic.

Complete the product-level evidence

Next, run the selected official TCK and the real publisher/host combination with the project’s supported profiles. The Eclipse TCK guidance distinguishes test execution and approved product-listing requirements. This article’s local checker supplies neither a listing nor permission to claim compatibility.

For release, connect the actual encoded birth/data trace to the shared ledger, verify supported disconnect and reconnect behavior, and inspect the consumer’s metric identities and quality transitions. Keep templates, historical replay and Primary Host failover as separate declared coverage areas rather than assuming this fixture exercises them.

The useful handover is one gateway-level evidence package: fixed inventory, connection relationship, publication sequence, alias registry, negative-test results and explicit coverage limits. That package can reveal integration defects that two successful single-device demonstrations leave hidden.