Connect an MQTT broker

Connect an MQTT 3.1.1 broker to Synnax, with its authentication, TLS, and Sparkplug B settings.

The MQTT integration reads values from and sends commands to any MQTT 3.1.1 broker, such as Mosquitto, EMQX, HiveMQ, or the broker of a cloud IoT service. Topics carry JSON payloads or bare values. The read task records topics, the write task publishes commands, and Sparkplug B tasks talk to SCADA systems.

MQTT tasks run inside the Synnax Core, not in a Driver. The Core uses the rack “Node 1”, and it runs MQTT tasks wherever the Core runs, Docker included.

Prerequisites

An MQTT broker that accepts MQTT 3.1.1 connections.
A Core that can reach the broker on the network. Synnax Desktop runs one for you.

Connect a broker

In the devices toolbar, click (Connect device), then select MQTT broker. You can also run the “Connect an MQTT broker” command.
Enter a name for the broker.
In Host, enter the address of the broker, such as broker.example.com. Leave Port empty for the default.
In Connect from, keep Node 1. The Console selects it for you.
Under Authentication, enter a Username and Password if the broker needs them.
Under Security, turn on TLS if the broker uses it. See TLS.
Click Connect.

The Console tests the connection before it saves the broker. The test waits up to 10 seconds. If the test fails, the dialog shows the error and keeps your entries.

import synnax as sy

rack = client.racks.retrieve(integration=sy.mqtt.INTEGRATION, one=True)
broker = client.devices.create(
    sy.mqtt.Device(
        name="Plant broker",
        host="broker.example.com",
        username="synnax",
        password="my-password",
        rack=rack.key,
    )
)

Python does not test the connection. The Core checks it within 5 seconds, and the device status shows the result.

TLS

Turn on TLS when the broker uses TLS. The default port then changes from 1883 to 8883.

CA file -> the certificates of the authority that signed the certificate of the broker. Empty uses the system roots.
Client certificate and Client key -> a client certificate, for a broker that asks for one.
Skip verification -> accepts any certificate from the broker.

Each file is a path on the computer that runs the Core, not on the computer that runs the Console. In code, the fields are ca_file, cert_file, and key_file.

Turn on Skip verification only for a broker with a self-signed certificate on a network that you trust. A CA file with the certificate of your own authority is safer.

Connection settings

Setting	Default	Notes
Host `host`		Address of the broker. Stored as the device `location`.
Port `port`	1883	1 to 65535. 8883 when TLS is on.
Client ID `client_id`	Empty	Empty uses an ID made from the device. See below.
Keep alive `keep_alive`	30 s	1 to 65535 seconds.
Connect from `rack`	Node 1	The rack of the Core.
Username `username`	Empty	Empty connects with no user.
Password `password`	Empty
TLS `secure`	Off	See TLS.
Skip verification `verification_skipped`	Off	Shows when TLS is on.
CA file `ca_file`	Empty	A path on the computer of the Core.
Client certificate `cert_file`	Empty	A path on the computer of the Core.
Client key `key_file`	Empty	A path on the computer of the Core.
Host ID `host_id`	Empty	See host application ID.
Groups `groups`	All	Sparkplug B groups to browse, separated by commas.

The device stores the Sparkplug B settings as sparkplug.host_id and sparkplug.groups.

A broker allows one connection for each client ID. If you set Client ID, make sure that no other client uses the same value, or the two clients disconnect each other.

Broker status

The Core checks each broker every 5 seconds and shows the result as its status in the devices toolbar:

Broker connected -> the Core reached the broker.
Failed to reach broker -> the Core did not reach the broker. The description gives the reason.

All tasks of one broker share one connection. The connection opens when the first task starts and closes when the last task stops. If it drops, the Core connects again on its own and subscribes to each topic again. While the connection is down, the tasks of the broker keep running and show a warning.

To change the settings of a broker, right-click it and select Edit connection. The Console tests the connection again before it saves.

Troubleshooting

Failed to reach broker
Cause
The Core cannot connect to the broker. The description gives the reason.
Fix
1. Check Host and Port.
2. Match TLS to the broker. A TLS broker often listens on port 8883.
3. Check the Username and Password, and the access rules of the broker.
broker is not connected
Cause
A task runs, but the connection to the broker is down. The Core connects again on its own, and the warning clears when the connection returns.
The connection to the broker drops again and again.
Cause
Two clients use the same Client ID.
Fix
Clear Client ID, or give each client its own ID.

For other problems, see Troubleshoot hardware.

Previous in Modbus

Write task

Read task