--- title: SparkplugB Listener Rule description: Accept inbound SparkplugB messages on the ControlCom Edge Server and route their metrics to platform variables. source: https://documentation.controlcomtech.com/build/edge-server/rules/sparkplugb-listener --- # 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](https://documentation.controlcomtech.com/build/edge-server/clients/modbus), it opens no outbound connection: it subscribes to the Edge Server's local MQTT broker and reacts to whatever the publisher sends. > **Workflow Stage: Collect** ## How it works SparkplugB topics have the structure: ``` spBv1.0//// ``` 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](https://documentation.controlcomtech.com/build/edge-server/getting-started) covers deployment and onboarding. Each metric you capture needs a variable on the gateway to receive it. Create those first (see [Creating a Variable](https://documentation.controlcomtech.com/build/edge-server/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 `` and `` 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 `` segment the publisher uses (for example `udp-bridge-1`). It must follow the topic-segment rules above. ### Source Devices Source Devices declare which `` 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 `` 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 `` 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](https://documentation.controlcomtech.com/build/edge-server/data-processors#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](https://documentation.controlcomtech.com/platform/devices/edge-server#sdk-commands) describes the full set of SDK commands. On the gateway itself, restart the container as described in the [Edge Server getting started guide](https://documentation.controlcomtech.com/build/edge-server/getting-started). ![Restarting Device](https://documentation.controlcomtech.com/images/devices/device-details-page.png) *The Details tab, with the Send command panel used to restart the Edge Server*