MQTT Integration Guide

Publish messages to and subscribe to topics on any MQTT broker, with TLS, QoS levels and retained messages.

Protocol

MQTT 3.1 · 3.1.1 · 5.0

Default port

1883 (plain) · 8883 (TLS)

Authentication

Username and password · mutual TLS

Operations

Publish · Subscribe

Use MaestroHub's MQTT connector to exchange real-time messages with PLC gateways, IoT devices, and event-driven services. This guide explains how to configure connections, design publish/subscribe functions, and orchestrate pipelines.

Overview

The MQTT connector delivers:

• MQTT v3.1, v3.1.1 and v5.0 support with QoS 0/1/2 and retained message control
• Publish and subscribe functions for bidirectional communication
• Security options including TLS, mutual authentication, and username/password logins
• Payload templating for JSON, binary buffers, or delimited text

Connection Configuration

Creating an MQTT Connection

Navigate to Connections → New Connection → MQTT and fill in these details:

MQTT Connection Creation Fields

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters)
Description	-	Optional description for this MQTT connection

2. MQTT Broker Configuration

Field	Default	Description
Protocol	tcp	Connection protocol: tcp (mqtt://), ssl (mqtts://), ws (ws://), or wss (wss://), required
Broker Hostname	-	MQTT broker hostname or IP address (e.g., broker.example.com), required
Port	1883	MQTT broker port (1-65535), typically 1883 for plain and 8883 for TLS, required
MQTT Version	3.1.1	MQTT protocol version (3.1 / 3.1.1 / 5.0), required
Client ID	-	Unique client identifier (max 65535 characters). Server generates if not specified
Keep Alive	1m	Keep-alive interval, a duration from 0s to 65535s in whole seconds (MQTT sends seconds). 0s turns keep-alive pings off
Connection Timeout	30s	How long to wait when connecting to the broker (1s-5m)
Write Timeout	30s	How long each publish / subscribe / unsubscribe may wait for the broker's acknowledgement (1s-5m). Applies to every MQTT version (the v5 packet timeout).

Protocol Options

• 3.1: Legacy MQTT version
• 3.1.1: Recommended, most widely supported
• 5.0: Latest, with enhanced features and performance

3. Session Management

3a. For MQTT v3.1 and v3.1.1

Field	Default	Description
Clean Session	true	Start with a clean session on connect

3b. For MQTT v5.0

Field	Default	Description
Clean Start	true	Start with a clean session on initial connection. Saved as the same setting as Clean Session.

4. Basic Authentication

Field	Default	Description
Username	-	MQTT broker username (optional)
Password	-	MQTT broker password (optional, but username is required if password is provided)

5. TLS/SSL Settings

5a. TLS Configuration

Field	Default	Description
Enable TLS/SSL	false	Use encrypted connection to the MQTT broker. Always on for the ssl and wss protocols; on with tcp, the connection uses ssl://. Not allowed with ws (plain WebSocket is never encrypted); use wss instead.
Skip Certificate Verification	false	Skip SSL certificate verification (not recommended for production)

5b. Certificate Verification Settings

(Only displayed when TLS is enabled and Certificate Verification is NOT skipped)

Field	Default	Description
Server Name (SNI)	-	Server name for SNI verification (e.g., broker.example.com)

5c. Client Certificates

(Only displayed when TLS is enabled and Certificate Verification is NOT skipped)

Field	Default	Description
Client Certificate	-	Client certificate for mutual TLS authentication (PEM format)
Private Key	-	Private key for client certificate (PEM format)
CA Certificate	-	CA certificate for server verification (PEM format)

6. Last Will and Testament (LWT)

Field	Default	Description
Will Topic	-	Topic to publish the will message (e.g., clients/disconnected). Leave empty for no Last Will.
Will QoS	0	Quality of Service for will message (0 / 1 / 2)
Will Message	-	Message to publish on unexpected disconnect
Retain Will Message	false	Broker retains the last will message

QoS Levels

• QoS 0: At most once, no confirmation
• QoS 1: At least once, confirmed delivery
• QoS 2: Exactly once, guaranteed single delivery

7. MQTT v3.1.1 Advanced Options

(Only displayed when MQTT Version = 3.1 or 3.1.1)

Field	Default	Description
Ping Timeout	10s	How long to wait for the broker's ping response before the connection is considered lost (1s-5m)

Reconnection, subscription recovery and message acknowledgement are handled by the platform, so they are not configurable here.

8. MQTT v5.0 Enhanced Properties

(Only displayed when MQTT Version = 5.0)

These are sent to the broker in the CONNECT packet.

8a. Session & Flow Control

Field	Default	Description
Session Expiry Interval	-	How long session state persists after disconnect, a duration from 0s to 4294967295s in whole seconds (e.g. 2h). Empty or 0s = the session ends with the network link
Receive Maximum	-	Maximum number of QoS 1 and QoS 2 messages the broker may send before they are acknowledged (1-65535). Empty = broker default (65535)
Maximum Packet Size (bytes)	-	Largest packet this client accepts from the broker (1-268435455). Empty = no limit

8b. Diagnostics

Field	Default	Description
Request Problem Information	true	Ask the broker to include reason strings on failures

8c. User Properties

Field	Default	Description
User Properties	-	Custom key-value pairs sent with the connection (JSON format)

Example User Properties

• {"correlationId":"12345","origin":"edge-gateway"}: Identify related transactions
• {"tenant":"alpha","priority":"high"}: Route messages by tenant or priority

9. Connection Labels

Field	Default	Description
Labels	-	Key-value pairs to categorize and organize this MQTT connection (max 10 labels)

Example Labels

• environment: production: Deployment environment
• team: iot: Responsible team
• protocol: mqtt: Connection protocol
• region: us-east-1: Geographical region

Notes

• MQTT Version compatibility: Sections 7 (v3.1.1 Advanced Options) and 8 (v5.0 Enhanced Properties) appear based on the selected MQTT version.
• The ssl and wss protocols always use TLS.
• Authentication requires a username when a password is provided.
• TLS certificate fields are available only when TLS is enabled and certificate verification is not skipped.
• Clean Session and Clean Start represent the same behavior in v3.1.1 and v5.0, respectively.
• Timeouts accept a unit, e.g. 30s or 2m.

Function Builder

Creating MQTT Functions

After the connection is configured:

1. Open the connection and go to its Functions tab → New Function
2. Choose Publish or Subscribe as the function type
3. Define topic filters, QoS, retained settings, and payload templates

Zoom

Design MQTT publish or subscribe functions with topic templates and payload mappings

Publish Function

Purpose: Send messages to MQTT topics. Create a function to publish messages to specific MQTT topics with configurable payload templates, QoS levels, and retention settings.

Configuration Fields

Field	Type	Required	Default	Description
Topic Template	String	Yes	-	MQTT topic to publish to (supports parameters). Example: sensors/((deviceId))/temperature
Payload Template	String	Yes	-	Message payload template (supports parameters). Example: {"temperature": ((value)), "timestamp": "((now))"}
QoS Level	Number	No	0	Quality of Service level for published messages (0, 1, or 2)
Retained	Boolean	No	false	Whether messages should be retained by the broker
Content Type (v5.0)	String	No	-	MIME type of the message payload, sent as the MQTT 5 Content Type property. Example: application/json. Empty sends none. A 3.1.1 connection refuses a publish that sets it
Message Expiry (v5.0)	Duration	No	-	How long the broker keeps the message for subscribers it cannot deliver to yet, sent as the MQTT 5 Message Expiry Interval in whole seconds (e.g. 1h = 3600, up to 4294967295s). Empty or 0s sends none: the message never expires. A 3.1.1 connection refuses a publish that sets it
Payload Format (v5.0)	Number	No	-	Tells receivers how to read the payload, sent as the MQTT 5 Payload Format Indicator: 0 unspecified bytes, 1 UTF-8 text. With 1, a payload that is not valid UTF-8 is refused before it is sent. Empty sends none. A 3.1.1 connection refuses a publish that sets it
Response Topic (v5.0)	String	No	-	Topic a receiver should publish its reply to, sent as the MQTT 5 Response Topic property (supports parameters). A topic name: no + or # wildcards. Empty sends none. A 3.1.1 connection refuses a publish that sets it
Correlation Data (v5.0)	String	No	-	Value a receiver echoes in its reply so the requester can match the two, sent as the MQTT 5 Correlation Data property (the bytes of the text; supports parameters). Empty sends none. A 3.1.1 connection refuses a publish that sets it
User Properties (v5.0)	Object	No	-	Key-value pairs of strings sent with the message as MQTT 5 User Properties, in key order (values support parameters). Example: {"site": "plant-1"}. Empty sends none. A 3.1.1 connection refuses a publish that sets it

Use Cases: Sensor data publishing, device command sending, status updates, event notifications

Subscribe Function

Purpose: Receive messages from MQTT topics. Create a function to listen for messages from specific MQTT topics with wildcard support for flexible topic matching.

Configuration Fields

Field	Type	Required	Default	Description
Topic Filters	Array	Yes	["sensors/+/data"]	MQTT topic patterns to subscribe to (supports wildcards + and #). Example: ["sensors/+/temperature", "devices/+/status"]
QoS Level	Number	No	0	Quality of Service level for subscription (0, 1, or 2)
No Local (v5.0)	Boolean	No	false	The broker does not send this connection the messages it publishes itself, sent as the MQTT 5 No Local subscribe option. Not allowed on a $share/... filter, nor on a connection that runs on several instances (its filters are shared)
Retain as Published (v5.0)	Boolean	No	false	Forwarded messages keep the retain flag they were published with (off: the broker clears it on live messages), sent as the MQTT 5 Retain As Published subscribe option
Retain Handling (v5.0)	Number	No	0	Retained messages when the subscription is made, sent as the MQTT 5 Retain Handling subscribe option: 0 send them, 1 send them only when the subscription is new, 2 never send them

Use Cases: Sensor data collection, device status monitoring, event processing, message routing

Subscribe options on one connection

MQTT keeps one set of subscribe options per topic filter on a connection, and every function on the connection receives each message whose topic its filter matches. So subscribe functions on one connection whose filters overlap (for example plant/+/temp and plant/#) must use the same No Local, Retain as Published and Retain Handling. A subscribe that differs is refused, and the error names the filter, both sets of options and the function that already holds the filter. Give them the same options, or put one on a separate connection. QoS may differ: the broker subscription uses the highest QoS asked for.

A 3.1.1 connection cannot send these options: it refuses a subscribe that turns one on.

Shared subscriptions

To spread a topic's messages over several subscribers, write the filter as a shared subscription: $share/<group>/<topic>, for example $share/line-workers/sensors/+/data. The broker delivers each matching message to one member of the group. Messages arrive on the plain topic (sensors/line1/data), which is what the function sees.

• One group per topic, per connection. Two functions on the same connection whose filters overlap must subscribe in the same group (or both without one). The broker delivers a message by topic only, so MaestroHub could not tell a message meant for one function from one meant for the other; the second function's subscription is refused with a message naming both functions. Put the functions in the same group, or move one to its own connection.
• Several instances. When a connection runs on more than one instance (its scaling setting), every function filter on it is subscribed in the group mh-<connection id> automatically, so each message runs one pipeline, not one per instance. A filter you wrote with your own $share/ group is kept as written.
• Retained messages. A shared subscription receives no retained messages when it is made; this is how MQTT defines it. A connection on several instances therefore no longer replays retained messages on subscribe.
• No Local. MQTT 5 does not allow No Local on a shared subscription (the broker would close the connection), so a function that turns it on is refused on a $share/ filter and on a connection that runs on several instances.
• MQTT 3.1.1. Shared subscriptions are an MQTT 5 feature. Brokers such as Mosquitto, EMQX and HiveMQ also honour $share/ for 3.1.1 clients; a broker that does not treats the filter as a plain topic name and nothing arrives. On MQTT 5 a broker without the feature refuses the subscription, and the refusal is shown on the Subscriptions page.

When a subscription is refused

The connection can be up while the broker refuses one function's filter: the broker's permissions do not allow it, the filter is not valid, or the broker lacks a feature the filter needs. MaestroHub then does not count the function as subscribed. The Subscriptions page shows subscription refused with the filter and the broker's reason next to the connection's state, and the subscription is retried every 30 seconds, so a fix at the broker takes effect without a restart. A QoS lower than the one the function asked for is accepted and noted once in the log.

Some brokers do not refuse: Mosquitto with an ACL file accepts every subscription and withholds the messages the client may not read. MaestroHub cannot tell that apart from a quiet topic, so the page shows the function as subscribed. Check the broker's ACL when a feed on such a broker stays silent.

Several functions on one filter

When a second function subscribes to a filter the connection already holds, MaestroHub re-sends the subscription at the highest QoS the functions ask for. On MQTT 5 the broker's retained messages for the filter reach the joining function only; on MQTT 3.1.1, on an MQTT 5 broker without subscription identifiers (AWS IoT Core), and when the filter is subscribed with Retain as Published, they reach every function on the filter, as they do after a reconnect. With Retain Handling 1 or 2 the broker sends no retained messages for the re-send.

Using Parameters

MQTT functions support parameterized topics and payload values via the ((parameterName)) syntax.

Configuration	Description	Example
Type	Validate incoming pipeline data	string, number, boolean, datetime, json, buffer
Required	Force topic fragments or payload fields	Required / Optional
Default Value	Provide fallback values	'line-01', 0, '{}'
Description	Document intent for other authors	"Line identifier appended to the topic path"

Zoom

Configure parameter validation, defaults, and descriptions for MQTT topics and payloads

Discover Tab

The connection's Discover tab shows the topics carrying traffic on the broker, so you can create functions from them. It becomes usable once the connection is saved.

1. Enter a Topic Pattern (default #, all topics; for example sensors/+/temperature for one branch), pick a QoS Level, and click Start Discovery.
2. Arriving topics build up in the Topic Tree. Select a topic to see its details and payload in Topic Details.
3. Click Create Subscribe Function or Create Publish Function and confirm the function name. A Subscribe function subscribes to that topic at QoS 0. A Publish function publishes to it at QoS 0, not retained, with a payload template built from the topic's payload: each value in a JSON payload becomes a ((parameter)); any other payload becomes ((payload)). A button reads Subscribe Function Exists / Publish Function Exists when the connection already has one for that topic.
4. Click Stop Discovery when you are done. A running session shows its idle timeout and maximum duration, and stops collecting new topics once it reaches its topic limit.

Zoom

Discover tab with live topics in the Topic Tree and the selected topic's payload

Pipeline Integration

Use the MQTT connection functions you create here as nodes inside the Pipeline Designer to synchronize production data with the rest of your stack. Drag in the publish or subscribe node, bind its parameters to upstream node outputs or constants, and shape event-driven flows without leaving the designer.

If you are planning more complex orchestration, review the Nodes page for patterns on where MQTT nodes fit best within broader orchestration strategies.

Zoom

MQTT node with connection, function, and parameter mappings

Common Use Cases

Telemetry Distribution

Publish normalized sensor data to MQTT topics consumed by SCADA dashboards, analytics platforms, or digital twins.

Command Handling

Subscribe to command topics from enterprise systems and invoke PLC writes, REST calls, or script nodes in response.

Edge-to-Cloud Bridging

Bridge legacy PLC data into cloud IoT platforms by combining OPC UA/Modbus reads with MQTT publish steps.