MQTT

Rostyman includes a full MQTT client for testing IoT devices, message brokers, and pub/sub systems. It supports connecting via all four MQTT transport schemes, publishing messages with configurable QoS and retain flags, managing topic subscriptions with wildcard support, and viewing all traffic in a real-time message log.

Opening an MQTT Tab

Click + New Tab and select MQTT, or open a saved MQTT connection from the sidebar. Each tab maintains its own connection, subscriptions, and message log independently.

Broker URL

Enter the broker URL in the address bar. Rostyman supports all four MQTT transport protocols:

Scheme	Description	Default Port
mqtt://	Standard unencrypted MQTT over TCP	1883
mqtts://	TLS-encrypted MQTT over TCP	8883
ws://	MQTT tunneled over WebSocket (unencrypted)	8080
wss://	MQTT tunneled over TLS WebSocket	8084

Examples:

mqtt://localhost:1883
mqtts://broker.example.com:8883
ws://broker.example.com:8080/mqtt
wss://broker.example.com:8084/mqtt
mqtt://broker.hivemq.com:1883

The path segment (e.g., /mqtt) is required by some brokers when using WebSocket transport.

Environment variables are supported anywhere in the URL using {{variableName}} syntax. They are resolved at connect time.

Connection Status Indicator

A colored dot sits at the left of the URL bar row:

Status	Color	Meaning
Disconnected	Gray	No active connection
Connecting	Amber	TCP handshake or MQTT CONNECT in progress
Connected	Green	CONNACK received, ready to publish and subscribe
Error	Red	Connection failed or closed unexpectedly

Environment Selector

The Environment dropdown in the URL bar row sets the active environment for the tab's collection. This controls which environment's variables are resolved in the URL, topic fields, and message payloads.

Connect and Disconnect

Click Connect to open the broker connection. Settings (client ID, credentials, keep-alive) are read at connect time. Changing settings while connected has no effect until you reconnect.

Click Disconnect (red, unplug icon) to cleanly close the connection. Active subscriptions are cleared from the Subscribe tab's active list when disconnecting. The message log is preserved.

---

Sub-tabs

Three sub-tabs appear below the URL bar:

Publish Tab

The Publish tab is the primary interface for sending messages to the broker.

Topic field

Enter the topic to publish to:

home/temperature
devices/sensor-01/status
v1/devices/{{deviceId}}/telemetry

Topics are case-sensitive hierarchical strings separated by /. Environment variables ({{variable}}) are resolved at publish time. The topic field is required — the Publish button is disabled until a topic is entered.

QoS selector

A dropdown selects the Quality of Service level for this publish:

QoS	Name	Behavior
0	At most once	Fire and forget. No acknowledgment from broker. Fastest, but messages may be lost on unreliable networks.
1	At least once	Broker acknowledges receipt (PUBACK). Guaranteed delivery, but duplicate messages are possible if the PUBACK is lost.
2	Exactly once	Four-step handshake (PUBLISH → PUBREC → PUBREL → PUBCOMP). Guaranteed delivery with no duplicates. Slowest but most reliable.

Retain checkbox

When Retain is checked, the broker stores the last message published to this topic. Any client that subscribes to the topic in the future will immediately receive the retained message upon subscribing, even if it was published long before they connected. Only the most recent message per topic is retained.

Message editor (Monaco)

A full Monaco editor fills the lower portion of the tab. It uses JSON syntax highlighting and supports:

• Syntax highlighting and bracket matching
• Line numbers and word wrap
• {{variable}} interpolation resolved at publish time
• Comments (stripped before sending)

Default message body:

{
  
}

Beautify Button

The ✨ Beautify button formats the JSON payload with 2-space indentation. This validates the JSON structure before publishing.

Publish Button

Click Publish to send the message. The button is disabled when not connected or when the topic is empty. Successful publishes appear in the Message Log as sent entries.

Subscribe Tab

The Subscribe tab manages topic subscriptions — the filters that tell the broker which messages to forward to this client.

Subscribing to a topic

Enter a topic filter in the input field, select a QoS level, and click Subscribe (or press Enter):

home/#
devices/+/status
sensors/temperature

The subscribe QoS level tells the broker the maximum QoS at which to deliver messages for this subscription. Messages published at a higher QoS are downgraded to the subscription's QoS.

Topic wildcards

