MQTT
The MQTT page lets you connect GEM to one or more MQTT brokers. You can publish GEM device, zone, and variable attribute changes to MQTT topics, subscribe to external MQTT topics to update GEM attributes automatically, browse the broker's full topic tree, and bind individual topics to GEM zones.
Connection Selector
At the top of the page is a Connection dropdown. Each connection corresponds to a GEM device with the mqtt driver.
- Select an existing connection to edit it. The dropdown shows the connection name and broker host.
- Select <New Connection> to create a new MQTT connection.
- The status indicator shows whether the connection is currently Connected or Disconnected.
- Reload restarts the MQTT driver to apply configuration changes.
- Delete permanently removes the connection.
Tabs
The page has five tabs: Settings, Publish, Subscribe, Explorer, and Messages.
Settings Tab
The Settings tab configures the MQTT broker connection across four sections.
Connection
| Field | Description |
|---|---|
| Name | Internal name for this connection (auto-formatted to lowercase_with_underscores). |
| Enabled | Toggle to enable or disable this connection. |
| Host | Hostname or IP of the MQTT broker. Include port if non-standard (e.g., broker.mqtt.com:8883). |
| Protocol | Transport protocol: mqtt, mqtts, wss, ws, tcp, ssl. |
| Username | Optional broker username for authentication. |
| Password | Optional broker password for authentication. |
Mode
| Field | Description |
|---|---|
| Protocol Mode | Standard MQTT, Sparkplug B — Edge Node, or Sparkplug B — Primary Host. Changing this on a saved connection triggers an automatic reconnect. |
| Sparkplug Version | Sparkplug spec version. Read-only — GEM speaks spBv1.0 (the only released Sparkplug version). |
| Group ID | Logical grouping for Sparkplug edge nodes (e.g., site_main). +, #, /, and whitespace are stripped on blur. |
| Edge Node ID | Unique identifier of this edge node within the group (edge mode only). Same character restrictions as Group ID. Leave blank to default to the GEM server hostname (slugified). |
| Subscribe Groups | Comma-separated group IDs to consume in host mode. Blank subscribes to all groups. |
In Standard MQTT mode, GEM publishes attribute changes to configurable topic templates with JSON payloads.
In Sparkplug B — Edge Node mode, GEM acts as a Sparkplug Edge Node. The driver manages the spec's topic namespace, sequence numbers, and birth/death certificates automatically:
NBIRTHis published on connect- Target objects are grouped into three logical Sparkplug devices —
zones,devices, andvariables— and the hierarchy lives in the metric path instead (e.g. a zone attribute publishes as<subsystem>/<zone>/<attribute>, a device attribute as<device>/<attribute>). This keeps Ignition's tag browser organized as a tree rather than hundreds of flat sibling devices. - Attributes are published as DDATA metrics encoded in Sparkplug B protobuf
DBIRTHis sent with current values for each device on connect or rebirthNDEATHis registered as the broker's LWT, so disconnects are signalled automatically- Incoming
DCMD/NCMDmetrics are first matched against your subscription rules by metric name. When no rule matches, an auto-resolver reverse-parses the metric path back to the GEM entity and dispatches the write — zone control metrics (state,level,volume, setpoints,color, …) go through the command engine,sourceroutes to the AV zone, and writable config attributes are set directly. Telemetry metrics (sensors, meters, battery, panel state) are refused so a controller can't write a read-only value.
In Sparkplug B — Primary Host mode, GEM consumes data from external Sparkplug edge nodes. The driver subscribes to spBv1.0/[group]/# (or all groups), decodes incoming Sparkplug payloads, and routes metrics into GEM attributes via subscriptions.
TLS
| Field | Description |
|---|---|
| Use TLS | Toggle to enable TLS/SSL encryption. When enabled, certificate fields appear. |
| Verify Server | When enabled, rejects connections to brokers with untrusted certificates. Disable for self-signed certs. |
| CA Certificate | Paste the PEM-encoded Certificate Authority certificate. |
| Client Certificate | Paste the PEM-encoded client certificate (for mutual TLS). |
| Client Private Key | Paste the PEM-encoded client private key (for mutual TLS). |
Paste certificate content directly into the text fields (including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers). Do not upload files.
Advanced
| Field | Description |
|---|---|
| Reconnect (ms) | Time in milliseconds between reconnection attempts. Default: 5000. |
| Keepalive (s) | MQTT keepalive interval in seconds. Default: 60. |
| Clean Session | When enabled, the broker discards any previous session state on connect. Default: on. |
Last Will and Testament
The Last Will and Testament (LWT) is a message the broker publishes automatically if GEM disconnects unexpectedly. In Sparkplug modes the LWT is auto-managed (Sparkplug NDEATH) and the configurable fields are hidden.
| Field | Description |
|---|---|
| Will Topic | The MQTT topic for the LWT message (e.g., GEM/status/offline). |
| QoS | Quality of Service level for the LWT message. |
| Will Payload | The message body (e.g., {"status": "offline"}). |
| Retain | When enabled, the broker retains the LWT message for new subscribers. |
Click Save to create or update the connection.
Publish Tab
The Publish tab configures which GEM data gets published to MQTT topics when attribute values change.
Publication Settings
| Field | Description |
|---|---|
| System Target | What type of GEM object to publish: device, zone, or variable. |
| Target Objects | Multi-select list of specific objects to publish. Choose individual items or select All (now and future) to automatically include objects created later. |
| Topic Template | The MQTT topic pattern used when publishing. Tokens in square brackets are replaced with actual values at publish time. (Standard mode only.) |
| QoS | Quality of Service for published messages: 0 (at most once), 1 (at least once), 2 (exactly once). (Standard mode only.) |
| Retain | When enabled, the broker retains the last published message on each topic. (Standard mode only.) |
In Sparkplug B — Edge Node mode, topic template / QoS / retain are hidden. Selected targets are grouped into the zones / devices / variables Sparkplug devices, and a Resolved Topic preview shows the spec-derived topic (spBv1.0/[group]/DDATA/[edge]/[device]) along with a sample path-shaped metric name. If the Edge Node ID is left blank, the preview shows <hostname> to reflect the runtime default. Outbound payloads and birth/death messages are handled by the Sparkplug protocol stack.
Available Tokens
Click any token button to append it to the Topic Template field:
| Token | Description |
|---|---|
[subsystem] | The subsystem name of the target object (e.g., lighting). |
[system_target] | The object type: device, zone, or variable. |
[target_id] | The numeric ID of the target object. |
[target_name] | The name of the target object (e.g., living_room_lights). |
[attribute] | The name of the attribute that changed (e.g., level, state). |
[hostname] | The hostname of the GEM server. |
Topic Preview
Below the template field, a live preview shows an example of what the resolved topic would look like with sample values.
Configured Publications
A summary table at the bottom shows all configured publications for the current connection, including the target type, topic template, number of selected objects, and QoS level.
Click Save to store the publication. Click Delete to remove it.
When you select "All (now and future)" as the target object, GEM will automatically publish attribute changes for any new objects of that type created after the publication is saved.
Subscribe Tab
The Subscribe tab lets you create subscriptions that listen for messages on MQTT topics and write their values into GEM attributes.
Subscription Form
| Field | Description |
|---|---|
| MQTT Topic / Metric Pattern | In Standard mode: an MQTT topic with + (single level) or # (multi-level) wildcards. In Sparkplug modes: a metric-name pattern matched against incoming Sparkplug metrics. Forms include metric_name, device/metric, group/edge/device/metric (host mode), and * / + / # wildcards. |
| System Target | The type of GEM object to update: device or variable. Zones are not a subscribe target — bind a topic to a zone from the Explorer tab's Map to zone button (the zone's address is the single inbound path for zone topics, so the driver routes them automatically). |
| Target Object | The specific object to update. The list populates based on the selected system target. |
| Attribute | Which attribute on the target object to update. Select < Create New > to define a new attribute name. |
| QoS | Quality of Service for the subscription. |
| Active | Toggle to enable or disable this subscription without deleting it. |
| Value Transform | Optional JavaScript expression to transform the incoming MQTT value before storing it. |
Value Transform
The value transform field accepts a JavaScript expression that is evaluated for each incoming message. Available variables:
| Variable | Description |
|---|---|
value | The incoming MQTT payload, parsed as JSON if possible, otherwise as a string. |
topic | The MQTT topic string the message was received on. |
message | The raw message string (before JSON parsing). |
Examples:
value * 1.8 + 32— Convert Celsius to FahrenheitJSON.parse(message).temperature— Extract a nested fieldvalue > 50 ? 'high' : 'low'— Conditional mappingMath.round(value * 100) / 100— Round to 2 decimal places
Subscriptions Table
Below the form, a table shows all subscriptions for the current connection with columns for topic, target, attribute, QoS, and status. Each subscription has action buttons:
| Button | Description |
|---|---|
| Enable / Disable | Toggle the subscription active or inactive. |
| Edit | Load this subscription into the form for editing. |
| Delete | Remove this subscription (with confirmation). |
When a variable is selected as the system target, the target objects list shows attribute names instead of numeric IDs, since variables are stored as global attributes.
Explorer Tab
The Explorer tab is a live, hierarchical view of every topic on the broker. While the tab is open it auto-subscribes to # (re-arming automatically if the broker reconnects) and builds a topic tree from all inbound traffic, including retained values. It is read-only exploration plus clear-retained — the persistent bridge rules still live on the Publish and Subscribe tabs. (Unavailable in Sparkplug Edge mode, where the node only publishes.)
Toolbar
| Control | Description |
|---|---|
| Live / Idle / Disconnected | Status dot reflecting whether traffic is being captured. |
| Filter | Substring filter across topic names and payloads; matching branches auto-expand. |
| Pause / Resume | Stop or resume folding new messages into the tree. |
| Expand / Collapse | Expand or collapse the whole tree. |
| spB metrics | Appears once Sparkplug traffic is seen. Toggles between exploding Sparkplug payloads into one browsable leaf per metric (Ignition tag-browser style) and showing the raw spB envelope topic. Both representations are kept, so toggling is instant and lossless. |
| Clear | Empty the captured tree. |
| Stats | Live topic count, total message count, and messages/second. |
Topic Tree and Inspector
The pane splits into a topic tree (left) and a payload inspector (right); drag the divider to resize (double-click to reset, arrow keys when focused). Each topic node shows a payload preview plus R (retained), Q (QoS), and message-count badges; aggregate branches show topic and descendant message counts.
Select a topic to inspect it. The inspector shows direction, retain/QoS/Sparkplug/binary badges, message count, and last-seen time, and renders the payload in auto, json, raw, hex, or base64 format (binary payloads always fall back to a hex dump). A Recent values list shows the last several values for the topic. Buttons copy the topic or payload, and Clear retained publishes an empty retained payload to wipe a retained message.
Map to Zone
Selecting a non-Sparkplug-metric topic shows a Map to zone button. This binds the topic to a GEM zone so its payloads drive a zone attribute:
- Existing zone — pick a zone; its
device_idandaddressare set to this connection and topic. - New zone — create a zone (name + subsystem) already bound to the topic.
- Zone attribute to set — which attribute the payload writes to (default
state). - Value transform — optional JavaScript expression (
value,message,topic) applied before storing, same as a subscription transform.
Mapped topics show a green indicator with the bound zone and target attribute, plus edit and unmap links. The driver routes zone topics automatically by address and re-routes whenever a zone is reloaded, so mappings take effect without reconnecting.
Messages Tab
The Messages tab provides a real-time view of MQTT traffic and tools for manual testing.
Message Log
The message log shows published and received messages in real time.
- Click Start to begin capturing messages, Stop to detach, Pause / Resume to hold the view without unsubscribing, and Clear to empty the log.
- JSON / CSV export the current (filtered) log to a downloaded file.
- The filter box narrows the log to topics or payloads matching a substring.
Each entry shows:
- Time — Timestamp with millisecond precision.
- Dir — Direction: IN (received) or OUT (published).
- Flags — QoS badge, R for retained, and spB for decoded Sparkplug B messages.
- Topic — The MQTT topic.
- Payload — The message content (binary payloads are flagged with their byte length; Sparkplug payloads are decoded to readable metric JSON).
The log retains up to 500 messages.
Publish
Send a test message to any MQTT topic. Disabled in Sparkplug Edge mode — all outbound traffic flows through the spB protocol stack.
| Field | Description |
|---|---|
| Topic | The topic to publish to. |
| QoS | Quality of Service level. |
| Retain | Whether the broker should retain this message. |
| Payload | The message body. |
| Format | How the payload is encoded: raw (UTF-8 as-is), json (validated before send), hex (e.g. 0a 1b ff — published as binary), or base64 (decoded and published as binary). |
- Save preset stores the current topic/payload/format under a name for reuse (presets persist in the browser and appear as clickable chips).
- The Recent sends dropdown reloads a previously published message.
Test Subscriptions
Subscribe to one or more topics for testing. Enter a topic and QoS and click Subscribe; active test subscriptions appear as chips with an unsubscribe ×. These are ephemeral — they are for live testing and are not saved (use the Subscribe tab for persistent bridge rules). Disabled in Sparkplug Edge mode — edge nodes publish only.
Related Documentation
- Devices — Creating the MQTT device
- Attributes — Understanding GEM attributes
- Triggers — Automating based on attribute changes