Usage

MQTT Dev has three main workflows:

1. Broker administration in the Gateway web UI
2. Subscriptions authored in the Designer
3. Publishing from Jython scripting

---

Broker Administration (Web UI)

Manage broker connections at Connections → MQTT Dev → Brokers. Enabled brokers auto-connect on Gateway startup and stay in sync with configuration changes.

See Configuration → Broker Connections for the creation wizard, the fields, and the row actions.

---

Subscriptions (Designer)

Subscriptions are authored in the MQTT Dev section of the Project Browser in the Designer (shown in the brand color #660066). Each subscription editor provides:

• Enabled toggle
• Broker dropdown (lists configured brokers)
• Topic Filter field (wildcards + and # allowed)
• QoS combo (0 / 1 / 2)
• A Jython code editor with Gateway autocomplete

Handler Signature

The subscription handler must define an onMessage function with this signature:

def onMessage(topic, payload, qos, retained):
    # topic:    str  - the topic the message arrived on
    # payload:  str  - the message payload, UTF-8 decoded
    # qos:      int  - the message QoS (0, 1, or 2)
    # retained: bool - True if this was a retained message
    pass

Runtime Behavior

• Handlers run on the Gateway, on a worker thread pool.
• They are compiled and executed in the owning project's script context.
• Saving the project applies adds, edits, and deletes live — no Gateway or Designer restart is required.

Example Handler

def onMessage(topic, payload, qos, retained):
    logger = system.util.getLogger("MqttDev")
    logger.info("Received on %s (qos=%d, retained=%s): %s"
                % (topic, qos, retained, payload))

    # Example: write the payload into a tag
    system.tag.writeBlocking(["[default]Plant/Line1/LastMessage"], [payload])

Inbound handling is entirely your Jython

There is no Sparkplug B decoding, namespace parsing, or automatic tag-tree mapping. Topics and wildcards are plain MQTT 3.1.1, and any interpretation of the payload is done in your handler code.

Topic Filters and Wildcards

Topic filters use standard MQTT wildcards:

• + matches exactly one topic level (e.g. sensors/+/temp)
• # matches the remaining levels and must be the last character (e.g. sensors/#)

---

Publishing (Scripting)

Publish messages with system.mqtt.publish. The module ships Gateway and Designer scopes, so the function is available to:

• Gateway scripts — tag event scripts, gateway timer/message handlers, and Perspective scripts (Perspective runs on the Gateway), which call the broker directly.
• The Designer script console, which reaches the Gateway over an RPC proxy.

Not available in Vision client scope

The module has no client scope, so system.mqtt.publish does not exist in a Vision client script. To publish from a Vision window, call a Gateway-scope script — for example system.util.sendRequest to a gateway message handler that publishes.

Overloads

# qos=0, retained=False
system.mqtt.publish(broker, topic, payload)

# retained=False
system.mqtt.publish(broker, topic, payload, qos)

# full form
system.mqtt.publish(broker, topic, payload, qos, retained)

Parameters

Parameter	Type	Default	Description
broker	str	—	Name of a configured broker connection.
topic	str	—	Topic to publish to (no wildcards).
payload	str	—	Message payload; sent as UTF-8.
qos	int	0	Quality of Service: 0, 1, or 2.
retained	bool	False	Whether the broker retains the message.

The named broker must be configured and connected for the publish to succeed.

Examples

# Simple publish (QoS 0, not retained)
system.mqtt.publish("PlantBroker", "plant/line1/status", "running")

# QoS 1
system.mqtt.publish("PlantBroker", "plant/line1/count", "42", 1)

# Retained message at QoS 1
system.mqtt.publish("PlantBroker", "plant/line1/state", "IDLE", 1, True)

Round-trip pub/sub

Publish with system.mqtt.publish and receive with a Designer subscription's onMessage handler. Both use the same named broker connections, so a message published to a topic your subscription filter matches will be delivered to your handler.

---

Status Tags

Monitor broker connectivity with the system status tags:

[System] MQTT Dev/Brokers/<name>/Enabled   (Boolean)
[System] MQTT Dev/Brokers/<name>/Status    (String: Connected / Disconnected / Disabled)

These update every 2 seconds and can be bound in Vision/Perspective, used in expressions, or read from scripting.

You can also query status over REST: GET /data/mqttdev/brokers/status.

---

Reconnection

Broker connections use the Paho client's automatic reconnect. On reconnection, the module replays subscriptions so your onMessage handlers continue to receive messages without manual intervention.

Trial / license effects on connections

An expired trial drops broker connections; applying a license or resetting the trial triggers reconnection. See Installation → License and Trial.

---

Limitations

• MQTT 3.1.1 only — the bundled Eclipse Paho v3 client does not support MQTT 5.
• No Sparkplug B — no Sparkplug decoding or namespace/tag-tree auto-mapping.
• No dedicated TLS configuration — ssl:// / wss:// are accepted but rely on Paho/JVM defaults (no keystore/CA/client-cert fields).
• Plaintext password storage — broker passwords are stored unencrypted (see Configuration).

---

Troubleshooting

Issue	Possible Cause	Solution
Subscription never fires	Subscription not fully configured	Ensure it is enabled and broker + topic filter + handler code are all set
Subscription never fires	Broker not connected	Check the broker Status tag/badge
publish fails	Broker name wrong or not connected	Verify the broker name and its connection status
Broker connects then drops	Trial expired	Reset trial or apply a license
TLS connection fails	Certificate not trusted	Ensure the broker cert is trusted by the Gateway JVM's default trust store
Handler errors	Exception in onMessage	Check Gateway logs for the owning project's script errors