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 General tab contains the global MQTT server settings.
Enable MQTT Distributor
- Navigate to Config → MQTT Distributor → General.
- Verify that Enabled is selected.
- 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.
- Navigate to Config → MQTT Distributor → Users.
- Create a new user or edit an existing user.
- 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:
- Create user accounts for your MQTT clients.
- Configure Access Control Lists (ACLs) to restrict topic access.
- 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:
- Navigate to MQTT Distributor > General.
- Expand the Advanced section.
- 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.