Broker API System Connector
Overview
The Broker connector is the primary MQTT publish/subscribe connector - it auto-publishes tag changes across all other connectors to the broker (topic-per-tag), handles inbound command topics that map to local tags, and supports TLS in addition to plain TCP. Like the generic MQTT connector, it has no polling loop of its own - all of its periodic work (connection monitoring, reconnection, and the heartbeat) runs inside a single dedicated background loop.
The connector detects when the broker connection is lost and reconnects automatically without blocking - reconnection runs on its own dedicated background thread, and an explicit disconnect is issued before every reconnect attempt to avoid MQTTnet's own "not allowed to connect while connect/disconnect is pending" race. Connection state checks use the connector's own tracked status rather than MQTTnet's IsConnected property, which is documented as unreliable immediately after a reconnect (see MQTTnet#2180).
Every MQTT operation (connect, publish, disconnect) is bounded by a 10-second timeout, so a broker that accepts a connection but never acknowledges it can't stall this connector indefinitely - since Broker publishes are processed by a single thread shared across every configured broker, an unbounded stall on one broker would otherwise back up publishing for all the others too. Connect and publish operations that take 3 seconds or longer are logged to %DEBUG (codes 280/285 below) even when they eventually succeed, so a broker that's merely slow - not yet timing out - is still visible before it becomes a real problem.
Like every connector, this one carries a %HEARTBEAT tag (see the System Tags reference) that toggles roughly every 5 seconds regardless of connection state, confirming its background reconnect-monitoring loop is still alive and running even during an extended outage.
Parameters
| Name | Values | Description |
|---|---|---|
| Type | BROKER | The connector type identifier. |
| Address | IP address or hostname | The MQTT broker's address. |
| Port | integer | The broker's MQTT port. |
| ClientId | string | The MQTT client identifier to connect with. |
| Username / Password | string | Broker credentials, if required. |
| Certificate / CaCert / CertPassword | file path / string | Client certificate, CA certificate, and certificate password for a TLS connection. |
| Version | MQTT protocol version | The MQTT protocol version to connect with (e.g. v3.1.1 or v5.0.0). |
| QOS | 0, 1, or 2 | The default Quality of Service level for publishes. |
| Retain | true/false | Whether published messages are retained by the broker. Defaults to true unless explicitly set to false. |
| Persistent | true/false | Whether to request a persistent (non-clean) session from the broker. |
| Indented | true/false | Whether published JSON payloads are pretty-printed. Defaults to true unless explicitly set to false. |
Supported Tag Types:
Every MQTT payload is plain text, so there's no DataType disambiguation needed - the raw payload string is passed straight to each tag's own SetValue, and the tag type itself (BoolTag/IntTag/DecimalTag/StringTag/etc.) handles its own coercion.
| Tag Type | Address | Behaviour |
|---|---|---|
| Any standard tag | An MQTT topic, matched case-insensitively | Subscribed on connect; updated whenever a message arrives on that topic. |
Connector Methods
| Name | Arguments | Description |
|---|---|---|
| PublishTag | Tag, Payload | Publishes a specific tag's current value/payload to its topic on demand. |
| Redirect | (arbitrary command payload) | Publishes an arbitrary command payload to the engine's redirect topic, for cross-instance command routing. |
| Monitor | Name, Payload | Publishes program/monitor data for a named item, e.g. for debug tooling. |
| ResetTag | Name, Value | Sets a tag's value directly, without going through MQTT. |
Addressing
The Address field of a tag is the literal MQTT topic to subscribe to. Command-style writes (PublishTag/Redirect/Monitor) are only available via RunMethod rather than through a polled tag.
Diagnostic Codes
| Code | Type | Description |
|---|---|---|
| 1200 | Error | Ping failed — MQTT communication error during the periodic connection check |
| 1225 | Error | Error handling a received MQTT message (e.g. malformed payload) |
| 1250 | Error | User certificate file missing at the configured path |
| 1255 | Error | Failed to load or apply the user certificate |
| 1265 | Error | Default certificate file missing at the configured path |
| 1270 | Error | Failed to load or apply the default certificate |
| 1400 | Error | Unable to apply an incoming MQTT value to a tag — format could not be parsed |
| 1510 | Error | RunMethod called with an unrecognised method name |
| 1520 | Error | RunMethod threw an unhandled exception |
| 2205 | Debug | Setting up the MQTT client with no authentication |
| 2210 | Debug | Setting up the MQTT client with authentication and TLS |
| 2215 | Debug | Setting up the MQTT client with authentication, no TLS |
| 2220 | Debug | Message received on a subscribed topic |
| 2235 | Debug | Successfully subscribed to a tag's topic |
| 2240 | Debug | A tag configured for subscription has an empty Address |
| 2245 | Debug | HandleConnection event fired |
| 2246 | Debug | isConnected transitioned to true - Connected event about to fire |
| 2247 | Debug | isConnected transitioned to false - ConnectionLost event about to fire |
| 2260 | Debug | Connecting using the default certificate |
| 2280 | Debug | A tag publish took 3 seconds or longer to complete (still succeeded - this is an early-warning timing flag, not a failure) |
| 2285 | Debug | Reconnecting to the broker (ConnectAsync) took 3 seconds or longer to complete |
| 3100 | Info | Connector started |
| 3201 | Info | Broker client connecting |
| 3202 | Info | Client connection re-established |
| 3230 | Info | Reconnecting after a failed ping |