MQTT supports two wildcard characters:

Wildcard	Level	Description	Example match
+	Single level	Matches exactly one topic level	devices/+/status matches devices/sensor-01/status but not devices/zone-a/room-1/status
#	Multi-level	Matches zero or more levels — must be the last character in the filter	home/# matches home/temperature, home/kitchen/light, and home

Active subscriptions list

Subscribed topics appear as a list below the input. Each row shows:

• The topic filter string
• The QoS level

Click the × button on a subscription to unsubscribe. Rostyman sends an MQTT UNSUBSCRIBE packet and removes the topic from the list. Messages for that topic will stop arriving immediately.

The Subscribe tab label shows the count of active subscriptions in parentheses, e.g., Subscribe (3).

Subscription state

Subscriptions are session-scoped. If you disconnect and reconnect, you must re-subscribe. Use the Subscribe tab to re-add your filters after reconnecting.

Settings Tab

The Settings tab configures connection parameters. All settings take effect on the next Connect.

Client ID

A unique string that identifies this client to the broker. If left empty, Rostyman generates a random UUID automatically.

rostyman-dev-001
my-sensor-client

Important: most brokers enforce unique client IDs. If two clients connect with the same ID, the broker typically disconnects the earlier connection. Auto-generation avoids this in most cases.

Client ID supports {{variable}} substitution, resolved at connect time.

Username

The broker login username. Leave empty if the broker does not require authentication.

Supports {{variable}} substitution.

Password

The broker login password. The field uses a masked input (characters are hidden). Leave empty if not required.

Supports {{variable}} substitution.

Keep Alive

The keep-alive interval in seconds. The MQTT client sends periodic PINGREQ packets to the broker to keep the TCP connection alive. If the broker does not receive a PINGREQ within 1.5 × keep-alive seconds, it disconnects the client.

Value	Behavior
60 (default)	Standard keep-alive, 60-second interval
0	Keep-alive disabled — no PINGREQ packets sent
Any positive integer	Keep-alive interval in seconds

---

Message Log

The Message Log appears at the bottom of the tab and shows all published and received messages in chronological order (oldest at top, newest at bottom). It auto-scrolls to the latest entry.

Filter Buttons

Filter	What it shows
All	Every log entry
Sent	Messages you published
Received	Messages received from subscriptions
System	Connection lifecycle events (connected, disconnected, subscribed, unsubscribed, errors)

Clear Button

The trash icon clears the log without disconnecting.

Message Rows

Each row displays:

Element	Description
Timestamp	HH:MM:SS when the entry was recorded
Direction icon	↑ (green) for sent, ↓ (blue/accent) for received, · (muted) for system
Topic	The MQTT topic the message was published to or received from (shown in accent color)
Payload	The message content, truncated with ellipsis if long, in monospace

The log retains the last 500 entries per session.

---

JSON Comments

You can include comments in your message payloads using // for single-line and /* */ for block comments. They are stripped before the message is sent — the broker receives valid JSON.

{
  // Current temperature reading
  "temperature": 22.5,
  /* Location identifier —
     matches the device registry */
  "location": "kitchen"
}

---

Saving to a Collection

Press Ctrl+S (or Cmd+S on macOS) to save the MQTT connection.

• New tab — the Save As dialog appears. Choose a collection, optional folder, and a name.
• Saved tab — the Save button highlights when there are unsaved changes.

What is persisted:

• Broker URL (with variable placeholders intact)
• Settings (client ID, username, password, keep-alive interval)
• Current publish topic, payload, QoS, and retain state
• Subscribe tab's most recent topic input and QoS selection

Active subscriptions and the message log are session-only and are not saved.

---

Tips

• Use mqtt://broker.hivemq.com:1883 or mqtt://test.mosquitto.org:1883 as a quick public test broker that requires no authentication
• Subscribe to # (the root wildcard) to capture every message on the broker — useful for exploration but can be very noisy on busy brokers
• QoS 0 is the right choice for high-frequency sensor telemetry where occasional message loss is acceptable; use QoS 2 for commands or configuration changes where delivery guarantees matter
• The retain flag is useful for "last known state" topics — a new dashboard subscriber immediately sees the device's current state without waiting for the next publish
• Store broker hostnames, ports, credentials, and device IDs in environments and use {{variable}} in the URL and settings — switch between development and production brokers by just changing the active environment