Skip to content

Connections

A connection profile is a named broker connection that Pub and Sub use by name. You can have as many profiles as you like, all connected at the same time, for example one per broker or one per site. Profiles are provided by Artek-MQTT-Common and managed on Artek MQTT → Connections in the gateway web interface, where the create and edit forms cover every setting, including username, password and TLS.

Profile settings

Setting What it does
Broker URLs One or more broker URLs. A URL with an out-of-range port (-1, 0, 65536) is rejected.
Server selection Use the brokers in order (sequential) or pick one at random.
MQTT version 5.0 (default) or 3.1.1.
Client ID The MQTT client id, with an optional automatic suffix.
Keep-alive The MQTT keep-alive interval.
Session MQTT 5: clean start and session expiry, set separately. MQTT 3.1.1: clean session.
Last Will Topic, payload, QoS, retain and, on MQTT 5, will delay.
Username / password Broker credentials, stored encrypted (see Security).
TLS See TLS.
MQTT 5 limits and properties Receive maximum (flow control), topic alias maximum, and user properties sent on connect.
Reconnect and timeout Reconnect backoff and connect timeout.
Store-and-forward See Store-and-forward.

Credentials in the broker URL

A broker URL may carry a username as user@host. It is parsed into the profile's credentials and masked when the profile is shown. If the explicit username or password fields are also set, they win. A password inside a URL (user:pass@host) is refused when you save: put it in the password field instead.

Editing a profile

  • A secret left blank in an edit keeps the stored one. The forms show secrets as a mask and never write that mask back over the real value.
  • Edits merge. A partial change keeps every field you did not send. The TLS block merges field by field, so re-sending TLS settings with blank secret fields keeps the stored key material.
  • Changing where a profile points clears its password. If you change the broker URLs or the TLS trust settings (TLS on/off, CA, hostname verification) without re-entering the password, the stored password is cleared rather than sent to the new destination. Re-enter it with the change.
  • Subscriptions survive edits. Subscribers keep receiving across any profile edit, and across deleting a profile and re-creating it under the same name.

Failover and reconnect

A profile with several broker URLs holds one active connection at a time. When the connection drops, it reconnects automatically and walks the broker list (in order, or at random if you chose that) until one answers.

Reconnect uses a backoff with a positive floor that resets once a session has been stable, so a flapping broker does not cause a reconnect storm. The connect timeout bounds each attempt.

TLS

Each profile supports full TLS and mutual TLS:

  • CA certificate (to trust the broker).
  • Client certificate and private key for mutual TLS, in PEM form; PKCS#1 and PKCS#8 keys are accepted, with an optional key password.
  • TLS version.
  • Hostname verification, on or off.

The client key and its password are stored encrypted and are never shown or logged (see Security).

Store-and-forward

Each profile has its own bounded store-and-forward queue on disk:

  • Messages published while the broker is unreachable are queued, up to a count and byte cap, with a drop policy for when the queue is full.
  • On reconnect the queue is flushed in order. A message leaves the queue only once it has been sent, and the queue is saved to disk atomically, so delivery is at-least-once (a message can occasionally arrive twice, but is not lost while it fits in the queue).
  • QoS 0 publishes are not buffered while disconnected. Use QoS 1 or 2 for data you need to keep.

The queue depth and counters appear in the connection status.

Connection status

Each profile's live status shows on its card on the Connections page and is available to scripts through system.artekmqtt.getConnectionStatus (see Scripting):

Field Meaning
state The connection state.
brokerInUse The broker currently connected.
connectedSinceEpochMs When the current connection started (epoch milliseconds).
reconnectAttempts Reconnect attempts made.
lastError The most recent connection error.
Store-and-forward counters Queue depth and related counters.

The status also reports the MQTT version negotiated with the broker.

Sparkplug and connection profiles

A Sparkplug edge node or host application uses a connection profile like everything else. Two behaviors are worth knowing:

  • Enabling or editing a Sparkplug edge node or host application on a profile that is already connected makes that profile reconnect once, so the session it announces itself on carries its death certificate as the MQTT Will. Expect one brief reconnect.
  • Disabling, deleting or re-pointing a profile at another broker first lets its edge nodes and host applications publish their death messages on the still-open session, then disconnects.

The very first connection after a gateway start already carries the correct Sparkplug Will, because the connection is made only after Pub and Sub have registered their Wills.

See Sparkplug B for when to give each Sparkplug edge node or host application its own profile.