IMD SolutionComputing LibraryShop main store

How-to

How Sparkplug UDT definitions reach MQTT Engine

Edge computing and IIoT Published 7 min read

Short answer

A UDT definition is not a file you import: it is a Template metric with isDefinition true published in the NBIRTH, and each DBIRTH instance binds to it by an exact-name templateRef. Build the births in Node-RED or on the Eclipse Tahu Node.js client, then verify the definition and the instance in the MQTT Engine tag provider.

On this page
  1. What Engine turns into a UDT definition
  2. Choose the client that builds the births
  3. Publish the definitions in the NBIRTH
  4. Bind the instances in the DBIRTH
  5. Sizing the births for Template1 with two members
  6. Verify the definition and the instance
  7. When the UDT still does not appear
  8. Questions asked

MQTT Engine never imports a UDT definition from a file, a script, or a JSON schema. It builds one from the edge node's own Sparkplug B births: a metric of datatype Template with isDefinition: true in the NBIRTH becomes a UDT definition, and any later Template metric whose value carries a templateRef equal to that name becomes a UDT instance of it. Publish the definitions from the same client that publishes the data — Node-RED with Sparkplug B nodes, or a Node.js program on the Eclipse Tahu client — and the structure arrives with the values. This walkthrough builds both births, sizes them, and verifies the result in the tag provider.

What Engine turns into a UDT definition #

A birth certificate is the message an edge node or device publishes when it connects, declaring every metric it will send: NBIRTH for the node, DBIRTH for each device, two of the nine Sparkplug B message types. Inside those metric arrays, the Template datatype carries the UDT structure, and one flag selects its role.

Role Key fields Published in What MQTT Engine creates
Definition type: "Template", isDefinition: true, member metrics NBIRTH A UDT definition named after the metric
Instance type: "Template", isDefinition: false, templateRef, member metrics NBIRTH or DBIRTH A UDT instance bound to the named definition

Binding is by name. templateRef must equal the definition metric's name exactly — same case, no leading or trailing spaces — so when an instance will not bind, compare the two strings character by character before touching anything else.

Definitions nest: a member of a definition can itself be a Template metric whose templateRef names another definition, and every definition in the chain must ride the same NBIRTH.

Template is one of the 22 metric datatypes Sparkplug B defines, so definitions travel in the same metric array as the node's Int32 and Float metrics; there is no separate topic or file for them. The broker never decodes any of it — it routes the protobuf bytes untouched, which is why MQTT broker support is not Sparkplug support. The binding happens entirely in the consuming client.

Choose the client that builds the births #

Approach Where the definition lives Control over births Fits when
Node-RED Sparkplug B nodes, metrics passed as objects in msg.payload A function node building the NBIRTH/DBIRTH metric arrays Limited to what the node forwards The edge logic already lives in Node-RED flows
Node.js on the Eclipse Tahu client A script object handed to the client's birth publish calls Full: publish order, rebirth handling, bdSeq Deterministic births, many devices, code under version control
Manual UDT in the SCADA designer with flat edge metrics The SCADA project, not the edge None Avoid it: the definition drifts from the edge and Engine never sees a template

The two client paths put identical protobuf on the wire and the template object layout is the same in both, which makes the Tahu example script at tahu/javascript/examples/simple/example.js the layout reference for either. Use the Tahu client when you control the runtime, because definitions must live in the NBIRTH and that client hands you the birth directly. Use Node-RED when the flow already exists, after one check: confirm the Sparkplug node forwards a Template-typed metric object unchanged. Some nodes accept only scalar datatypes, and a node that flattens or drops the value object will never produce a definition.

Publish the definitions in the NBIRTH #

  1. Put every UDT the node will use into the NBIRTH metric array as a Template metric with isDefinition: true, its members inside value.metrics. Member values act as defaults:
