// mqtt

MQTT

Connect to an MQTT broker over a persistent backend connection, subscribe to topics, and publish messages — all from a request tab, with a live transcript of the traffic.

What It Does

  • Connects to plaintext (mqtt://, default port 1883), TLS (mqtts://, default port 8883), or bare host:port brokers
  • Subscribes to a topic, including wildcards like sensors/#
  • Publishes messages to a topic, optionally as retained messages
  • Supports QoS 0, 1, and 2 for the subscription and published messages
  • Optional client ID (auto-generated when blank), username, and password
  • Configurable keep-alive interval, clean or persistent sessions, and a Last Will message
  • Shows binary payloads safely — non-UTF-8 messages appear base64-encoded with their byte size; messages up to 64 MB are accepted
  • Resolves {{variables}} in topics, client ID, credentials, and payload
  • Keeps the password in the OS keychain — it is not written to the collection files or the saved tab state
  • Live status indicator with a received-message count and an incoming-message flash
  • Transcript of published and received messages with topics and timestamps; retained messages are marked retained

Connecting

  1. Enter the broker URL — mqtt://broker.example.com, mqtts://… for TLS, or host:port
  2. Optionally set a client ID, username, and password under Connection & Auth
  3. Click Send — the status indicator goes live once connected. Sending again with the same connection settings reuses the open connection; changing the broker, credentials, subscription, session, Last Will, or TLS options reconnects
  4. Use the Disconnect button in the MQTT panel to close the connection

Connection Options

  • Keep-alive (s) — seconds between keep-alive pings, 0–65535 (default 60). 0 disables keep-alive
  • Clean session (on by default) — turn it off for a persistent session: the broker keeps your subscriptions and queued QoS 1/2 messages while you are disconnected. A persistent session needs a fixed Client ID

Last Will

The Last Will section sets a message the broker publishes on your behalf if the connection drops unexpectedly — useful for testing presence or “device offline” handling.

  1. Enter a Will Topic — leaving it empty sends no Last Will
  2. Enter the Will Payload and choose the Will QoS
  3. Tick Retain will to have the broker keep the will message as the topic’s retained value

The will payload is stored like the password — in the OS keychain, not in collection files.

Subscribing

  1. Enter a topic filter, e.g. sensors/temperature or sensors/# for a wildcard
  2. Choose the QoS level
  3. Click Send — matching messages stream into the transcript as they arrive

Publishing

  1. Enter the target topic
  2. Enter the payload in the body editor
  3. Tick Retain to ask the broker to keep the message as the topic’s last known value for future subscribers
  4. Click Send — the message is published on the open connection

Troubleshooting

Cannot connect

  • Check the scheme and port — 1883 for mqtt://, 8883 for mqtts://
  • Verify credentials, and that the broker accepts your client ID
  • “A persistent session (clean session off) needs a fixed Client ID” — enter a client ID or turn Clean session back on

No messages received

  • Confirm the topic filter actually matches the published topics
  • Check that the subscription QoS is acceptable to the broker

Next Steps