Get started: MQTT
This tutorial builds a small dashboard that subscribes to an MQTT topic and shows each incoming message on a data piece. You'll create a shared MQTT connection to the Coreflux public broker, an incoming MQTT data source, and a tap action that publishes a test message to the same topic — so you can see updates without an external MQTT tool.
The public broker at iot.coreflux.cloud needs no account. Everyone connected to the public broker can see every message on it — pick a topic that's unique to you, so you don't clash with other people following this tutorial, and don't send anything private.
The Coreflux public broker can disconnect often. Routix Dash reconnects automatically, but you might briefly see a disconnected status dot or miss a message while the link is down. That's normal for a free public test broker — for a stable connection, use your own MQTT broker.
Before you begin
You need one data section on the home screen. If you already completed Get started: HTTP GET, reuse that section; otherwise create one (Add data section manually on the empty home screen, or from the menu).
Pick a subscribe topic for this tutorial. It must be unique to you — replace yourname in the example below with something only you would use (your initials, a nickname, or a random id). If you reuse the example topic as-is, other people following this tutorial can see your messages and publish to your subscription.
routix/test/dash-yourname
Use the same topic everywhere below: in the connection, the source filter, and the destination's publish topic.
1. Create an MQTT connection
Open the menu (top-right) → MQTT connections → Add MQTT connection.
On the New MQTT connection screen:
- Name —
Coreflux Public - Host —
iot.coreflux.cloud - Port —
1883 - Transport — TCP
- Use TLS — off
- Protocol version — MQTT 3.1.1 (default)
- Authentication — leave username and password empty (the public broker allows anonymous access)
Leave Keep-alive (s), Connection timeout (s), and advanced settings at their defaults.
Tap Test in the top-right (next to the save tick) to check that the broker is reachable. A sheet shows Connecting… and then Connected successfully. once it succeeds. You don't need to save first.
Tap the save tick in the top-right.
See Data sources (incoming) — shared connections.
2. Create an MQTT data source (subscribe)
Open the menu → Data sources → Add data source, or start from Add data piece → Data source → Add data source.
On the "New data source" screen:
- Set Name to
MQTT Coreflux Source. - Set Data source type to MQTT.
- Set MQTT connection to
Coreflux Public. - Set Topic filters (subscribe) to your topic (one line), for example
routix/test/dash-yourname. - Leave Subscription QoS at QoS 0 – At most once.
Tap the save tick in the top-right.
While at least one data piece uses this source, the connection stays open, and each message published to your topic updates value. The source row shows a connected status dot when the broker link is up.
3. Add a data piece
On an empty section, tap Add data piece manually or Ask AI assistant to add data piece. Or turn on Edit layout, tap Add at the top, then Add data piece. In the library, pick Design your own data piece.
- Data source —
MQTT Coreflux Source(already selected if you came from step 2)
Set MQTT Coreflux Source as the data piece root data source. Add a Label — it inherits that source.
Until the first message arrives, the Label may be empty or show a loading state. Set Touches on the Label to Capture so tap actions in later steps run when you tap that Label — even if it is still empty.
Tap the save tick in the top-right.
4. Create an MQTT data destination (publish test message)
To exercise the source from inside the app, add an outbound publish on the same connection and topic.
Open the menu → Data destinations → Add data destination.
On the "New data destination" screen:
- Name —
MQTT Coreflux Publish - Type — MQTT
- MQTT connection —
Coreflux Public - Publish topics — the same topic as step 2 (for example
routix/test/dash-yourname) - Leave Publish QoS and Retain at their defaults.
Tap the save tick in the top-right.
See Data destinations (outgoing) for the full list of MQTT publish options.
5. Build the message with Lua
On the home screen, turn on Edit layout, tap the data piece, then tap its menu button and choose Edit.
Select the Label, then open Events → On tap and tap Add... → under Data actions, choose Lua.
Enter a short script that returns a JSON-friendly Lua table:
return {message = "Hello from Routix Dash", at = os.date("%H:%M:%S")}
Each tap builds a fresh timestamp in the at field. The app turns the Lua table into JSON when it publishes.
See Lua for the tap names (value, raw, ctx).
6. Trigger the MQTT publish
Tap Add... → under Data actions, choose Trigger data destination.
Set:
- Data destination —
MQTT Coreflux Publish - Text to send — leave it empty so the app sends the current value (the Lua table from the Lua action)
MQTT publishes don't return a response to the tap actions. The message arrives back through your MQTT data source subscription instead.
Save the data piece.
Your tap actions, in order:
| Category | Action | Role |
|---|---|---|
| Data actions | Lua | Builds {message, at} as JSON to publish |
| Data actions | Trigger data destination | Publishes it to your topic on Coreflux Public |
7. Tap the Label on the dashboard
Back on the home screen, tap the Label. Tapping elsewhere on the data piece does nothing.
- The Lua action builds the JSON object.
- Trigger data destination publishes it to your topic.
MQTT Coreflux Sourcereceives the message and updatesvalue.- The data piece shows the decoded JSON (for example
{"message":"Hello from Routix Dash","at":"14:30:05"}).
Tap again to publish another message with a new at time.
8. Show one field (optional)
Showing the whole JSON is rarely what you want. To display just the message text:
- Turn on Edit layout, tap the data piece, then tap its menu button → Edit.
- Under Data transformers pipe, tap Add... → Simple expression.
- Enter
value?.message.
Save the data piece. The data piece now shows Hello from Routix Dash instead of raw JSON.
MQTT details about the message itself — topic, QoS, retain — are available in transformers as ctx.transport, for example ctx.transport.topic in Expressions or Lua. See JSONPath for the full list of fields.
Test from an external tool (optional)
You can also publish to your topic from another MQTT tool (for example MQTT Explorer or mosquitto_pub) while Routix Dash stays subscribed:
mosquitto_pub -h iot.coreflux.cloud -p 1883 -t "routix/test/dash-yourname" -m '{"message":"External client","at":"12:00:00"}'
Replace the topic with yours. The data piece updates as soon as the broker delivers the message.
Connection diagnostics
If the data piece stays empty or shows an error:
- Open MQTT connections →
Coreflux Publicand check the connection log (you should see a successful connect entry). - On the "Data sources" screen, confirm
MQTT Coreflux Sourcehas a green status dot. - Confirm the topic filter exactly matches the publish topic (MQTT topics are case-sensitive).
- The public broker is shared — if nothing updates, make sure you're publishing to the same topic you subscribed to.
- If the status dot flickers or shows disconnected, open the connection log — reconnect entries mean the app is restoring the link. Frequent drops on Coreflux are expected; use your own broker to avoid them.
What you built
| Part | Role |
|---|---|
| MQTT connection | Shared link to iot.coreflux.cloud |
| MQTT data source | Subscribes to your topic; each message updates value |
| MQTT data destination | Publishes a test message on tap |
| Data piece | A Label shows the latest message (the whole JSON, or just the message text after step 8) |
| Lua | Builds the message to publish on each tap |
| Trigger data destination | Sends the current value to the broker |
Next steps
This tutorial uses a reusable destination so other data pieces can publish the same way. For a publish that belongs on this component only, use MQTT send instead. Topics and Text to send can include {{ value?.field }} when the tap runs.
- Get started: WebSocket send and receive — shared connection and echo server
- Get started: HTTP GET — incoming HTTP data and transformers
- Data sources (incoming) — MQTT subscribe options, trigger modes, and
ctx.transport - Data destinations (outgoing) — MQTT publish QoS, retain, and MQTT 5 fields
- Tap actions — richer publish chains and multiple destinations