// Illustrative payload object; the field names follow the Tahu client layout
// shown in tahu/javascript/examples/simple/example.js.
const nbirthPayload = {
  timestamp: Date.now(),          // number, milliseconds since epoch
  metrics: [
    {
      name: "Template1",          // string: the UDT definition name Engine will list
      type: "Template",
      value: {
        isDefinition: true,       // boolean: this metric is the definition
        metrics: [
          { name: "Speed",   type: "Float",   value: 0 },     // default values
          { name: "Running", type: "Boolean", value: false }
        ]
      }
    }
  ]
};
  1. Give every member an explicit type. An untyped member either fails to encode or reaches Engine with the wrong datatype.
  2. Publish the NBIRTH before any DBIRTH. An instance whose definition Engine has not received cannot bind.
  3. Answer Engine's rebirth command by republishing the full NBIRTH with all definitions, then every DBIRTH. Metric aliases ride these same births, and a metric that comes back without its alias is the case traced in why the rebirth metric arrives without its Sparkplug alias.
  4. Treat reconnects the same way: after any reconnect or broker change, Engine rebuilds what it knows solely from the births that follow, and that missing republish is why rebirth fails after switching Sparkplug MQTT brokers.

Bind the instances in the DBIRTH #

  1. In each device's DBIRTH, declare instances as Template metrics with templateRef set to the definition name and isDefinition: false:
// Illustrative payload object, same field names as the NBIRTH example.
const dbirthPayload = {
  timestamp: Date.now(),
  metrics: [
    {
      name: "TemplateInstance1",  // string: the instance name under this device
      type: "Template",
      value: {
        templateRef: "Template1", // string: must equal the definition name exactly
        isDefinition: false,
        metrics: [
          { name: "Speed",   type: "Float",   value: 1450.0 },
          { name: "Running", type: "Boolean", value: true }
        ]
      }
    }
  ]
};
  1. Keep the instance's member names and types aligned with the definition; Engine writes instance members by that match.
  2. Update values at runtime with DDATA: publish the instance as a Template metric carrying only the changed members and their new values, then confirm Engine writes them into the existing instance.
  3. Treat structure as birth material. A member added, removed, retyped, or renamed — in the definition or in an instance — goes out as a new NBIRTH and fresh DBIRTHs, never as DDATA.

Sizing the births for Template1 with two members #

Inputs, each with its source:

  • One definition, Template1, with two members — Speed (Float) and Running (Boolean) — the layout used in the payload examples above.
  • One instance, TemplateInstance1, with the same two members and live values 1450.0 and true.
  • Per-metric size in a birth: 40–80 B, derived from published Sparkplug B guidance that a device birth carrying 100 tags runs 4–8 KB, since 4000 B ÷ 100 tags = 40 B per tag and 8000 B ÷ 100 tags = 80 B per tag.

Rule in words: a birth's payload is its metric count times the per-metric size. Count what each birth carries and compare the result against the size at which births start to matter.

Arithmetic:

  • NBIRTH metrics = 1 definition metric + 2 member metrics = 3.
  • DBIRTH metrics = 1 instance metric + 2 member metrics = 3.
  • NBIRTH size = 3 × 40 B = 120 B, up to 3 × 80 B = 240 B.
  • DBIRTH size = 120–240 B by the same product.
  • Whole birth sequence = 240 B + 240 B = 480 B at the top of the range.

Decision: 480 B is under one-eighth of the 4 KB floor of the 100-tag range (4096 B ÷ 8 = 512 B), so publish every definition in the single NBIRTH and do not split births. Splitting enters the question only when one device's tag count approaches 100 — 4–8 KB per birth — and the first number to check then is the broker's maximum payload setting, not the template structure.

Verify the definition and the instance #

This is the test that proves the payloads above; run it once after the first publish.

  1. Subscribe with a Sparkplug-aware MQTT client to the node's NBIRTH topic and decode it: the definition metric must show datatype Template, isDefinition: true, and the two members with their types.
  2. Decode the DBIRTH: the instance metric must carry templateRef equal to Template1, character for character.
  3. In the MQTT Engine tag provider, open the UDT definitions area: Template1 should be listed with Speed as Float and Running as Boolean.
  4. Browse the Edge Nodes hierarchy — group, edge node, device: the instance must appear as a UDT instance of Template1, not as a folder of atomic tags.
  5. Flip one member at the edge (Running to false) and publish the DDATA: the matching member inside the instance updates. If steps 1–2 pass and step 4 fails, the problem is on the Engine side, not in the payload.

