Configure the MQTT Connector

Configure an MQTT broker connection, discover or create topics, publish and subscribe to data, set TLS and QoS, and troubleshoot the MQTT Connector.

+ More

The MQTT Connector connects SIA Connect to an MQTT broker. Use it to subscribe to topics, publish values from mappings, and discover topics that are actively receiving messages.

This guide explains how to create an MQTT instance, configure broker security, discover or create items, understand MQTT delivery settings, and resolve common connection and messaging problems.

Before you begin

Prepare the following information:

The broker hostname or IP address.
The broker port.
A unique MQTT client ID for SIA Connect.
A username and password if the broker requires authentication.
The broker CA certificate if you want SIA Connect to verify the broker.
A client certificate and matching private key if the broker requires mutual TLS.
The topic names and access-control permissions required for publishing, subscribing, and discovery.

Make sure SIA Connect can reach the broker through the configured network, firewall, and DNS settings.

Treat broker passwords, private keys, and certificates as sensitive information.

Create an MQTT instance

Sign in to the Edge Portal.
Open Workspace > Instances.
Select Add instance.
Select the MQTT Connector.
Enter a descriptive instance name.
Enter the broker hostname or IP address in Address.
Complete the Connector-specific parameters described below.
Select Save.

The Connector removes any protocol prefix entered in Address and uses either tcp:// or ssl:// according to the configured port and TLS settings. You can therefore enter an address such as broker.example.com without a prefix.

Instance parameters

Parameter	Default	Description
Address	None	Broker hostname or IP address. The Connector adds the connection protocol automatically.
Port	`8883`	TCP port used by the MQTT broker.
Username	Empty	Username used to authenticate with the broker. Leave empty when authentication is not required.
Password	Empty	Password used to authenticate with the broker.
Device ID / Client ID	Generated device name	Client identifier presented to the broker. It must be unique among concurrently connected clients.
Keep alive interval	`60` seconds	Intended interval for MQTT keep-alive traffic. See Current Connector limitations below.
Subscription request mode	Bulk requests	Controls whether topics are submitted to the broker in one bulk subscription request or as individual requests.
SSL version	SSL Default version	Selects no TLS, the library default, TLS 1.0, TLS 1.1, or TLS 1.2.
Certificate	No connection security	Client certificate presented to the broker for mutual TLS.
Key	No connection security	Private key that matches the selected client certificate.
Server certificate	No server certificate	CA certificate used to validate the broker certificate.
Verify server CA	Yes	Verifies the broker certificate and hostname when a server CA certificate is selected.

Choose the subscription request mode

Bulk requests: Sends the configured topic filters in one request. This is more efficient and uses the QoS selected for each item.
Single requests: Subscribes to each topic separately. Use this when the broker does not accept bulk subscription requests.

Use Bulk requests unless the broker requires individual subscription requests.

Configure TLS

The Connector uses a plain TCP connection when the port is 1883. In this version, selecting certificates or an SSL version does not enable TLS on port 1883.

To use TLS:

Enter the broker's TLS port. Port 8883 is commonly used, but the broker can use another port.
Select SSL Default version or a TLS version supported by the broker.
Upload the broker CA certificate to the MQTT Connector's file area.
Select that CA certificate under Server certificate.
Keep Verify server CA set to Yes.
If mutual TLS is required, also select the client Certificate and matching Key.
Save the instance.

The hostname entered in Address must match the identity in the broker certificate when hostname verification is enabled.

Selecting an SSL version enables an encrypted connection, but the Connector only enables broker certificate verification when a Server certificate is selected.

Create an MQTT item manually

Open the MQTT instance.
Open its Items section.
Select Add item.
Enter a descriptive item name.
Select the required read and write direction.
Enter the MQTT topic or topic filter.
Select the required Retain and QoS settings.
Complete any standard item settings needed by the application.
Select Save.

The item direction determines how the Connector uses the topic:

Read: Subscribes to the topic and receives messages.
Write: Publishes values to the topic when the item receives data, normally through a mapping.
Read/Write: Subscribes to the topic and can also publish to it.

Item parameters

Parameter	Default	Description
Topic	`topic`	Exact MQTT topic used for publishing, or an exact topic or wildcard filter used for subscribing.
Retain	True	When publishing, asks the broker to store the message as the retained message for the topic. This setting does not change subscription behavior.
QoS	`0`	Requested MQTT delivery level for the topic.

The Connector transports received and published payloads as UTF-8 text. A received value is timestamped when SIA Connect receives it.

Use topic wildcards

Read and Read/Write items can subscribe with standard MQTT wildcard filters:

Wildcard	Meaning	Example
`+`	Matches one topic level.	`sensors/+/temperature`
`#`	Matches all remaining topic levels and must be the final level.	`factory/line1/#`

When a wildcard item receives a message, the returned data identifies the actual topic that matched the filter. This lets mappings use the concrete topic rather than only the configured wildcard.

Publish items should normally use an exact topic. The Connector also supports SIA Connect variable references in topic names when a mapping resolves the topic dynamically.

Understand QoS and retained messages

QoS	Delivery behavior	Consideration
`0`	At most once	Lowest overhead. A message can be lost and is not retried by MQTT.
`1`	At least once	Delivery is acknowledged, but duplicate messages are possible.
`2`	Exactly once	Highest protocol overhead. Use only when supported and required.

