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:

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:

  1. Set Name to MQTT Coreflux Source.
  2. Set Data source type to MQTT.
  3. Set MQTT connection to Coreflux Public.
  4. Set Topic filters (subscribe) to your topic (one line), for example routix/test/dash-yourname.
  5. 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.

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:

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:

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.

  1. The Lua action builds the JSON object.
  2. Trigger data destination publishes it to your topic.
  3. MQTT Coreflux Source receives the message and updates value.
  4. 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:

  1. Turn on Edit layout, tap the data piece, then tap its menu button → Edit.
  2. Under Data transformers pipe, tap Add... → Simple expression.
  3. 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:

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.