MQTT Distributor Module - Usage and Configuration

After installing MQTT Distributor, you can configure the MQTT server settings and create one or more user accounts for MQTT clients. Below, you'll also find various references for tables, tags, and custom properties.

Configure the MQTT Server

The Connections tab on the left hand navigation menu contains the global MQTT server settings.

Enable MQTT Distributor

1. Under Connections, navigate to MQTT Distributor → Settings.
2. Under the Distributor Settings tab, verify that Enable MQTT Distributor is selected.
3. Click Save Changes if any modifications are made.

Configure Network Connections

MQTT Distributor supports both standard and secure client connections.

Non-TLS Connections

Setting	Description	Default
Enable TCP	Enables standard MQTT TCP connections.	Enabled
Port	MQTT TCP listening port.	1883
Enable Websocket	Enables MQTT over WebSocket connections.	Enabled
Websocket Port	MQTT WebSocket listening port.	8090

TLS Connections

TLS encrypts communication between MQTT clients and MQTT Distributor.

Before enabling TLS, upload a valid SSL certificate to Ignition.

Setting	Description	Default
Enable TLS	Enables secure MQTT connections.	Disabled
Secure MQTT Port	MQTT TLS listening port.	8883
Enable Secure Websocket	Enables secure MQTT WebSocket connections.	Disabled
Secure Websocket Port	Secure MQTT WebSocket listening port.	9443

TLS Certificate Updates

Prior to MQTT Distributor 4.0.30, changes made to Ignition SSL certificates are not automatically detected while TLS is enabled. This can prevent MQTT clients from reconnecting after certificate updates.

If this occurs:

• Restart the MQTT Distributor module, or
• Save any change to the MQTT Distributor configuration.

MQTT Distributor 4.0.30 and later automatically detect certificate updates when running on Ignition 8.1.41 or newer.

Advanced Settings

Setting	Description
Allow Anonymous MQTT Connections	Allows clients to connect without a username and password. Disabled by default.
Custom Properties	Reserved for advanced configuration. Do not modify unless directed by Cirrus Link support.

Create MQTT Users

MQTT clients authenticate using user accounts configured on the Users tab.

1. Navigate to Config → MQTT Distributor → Users.
2. Create a new user or edit an existing user.
3. Configure the username, password, and access permissions.

User Settings

Setting	Description
Username	Username supplied by MQTT clients when connecting.
Password	Password supplied by MQTT clients when connecting.
ACLs	Access Control Lists that define which topics the user can publish to and subscribe to.

Default User

MQTT Distributor creates a default user during installation:

Setting	Default Value
Username	admin
Password	changeme
ACL	RW #

⚠️ Important: Change the default password before deploying MQTT Distributor in a production environment.

Further Configuration

After configuring MQTT Distributor, you can:

1. Create user accounts for your MQTT clients.
2. Configure Access Control Lists (ACLs) to restrict topic access.
3. Configure MQTT Engine, MQTT Transmission, or other MQTT clients to connect using the configured credentials.

---

Tags

MQTT Distributor automatically creates a set of tags that provide status information and control functions for the module. These tags are organized into the Distributor Control and Distributor Info folders, respectively.

📁 Distributor Control

The Distributor Control folder contains tags used to control MQTT Distributor behavior.

Tag Name	Data Type	Description
Enabled	Boolean	Controls whether MQTT Distributor is enabled. This tag is writable.

📁 Distributor Info

The Distributor Info folder contains tags that provide information about MQTT Distributor and connected MQTT clients.

Tag Name	Data Type	Description
Connected Clients	Integer	The number of MQTT clients currently connected to MQTT Distributor.
Keep Inactive Clients	Boolean	Controls whether inactive clients are included in the Distributor Info tags. This tag is writable. Available in MQTT Distributor 4.0.18 and later.
MQTT Clients *	Dataset	Contains information about connected MQTT clients. Available in MQTT Distributor 4.0.18 and later. See the dataset structure below.
Total Clients	Integer	The total number of clients that have connected since the last MQTT Distributor restart. Available in MQTT Distributor 4.0.18 and later.

* MQTT Clients Dataset

The MQTT Clients dataset contains one row for each client and includes the following columns:

Column Name	Data Type	Description
ClientId	String Array	MQTT client identifier.
Username	String Array	Username used to connect to MQTT Distributor.
IP Address	String Array	Client IP address.
Connected	Boolean Array	Indicates whether the client is currently connected.
Last Connect Time	DateTime Array	Timestamp of the client's most recent connection.
Last Disconnect Time	DateTime Array	Timestamp of the client's most recent disconnection.

---

Custom Properties

⚠️ Custom properties should only be added after consultation with the CirrusLink support team

maxOutboundQueueSize

The maxOutboundQueueSize custom property allows you to configure the maximum outbound message queue size used by MQTT Distributor.

Available in MQTT Distributor 4.0.21 and later.

To configure this property:

1. Navigate to MQTT Distributor > General.
2. Expand the Advanced section.
3. Enter the following JSON in the Custom Properties field:

{
  "maxOutboundQueueSize": 32768
}

Replace 32768 with the desired queue size.

Verify the Configuration

After saving the configuration, verify that the property was applied by reviewing the Ignition Gateway logs.

Look for a message similar to the following from the com.cirruslink.chariot.server logger:

Server 08Jan2024 14:37:41 maxOutboundQueueSize: 32768

If this message appears in the logs, MQTT Distributor has successfully applied the configured queue size.