When Retain is enabled on a published item, the broker stores the latest retained message for that topic. New subscribers can then receive that retained value immediately. Disable Retain when messages should only represent live events.

Discover MQTT topics

MQTT brokers do not normally provide a topic catalogue. The Connector discovers topics by subscribing to a filter and listening for messages during a scan window. A topic only appears if the broker delivers a message for it while discovery is running.

Open the configured MQTT instance.
Select Discover items.
Enter a topic filter. Use a narrow filter such as factory/line1/# when possible.
Select the QoS used for the discovery subscription.
Set the scan duration shown by the Edge Portal.
Start discovery.
Publish or wait for messages on the topics you want to find.
Select the discovered candidates you want to import.
Import the selected items.
Review each imported item's name, direction, topic, QoS, retain setting, and standard item settings.

If the topic field is empty or still contains its placeholder value, discovery listens on #. Some brokers block broad wildcard subscriptions. A narrower topic filter is more likely to match the broker's access-control rules and reduces unnecessary traffic.

Discovery creates one read item candidate for each actual topic received. The candidate uses the text data type and includes the most recent sample received during the scan. Samples longer than 512 characters are shortened in the discovery result.

Verify the configuration

Confirm that the MQTT instance does not report a connection error.
For a Read item, publish a known test message to its topic from another authorized MQTT client.
Confirm that the value appears on the item in the Edge Portal.
For a Write item, create or use a mapping that sends a controlled test value to it.
Confirm with another MQTT client that the expected payload arrives on the configured topic.
If Retain is enabled, reconnect a test subscriber and confirm that the retained value is appropriate for the application.

Test writes only where changing the target topic cannot cause unsafe equipment operation or unintended automation.

Current Connector limitations

The Connector uses a clean MQTT session. Subscriptions are recreated after reconnecting rather than retained as a persistent broker session.
The Connector does not provide a setting for an MQTT Last Will message.
Only one QoS 1 or QoS 2 publish can be in flight at a time. Publishing another acknowledged message before the current one completes can report Max messages inflight.
In Connector version 0.2.0, regular instance operation uses a 60-second keep-alive interval even if another value is entered under Keep alive interval. Topic discovery reads the configured value correctly.
In Single requests mode, subscription requests use QoS 1. Use Bulk requests when the configured QoS for each item must be used.

Troubleshoot the MQTT Connector

Problem or message	Likely cause	Action
Failed to connect, Disconnected, or Server unavailable	The broker is stopped, unreachable, using another port, or blocked by routing or firewall rules.	Confirm the address and port. Check DNS, routing, firewall rules, and broker availability from the SIA Connect network.
Bad username or password	The credentials are incorrect or not accepted by the broker.	Re-enter the username and password. Confirm the account is active in the broker.
Not authorized or the topic is not authorized	The account cannot connect, publish, or subscribe to the requested topic filter.	Review broker ACLs and grant only the required topic permissions. For discovery, try a narrower filter such as `sia_connect/#`.
Identifier rejected	The client ID is invalid, already in use, or rejected by broker policy.	Enter a valid, unique Device ID / Client ID. Check whether another client is connecting with the same ID.
Unacceptable protocol version, Bad MQTT version, or Wrong MQTT version	The broker and client do not agree on a supported MQTT protocol version.	Confirm that the broker accepts the MQTT client version used by this Connector. Review broker listener and compatibility settings.
SSL not supported or the TLS connection fails	The port, TLS version, CA certificate, client certificate, private key, or broker hostname is incorrect.	Do not use port `1883` for TLS. Select a supported TLS version, the correct broker CA, and a matching client certificate and key when mutual TLS is required.
Bad protocol	The broker address or connection protocol is invalid.	Enter only the broker hostname or IP address in Address and verify the configured port and SSL settings.
Invalid UTF-8, Topic name truncated, or Invalid topic filter	The topic contains invalid text, is too long, or uses MQTT wildcards incorrectly.	Use a valid UTF-8 topic. Use `+` for one level and place `#` only at the end of a filter.
Bad QoS	The selected delivery level is invalid or unsupported for the operation.	Select QoS `0`, `1`, or `2`. Confirm that the broker permits the selected level.
Max messages inflight	A QoS 1 or QoS 2 publish is still waiting for acknowledgement.	Reduce the publish rate, use QoS 0 where suitable, or wait for the current acknowledged publish to complete.
Discovery returns no topics	No matching message arrived during the scan, the wildcard filter is blocked, or the account lacks subscription permission.	Publish a test message during the scan. Verify the topic filter and ACLs, increase the scan duration, or use a narrower filter.
A retained value appears immediately after subscribing	The broker already stores a retained message for the topic.	Confirm whether the retained value is expected. Publish an updated retained value or clear it using an appropriate MQTT client and broker procedure.
A Read item receives no data although the instance is connected	The topic does not match, the item is Write-only, or the subscription was rejected.	Check the exact topic and case, item direction, wildcard syntax, QoS, broker ACLs, and Connector logs.
A Write item does not publish	No value is reaching the item, the topic is incorrect, or the broker rejects the publish.	Verify the mapping and its trigger, item direction, resolved topic, instance status, and broker publish permissions.

If the problem continues, review the instance error and the system logs together. The MQTT return code normally identifies whether the failure concerns connectivity, authentication, authorization, TLS, the client ID, the topic, or QoS.

connector discovery mqtt qos retain tls topics troubleshooting

Contact Us