PlatformBuildAPIChangelog

SparkplugB Listener Rule

The SparkplugB Listener is a Rule on the ControlCom Edge Server that accepts inbound SparkplugB (spBv1.0) messages from an external publisher — a UDP-to-MQTT bridge, a gateway, or another edge device — and routes their metrics to platform variables.

Unlike a Client, the listener does not open an outbound connection. It subscribes to the Edge Server's local MQTT broker and reacts to whatever the publisher pushes.

How it works

SparkplugB topics have the structure:

spBv1.0/<groupId>/<msgType>/<edgeNodeId>/<deviceId>
  • groupId is derived automatically by the Edge Server. It uses the device's id, or the location name when the device has a location set. You do not configure it on the rule.
  • msgType is the SparkplugB message type (NBIRTH, NDATA, DBIRTH, DDATA, etc.) — handled by the listener internally.
  • edgeNodeId is the Source Gateway you configure on the rule. It must match exactly what the external publisher uses.
  • deviceId is one of the Source Devices you configure under the rule. A message is only accepted when its deviceId segment matches one of these.

Each accepted metric is then routed to a platform variable through a Mapping that pairs a (Source Device, Sparkplug B Metric Name) tuple with a Topic Property Path.

Topic segment rules: edgeNodeId, deviceId, and alias must not contain /, +, #, whitespace, or control characters, because those would either split the MQTT topic or match an MQTT wildcard.

Prerequisites

  • This guide requires the ControlCom Edge Server to be onboarded. See our Onboarding Guide for the Edge Server to get started.
  • A platform variable must already exist on the device to receive each metric you want to capture. See Creating a Variable — you'll need its Topic Property Path when configuring a mapping.
  • An external publisher (UDP bridge, gateway, third-party device) that publishes SparkplugB messages to the Edge Server's local MQTT broker. The publisher's <edgeNodeId> and <deviceId> topic segments must be known up front.

Creating a SparkplugB Listener

To create a new SparkplugB Listener rule:

  1. Navigate to Administration > Devices
  2. Select an onboarded device
  3. In the device page, click the Edge Server tab
  4. Switch to the Rules tab in the SDK editor
  5. Click + Add Rule and select SparkplugB Listener
  6. Select the newly added rule in the rules list

Connection Sub Menu

  1. Enter a friendly Name for the rule, and an optional Description.
  2. Toggle Enabled on to activate the listener.
  3. Enter the Source Gateway — the exact <edgeNodeId> segment the external publisher uses (for example udp-bridge-1). The value must follow SparkplugB topic-segment rules (no /, +, #, or whitespace).

Source Devices Sub Menu

Source Devices declare which <deviceId> topic segments this listener should accept. You must add at least one device before you can add mappings.

  1. Open the Source Devices tab and click Add Device.
  2. Enter the Device ID — the literal string the external publisher uses as the <deviceId> segment (often a MAC address, serial number, or device identifier such as 001EC06C5B06). Must be unique within the rule.
  3. Optionally enter an Alias — a friendly name. If provided, the alias is used as the <deviceId> segment instead of the Device ID field. Leave blank to match on the Device ID. Useful when the publisher publishes under a friendly name (sensor-alpha) while you still want to record the hardware identifier (MAC, serial) in the Device ID field.
  4. Repeat for every source sensor the listener should accept.

Removing a device will also cascade-remove any mappings that point at it.

Mappings Sub Menu

Each mapping routes a SparkplugB metric on a specific source device to a platform variable.

  1. Open the Mappings tab and click Add Mapping.
  2. Select the Source Device — the device this metric belongs to.
  3. Enter the Sparkplug B Metric Name — must match the name field of the SparkplugB metric in the inbound payload (for example Inputs/0, Temperature, or Tank1/Level). The (Source Device, Metric Name) pair must be unique within the rule.
  4. Select the Platform Variable (Topic Property Path) — the platform variable that should receive the metric's value. The mapping's type (number, boolean, string) is inferred from the selected variable, and the incoming metric value is coerced to that type.
  5. On the Scaling tab (only for number mappings):
    • Scale — multiplier applied to the metric value (defaults to 1). Example: if the publisher sends 857 but the expected value is 8.57, set scale to 0.01.
    • Offset — constant added to the scaled value (defaults to 0).
    • Decimals — number of decimals to keep in the stored value.
  6. On the Misc tab:
    • Send if Stale After Milliseconds — force a publish to the platform if the value has not changed in this many milliseconds. Quick presets are available for 10 minutes, 1 hour, 6 hours, and 1 day. Leave blank for no stale-publish.
    • Deadband Percentage — only publish changes greater than this percent of the previous value. Defaults to 5. Only applies to number mappings.
  7. On the Transforms tab, optionally add Value Transforms that rewrite the incoming metric value before it is coerced and stored. Transforms reference the current value as {{READ_VALUE}}. Multiple transforms run in rank order — each transform's output becomes the next transform's READ_VALUE, letting you chain conversions (e.g. scale, then clamp, then threshold).

Settings Sub Menu

The Settings tab exposes maintenance actions for the rule:

  • Remove Rule removes the SparkplugB Listener from this Edge Server configuration.
  • Export Mappings downloads the current mapping list as a CSV (useful for bulk editing).
  • Import Mappings restores mappings from a previously exported CSV. Devices referenced by the CSV are auto-created if they don't already exist on the rule.

Saving

After configuring Connection, Source Devices, and Mappings, click the Save Configuration button and click Save in the confirmation popup.

Deployment

Once the Edge Server has been configured with a SparkplugB Listener, the changes can be deployed in a few ways. The Edge Server will pick up its changes on the next boot of the container.

Sending restart command from ControlCom Connect Platform

  1. Navigate to Administration > Devices
  2. Select the Device with the new SparkplugB Listener configuration
  3. On the Details tab, click the restart button. This will stop the instance where it is currently running.

Stopping and starting the ControlCom Edge Server manually

This can be done by following the restart commands from the Onboarding Guide of the Edge Server

Restarting Device
Device Details page on ControlCom Connect

Was this page helpful?