MQTT

Connect to a broker

1. Press Ctrl+Shift+T and pick MQTT.
2. Type the broker, for example mqtt://10.42.0.5.
3. Press Enter.

The scheme sets the transport and its default port:

Address	Transport
mqtt://	TCP, port 1883
mqtts://	TLS, port 8883
ws://	WebSocket, port 80
wss://	WebSocket over TLS, port 443
user@machine	through the machine's SSH

A WebSocket connection uses the path /mqtt unless the address names another.

To reach the broker through a proxy or ProxyPass, set the Route of the connection. See Routes.

Reach a broker through SSH

Many brokers only listen on the machine they run on. Type user@machine and Vandle opens the machine's SSH connection first, then talks to the broker from there, at 127.0.0.1:1883. The SSH server has to allow TCP forwarding.

If the broker sits elsewhere as seen from the machine, set Broker as the machine sees it in the Edit connection dialog. The Transport field there switches between all five ways.

The sign-in for SSH is the machine's. The broker's own user and password are asked for on the first connect and kept with the entry.

Sign in and certificates

If the broker wants a user name and password, Vandle asks. A refused sign-in is asked for again: "The broker did not accept the user name or password."

When a TLS broker shows a certificate this computer does not trust, Vandle shows who it was issued to, by whom, how long it is valid and its fingerprint. Choose:

• Trust it for this broker to keep trusting this exact certificate.
• Trust just this once for this connection only.
• Cancel to stop.

If a trusted broker later shows a different certificate, Vandle warns you before it connects.

Choose what you listen to

By default the tab listens to #, every topic. To narrow it:

1. Click Listening to in the header.
2. Write one filter per line. + is one level, # everything below.
3. Click Apply.

For a saved broker, the list is kept with its entry.

The header also shows the broker, the messages per second (msg/s) and the number of topics.

Browse topics

The left side shows topics as a tree, with the last value, its age and how many messages arrived. R marks a retained message.

• Type in Topics and payloads… to search topic names and small payloads.
• All, Retained and Last minute filter the list. Last minute shows topics that spoke in the last minute.
• The collapse button folds the whole tree.

A search shows at most 1,000 topics. Narrow it to see the rest.

Read a topic

Click a topic. The right side shows:

• the path, with a button to copy it
• Last message, as JSON, Text or Hex. A value that changed shows its previous one ("was …").
• History: the last 500 messages of this topic, in memory only. Messages you sent are marked sent.
• Chart: click a number in the JSON payload and it is charted as new messages arrive.

A very large payload is not shown at first. Click Open anyway to see it.

Publish

The Publish box sits under the topic.

1. Fill in Topic and Payload.
2. Pick QoS 0, 1 or 2, and tick Retain if the broker should keep the message.
3. Click Publish, or press Ctrl+Enter.

Selecting a topic fills in its path. For devices Vandle recognises, ready-made buttons appear next to Publish, and the first one fills the form:

• zigbee2mqtt: Toggle, On, Off, brightness, Permit join 2 min
• Tasmota, Shelly and ESPHome: Toggle and their usual commands

These buttons only send when you click them.

Save a command

Type a name in Name to save this as and click Save. The command appears under Saved.

• Click it to send it.
• Right-click it for Fill in, do not send or Delete.

Saved commands are kept on the broker's sidebar entry, so pin the broker first.

Delete a retained message

Select the topic and click Delete retained. Vandle publishes an empty retained message, which removes it from the broker.

Clean up many retained messages

Clean up retained in the header finds old retained messages below a branch, such as Home Assistant's ghost entities. It starts at the branch of the topic in front, or at homeassistant.

Choose how far it goes:

• Stale only: something on the broker says the device is gone. zigbee2mqtt no longer lists it, or its availability says offline.
• Stale or silent: adds configs whose state topic has said nothing since the tab connected. Slow sensors land here too, so look before you remove.
• Everything below: every retained message under the branch.

Review the list. Click an entry to leave it out or take it in again, then click Remove with the count. Back to the tree leaves without removing anything.

MQTT keeps no dates, so age is never a reason on its own.

Record and export

Click Record, write the topics to record (one filter per line; # records everything) and click Start recording. Click the button again to stop. Discard throws the recording away.

Nothing is written to disk until you export. Export offers:

• Message log (CSV): the recording, or without one, the history of all topics.
• This topic, fields as columns (CSV): one column per JSON field of the selected topic.

A recording stops at 1,000,000 messages.

When the connection drops

Vandle reconnects by itself, after 2, 5, 10 and then every 30 seconds. A notice above the tree counts down. The tree, the history and a running recording stay.

If the tab has ended, press Ctrl+Shift+R or click Connect.

From a Docker tab

A Mosquitto, EMQX or HiveMQ container in a Docker tab has Open as MQTT next to its published port.

Keys can be changed in Settings, under Hotkeys.