MQTT Connections

An MQTT connection subscribes to a topic on an MQTT broker and delivers messages to your widgets in real time. This is ideal for live sensor data, machine status updates, and other streaming data.

Setting up an MQTT connection

1. Go to Data Connections and click New Connection.
2. Select MQTT as the connection type.
3. Choose a data source config — the MQTT broker to connect to.
4. Enter the topic to subscribe to (e.g., factory/line-1/temperature).
5. Set the QoS (Quality of Service) level.
6. (Optional) Enter a JSONPath expression to extract a specific field from JSON messages.
7. Give the connection a name.
8. Click Save.

QoS levels

Level	Meaning	Use when
0	At most once — messages may be lost	High-frequency data where occasional loss is acceptable
1	At least once — messages may be duplicated	You need reliable delivery but can handle duplicates
2	Exactly once — guaranteed single delivery	Every message must be processed exactly once

JSONPath extraction

If your MQTT messages are JSON objects, you can use a JSONPath expression to extract a specific value. For example, if messages look like:

{ "sensor": "temp-1", "value": 72.5, "unit": "F" }

Setting JSONPath to $.value would extract just 72.5.

Using MQTT data in widgets

MQTT connections work differently from other connection types:

• getData("name") returns the last received message value. If no messages have arrived yet, it returns the most recent stored value.
• onSourceData("name", handler) subscribes to live updates. Your handler function is called each time a new message arrives:

onSourceData("Temperature Feed", (data) => {
  document.getElementById("temp").textContent = data.value + "°F";
});

For real-time displays, use onSourceData() instead of polling with getData().

Notes

• The MQTT broker must be accessible via WebSocket (ws:// or wss://). Standard TCP MQTT connections are not supported.
• MQTT subscriptions are active while the widget is displayed. When you navigate away from a dashboard, subscriptions are closed.
• If the broker requires authentication, the credentials are stored in the data source config (admin-managed).