MQTT Subscriber

The MQTT Subscriber connects to a Message Queuing Telemetry Transport (MQTT) broker, subscribes to a Sparkplug B namespace, and writes the incoming metrics into the profile tag tree as read-only tags. Sparkplug B is an MQTT payload format for industrial data. It is the inbound counterpart to the MQTT Publisher, which only sends, and it sits in the Publishers & Subscribers category.

Use it to bring the data of an external Sparkplug edge node, or of a supervisory control and data acquisition (SCADA) or industrial Internet of Things (IoT) platform, into Profinity as ordinary tags. The tags can be shown on a dashboard, logged, used in a rule, or read by a script.

flowchart LR
    Broker["MQTT broker"] --> Subscriber["MQTT Subscriber"] --> Tags["Read-only tags"]

The MQTT Subscriber receives Sparkplug metrics from an MQTT broker and writes them into the profile tag tree as read-only tags

The MQTT Subscriber is for an external Sparkplug B source, such as a third-party edge device, gateway, or SCADA platform. To share tags between two Profinity instances, use Tag Relay, which has its own snapshot format and does not use Sparkplug.

Licence required

The MQTT Subscriber requires the Data Relay licensed feature. Refer to Licensing for the editions that include it.

Quick start

The subscriber starts only when Server URL, Topic filter, Host ID and Tag path prefix are all set.

1. Add an MQTT Subscriber to your profile from the Publishers & Subscribers category.
2. Enter the broker address in Server URL, for example mqtt://broker.example.com.
3. Keep the default Topic filter spBv1.0/# to subscribe to the whole Sparkplug B namespace, or narrow it to one group, for example spBv1.0/Plant1/#.
4. Enter a Host ID, for example Profinity.
5. Enter a Tag path prefix, for example External.
6. If the broker requires a login, enter the Username and Password.
7. Save the settings.

With Auto connect on, which is the default, the subscriber connects when the profile loads, and its status shows On while it is connected. To check that it works, wait for the edge node to publish. The tags then appear under the Tag path prefix, at the paths described in Where tags appear.

Settings

Connection settings

Setting	Type	Required	Default	Purpose
Server URL	Text	Yes	None	The broker's connection URL, for example mqtt://broker.example.com or mqtts://broker.example.com. Use mqtts:// to enable Transport Layer Security (TLS).
Broker port	Whole number	No	1883	The broker's port, from 1 to 65535. Defaults to 1883. A port in the Server URL takes precedence. With an mqtts:// URL that has no port, leaving this at 1883 connects on 8883, and any other value is used as entered.
Auto connect	On or off	No	On	Connects to the broker when the profile loads. On by default. Refer to Connections and reconnecting.
Trust all server certificates	On or off	No	Off	Disables TLS server certificate validation. Enable only when connecting to a trusted broker that uses a self-signed certificate.
Username / Password	Text and Secret	No	None	Credentials for broker authentication, when the broker requires them. The password is stored encrypted.
Client ID	Text	No	Empty	The MQTT client ID. Leave blank to generate one.

Sparkplug settings

Setting	Type	Required	Default	Purpose
Topic filter	Text	Yes	spBv1.0/#	The Sparkplug topic filter to subscribe to. Defaults to spBv1.0/#, the whole Sparkplug B namespace. Narrow it to one group, for example spBv1.0/Plant1/#, to subscribe to only that group.
Host ID	Text	Yes	None	The name this subscriber announces as a Sparkplug primary host application, for example Profinity. It must not contain +, # or /.

Tags settings

Setting	Type	Required	Default	Purpose
Tag path prefix	Text	Yes	None	The profile subtree that subscribed metrics are written under, for example External. The subscriber owns this subtree, so do not create tags beneath it from any other component or script. Refer to Tag tree path for the path rules.

Example

This example is for illustration. It subscribes to the group Plant1 and writes its metrics under the tag path prefix External. Add it under components: in the profile.yaml file of the profile.

- component:
    type: MqttSubscriber
    id: MqttSubscriber1
    name: MQTT Subscriber
    tagTreeParentPath: /
    url: mqtt://BROKER_HOST
    brokerPort: 1883
    autoConnect: true
    topicFilter: spBv1.0/Plant1/#
    hostId: Profinity
    tagPathPrefix: External

Replace BROKER_HOST with the address of your broker. Each value is a setting from the Settings section.

Where tags appear

An incoming metric is written to a path built from the Tag path prefix and the Sparkplug group, edge node, device, and metric names:

{prefix}/{groupId}/{edgeNodeId}/{deviceId}/{metric segments}

For example, with the prefix External, group Plant1, edge node Node1, device Pump and metric Temp/Out, the tag path is External/Plant1/Node1/Pump/Temp/Out. The device segment is omitted for a node-level metric, and present for a device-level metric.

These are Sparkplug B terms. An edge node is the MQTT client that connects to the broker and publishes for a site, a device is a piece of equipment attached to an edge node, and a metric is one named data point. A death message is the message that the broker publishes for an edge node when it disconnects unexpectedly. As of November 2026, the Eclipse Sparkplug specification defines each of these. A metric name that contains / adds further segments beneath the device.

Subscribed tags are read-only

A tag the MQTT Subscriber creates cannot be written to from a dashboard, a script or any other source, and the write is rejected. The only thing that changes the value of one of these tags is the next Sparkplug message for that metric. A lost broker connection, or a death message for the node or device, marks the tags Stale and keeps their last value.

To react to an incoming value, use a Run on tag change script that watches the tag. The script reads the new sample as it would for any other tag change, and it is not given the raw MQTT payload. Refer to Script Types for the script types.

If an incoming metric's path is already used by something that is not one of this subscriber's own tags, that one metric is skipped and a warning is written to the log. Examples are an existing device tag, a Tag Relay mirror, a writable tag that a script component owns, or a derived tag. The rest of the message is still applied. To stop the skip, remove the other tag at that path, or change the Tag path prefix so that the metric is written beneath a subtree that holds no other tags.

Sparkplug behaviour

The subscriber applies metrics from node-level and device-level publishers, and skips command and state messages and metric types that it does not support. MQTT Subscriber Sparkplug behaviour lists the messages and metric types it applies, how it announces itself as a host, and what it does after a sequence gap or a metric death.

Reconnection

The subscriber keeps trying to connect every 5 seconds, both when the broker is down at start and after a lost connection. It stays in Error until the broker is back, and the log records the reason once for each outage. Refer to Connections and reconnecting for the full behaviour.

Status and troubleshooting

The MQTT Subscriber shows On while it is connected to the broker, Error while it is running and disconnected, and Off when it is stopped. While it is in Error, it retries as described under Reconnection.

Check the Logs for the underlying message first.

What you see	Cause	What to do
The status shows Error.	The Server URL scheme or Broker port does not match the broker.	Correct the scheme and port.
The status shows Error.	The broker does not accept the Username and Password.	Correct the credentials.
The status stays Off.	One of Server URL, Topic filter, Host ID or Tag path prefix is not set, so the subscriber stays off.	Set all four.
The status shows On but no tags appear.	The Topic filter is set to a different group from the one you expect.	Change the Topic filter to cover that group.

Use the MQTT Publisher or Webhook Publisher to send data out, and Tag Relays to share tags between Profinity instances.