When the UDT still does not appear #

  1. Flat folders, no definition anywhere: the birth never carried a Template metric, or the Node-RED node flattened it. Decode the NBIRTH and inspect the metric datatype.
  2. Definition exists, instance shows as a plain folder: templateRef does not match the definition name. Compare both strings byte for byte, including case and whitespace.
  3. Instances present, definition missing: the definition went out in a DBIRTH. Move every isDefinition: true metric into the NBIRTH.
  4. An old member list persists after an edit: the definition changed without a new NBIRTH. Restart the edge client or trigger Engine's rebirth command.
  5. Instance members missing or mistyped: the instance member array differs from the definition's. Align names and types.
  6. Nothing decodes at all: the payload is JSON from a plain MQTT node rather than Sparkplug protobuf. Confirm the topic namespace and the encoder, and see troubleshooting rejected JSON payloads on an MQTT broker for that failure mode.

Questions asked

Does the UDT definition survive an edge node reconnect?

Only if the node republishes it. Engine builds its view from the births it receives, so a normal reconnect brings the definitions back with the fresh NBIRTH. A broker change or an expired session leaves Engine with nothing until new births arrive, and triggering the rebirth command from Engine is the fastest way to restore the definitions without restarting the edge client.

How do I update one member of a UDT instance at runtime?

Publish a DDATA for that device carrying the instance as a Template metric under the same instance name it was born with, listing only the changed members and their new values. DDATA never creates or alters structure: a member added, removed, retyped, or renamed needs a new NBIRTH with the revised definition, followed by fresh DBIRTHs for the instances.

Can a UDT definition contain another UDT?

Yes. A member of a definition can itself be a Template metric whose templateRef names another definition, and the instance then binds through the chain. The constraint is that every definition in the chain must appear in the same NBIRTH, published before any instance that references it, directly or through nesting.

Does the broker need Sparkplug template support for this to work?

No. The broker routes the protobuf bytes without decoding them; template resolution happens in the consuming client, here MQTT Engine. What the broker contributes is session state and size limits, so the settings to check on it are persistent session behavior and maximum payload. A broker restart without persistent sessions has the same effect as a broker switch: definitions return only with fresh births.

Why does my Node-RED flow still publish flat tags when the payload contains a Template metric?

Most likely the Sparkplug node flattened or dropped the value object on its way to the encoder. Test with one definition and one instance, then decode the published NBIRTH: if the definition metric is missing or its datatype is not Template, that node cannot forward template objects, and the births must be assembled in a function node or moved to the Tahu client.

Keep reading

  • How-to

    Push ClearSCADA values to MQTT through an edge gateway

    ClearSCADA and Geo SCADA do not publish straight to an MQTT broker: the value travels from the SCADA server through an edge gateway to the broker as two independent client connections. Prove the SCADA read on one known point and the MQTT publish on a fixed test payload separately, join them only after both pass, and chase a login failure in the server's own web logs, never in the broker settings.

    Edge computing and IIoT

  • Explainer

    Exporting Sparkplug B out of Geo SCADA to a historian

    No modified DDK driver will push Sparkplug B out of Geo SCADA, because the driver layer is pull-only in the outbound direction. Build the publisher on the Client API Sample DataFeeder pattern, which watches about 100,000 points per instance; for millions of points, use HSI or a database-level connector.

    Edge computing and IIoT

  • Troubleshooting

    Fixing extra characters in a PLC MQTT JSON payload

    The extra characters come from publishing a UTF-16 WSTRING to a subscriber that reads UTF-8, and from sending SIZEOF bytes of the allocated buffer instead of the text. Convert the finished JSON with JSON.Stu.ConvertUTF16toUTF8 into a STRING(2000), then publish TO_UDINT(JSON.Stu.StrLenA(ADR(utf8JsonData))) bytes. Keep the MQTT 5 properties; they declare UTF-8 but convert nothing.

    Edge computing and IIoT