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, it opens no outbound connection: it subscribes to the Edge Server's local MQTT broker and reacts to whatever the publisher sends.

How it works

SparkplugB topics have the structure:

spBv1.0/<groupId>/<msgType>/<edgeNodeId>/<deviceId>

The Edge Server derives groupId itself, from the device's id or from the location name when the device has a location set, so you do not configure it on the rule. msgType is the SparkplugB message type (NBIRTH, NDATA, DBIRTH, DDATA and so on) and is handled internally. The two segments you do configure are edgeNodeId, which is the rule's Source Gateway and must match exactly what the publisher uses, and deviceId, which must match one of the rule's Source Devices for a message to be accepted.

Each accepted metric is routed to a platform variable through a Mapping that pairs a source device and a SparkplugB metric name with a Topic Property Path.

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

Prerequisites

The Edge Server must already be onboarded as a ControlCom Gateway. The Edge Server getting started guide covers deployment and onboarding.

Each metric you capture needs a variable on the gateway to receive it. Create those first (see Creating a Variable); you select each variable by its Topic Property Path when you add a mapping below.

You also need an external publisher (UDP bridge, gateway or third-party device) that publishes SparkplugB messages to the Edge Server's local MQTT broker, and you need to know the <edgeNodeId> and <deviceId> segments it publishes under.

Creating a SparkplugB Listener

1. Open Devices under System in the sidebar and select the onboarded gateway.
2. Open the Edge Server tab. The SDK Configuration editor opens on its Clients tab; switch to the Rules tab.
3. Click Add Rule and choose SparkplugB Listener in the Add New Rule dialog.

The new rule opens in a side panel and also appears as a card on the Rules tab; click the card to reopen it later.

The rule panel has four tabs: Connection, Source Devices, Settings and Mappings.

Connection

1. Enter a Name for the rule and, optionally, a Description.
2. Turn on Enabled.
3. Enter the Source Gateway, the exact <edgeNodeId> segment the publisher uses (for example udp-bridge-1). It must follow the topic-segment rules above.

Source Devices

Source Devices declare which <deviceId> segments the listener accepts. Add at least one before adding mappings.

1. Click Add Device.
2. Enter the Device ID, the literal string the publisher uses as the <deviceId> segment, often a MAC address or serial number such as 001EC06C5B06. It must be unique within the rule.
3. Optionally enter an Alias. When set, the alias is matched as the <deviceId> segment instead of the Device ID. This lets you keep the hardware identifier in the Device ID field while the publisher uses a friendly name such as sensor-alpha.
4. Repeat for every source device the listener should accept.

Removing a device also removes any mappings that point at it.

Settings

The Settings tab holds maintenance actions: Remove Rule deletes the listener from this configuration, Export Mappings downloads the mapping list as a CSV for bulk editing, and Import Mappings loads mappings from a CSV. Devices referenced by an imported CSV are created on the rule if they do not already exist.

Mappings

Each mapping routes one SparkplugB metric on one source device to a platform variable. Click Add Mapping, then select the new entry in the list on the left. Sort by Device / Metric keeps the list in order.

On the General tab:

1. Select the Source Device the metric belongs to.
2. Enter the Sparkplug B Metric Name, which must match the name field of the metric in the inbound payload (for example Inputs/0, Temperature or Tank1/Level). The source device and metric name pair must be unique within the rule.
3. Select the Platform Variable (Topic Property Path) that receives the value. The mapping's type (number, boolean or string) follows the selected variable, and the incoming value is converted to that type.

On the Scaling tab (number mappings only), Scale (defaults to 1) multiplies the metric value, Offset (defaults to 0) is added after scaling, and Decimals rounds the stored value. If the publisher sends 857 and the real value is 8.57, set Scale to 0.01.

On the Misc tab, Send if Stale After Milliseconds forces a publish to the platform when the value has not changed in that time; presets cover 10 minutes, 1 hour, 6 hours and 1 day, and leaving it empty disables stale publishing. Deadband Percentage (defaults to 5, number mappings only) suppresses changes smaller than that share of the previous value.

On the Transforms tab you can add Value Transforms that rewrite the incoming value before it is converted and stored. A transform references the current value as {{READ_VALUE}}. Several transforms run in rank order, each one's output becoming the next one's READ_VALUE, so you can chain a scale, a clamp and a threshold.

Saving

Click Save Configuration in the editor header, then confirm with Save Configuration in the Save SDK configuration? dialog. The configuration is stored on the platform; the gateway applies it on its next restart.

Deployment

The Edge Server reads its configuration when it starts, so a restart is what puts the new listener into service. There are two ways to trigger one.

From the platform, open the gateway's Details tab and click Restart in the Send command panel. The Edge Server restarts and reconnects with the new configuration. Edge Server Management describes the full set of SDK commands.

On the gateway itself, restart the container as described in the Edge Server getting started guide.