.mqtt files

.mqtt files describe an MQTT session: the broker to connect to, topics to subscribe on connect, and publish / expect blocks to run interactively or scripted. The Explorer shows a live topic tree and message timeline.

Minimal example

@broker    = mqtt://broker.hivemq.com:1883
@client-id = sendpad-demo
@keepalive = 60

@subscribe sensors/# qos=0
@subscribe home/broadcast qos=1

### Publish — temperature reading
# @topic sensors/temp
# @qos 1
# @retain off
> { "temp": 22.5, "ts": "{{now}}" }

### Expect broadcast
# @expect topic = home/broadcast within 5000
< { "type": "announce" }

Press ⌘Enter to connect. Use the compose bar to publish ad-hoc messages, or ⌘⇧Enter to run all blocks sequentially as a scripted test.

Connection directives (file-level)

Directive	Description
`@broker <url>`	Broker URL — `mqtt://`, `mqtts://`, `ws://`, `wss://` (required)
`@client-id <id>`	Client ID (default: auto-generated)
`@username <u>`	Username
`@password <p>`	Password — reference `{{VAR}}` from `.env.local` for real credentials
`@keepalive <seconds>`	Keepalive interval (default 60)
`@clean-session on\|off`	Clean-session flag (default on)
`@will-topic <topic>`	Last-will topic
`@will-payload <string>`	Last-will payload
`@subscribe <topic> [qos=N]`	Subscribe on connect. Multiple allowed.

Wildcards + (single-level) and # (multi-level) are supported on every subscribe.

Message blocks

Each ### introduces a message block. Use > to publish and < to expect a received message.

Publish

### Announce
# @topic   device/alerts
# @qos     1
# @retain  off
> { "type": "boot", "version": "2.0.0" }

Expect

### Ack from broker
# @expect topic = device/acks within 3000
< { "ok": true }

Directive reference

Directive	Description
`# @topic <topic>`	Topic for the next publish (`>`)
`# @qos 0\|1\|2`	QoS for the next publish or subscribe
`# @retain on\|off`	Retain flag on the next publish
`# @expect topic = <pattern> within <ms>`	Wait for a message matching the topic pattern
`# @assert body contains <text>`	Assert on the received payload
`# @extract <var> = <jsonpath>`	Extract a value from the received message
`# @name <id>`	Name a step for the test report

QoS semantics

QoS 0 — at most once. Fire-and-forget. No acknowledgement, no retry.
QoS 1 — at least once. Broker acknowledges; message may arrive more than once.
QoS 2 — exactly once. Four-step handshake; slowest but duplicate-free.

Sendpad renders the QoS of each message inline in the timeline.

Retained messages

Messages published with @retain on are stored by the broker and delivered to any future subscriber of that topic as the first message after subscribe. The topic tree highlights retained messages with a pin badge and shows the retained payload even before your session began.

Topic tree UI

The Topic Tree groups incoming messages by topic — collapsible, with per-topic message counts. Click any topic to filter the timeline.

Device simulator (Pro)

Open Device Simulator from the .mqtt toolbar to publish fake data on a timer — great for demo dashboards and soak tests. Configure topic, QoS, payload template, and emit interval; leave running in the background.

Secure credentials

Put broker credentials in <env>.env.local (auto-gitignored). Sendpad masks .env.local-only values automatically:

@broker   = mqtts://broker.example.com:8883
@username = iot-device
@password = {{MQTT_PASSWORD}}

# prod.env.local — gitignored, never committed
MQTT_PASSWORD = your-real-password