Connect to a station MQTT broker¶

This page explains how to open the MQTT applet and connect AetherSDR to a station MQTT broker so you can subscribe to topics, view incoming messages, publish canned payloads, and monitor message publication confirmations.

Before you start¶

Your MQTT broker is running and reachable from the machine running AetherSDR.
You know the broker's hostname or IP address, port, and credentials (if any).
AetherSDR was built with MQTT support (HAVE_MQTT). If the MQTT tray button is absent, your build does not include this feature.

Steps¶

If the applet panel is not visible, click View > Applet Panel to show it.
Click the MQTT tray button on the right sidebar. The MQTT applet opens.
Click Settings... in the MQTT applet header. The MQTT Settings dialog opens.
In the Connection tab, enter the broker hostname or IP address in the Host field. Default is localhost.
In the Port field, enter the broker TCP port. Default is 1883. Valid range: 1–65535.
If the broker requires authentication, enter your credentials in the User and Pass fields. Both are optional and may be left blank. The password is stored in the system keychain.
In the Topics field, enter a comma-separated list of topics to subscribe to. Leave blank if you only need to publish. To also overlay a topic's value on the panadapter, prefix it with *. Example:
```
*rotator/pos, *ant/selected, station/log
```
If the broker requires TLS, check the TLS checkbox. The port field switches automatically from 1883 to 8883. If you need a custom CA certificate, enter the file path in the CA cert field that appears. Leave CA cert blank to use the system CA bundle.
Configure publish buttons in the Publish Buttons tab if desired.
Click OK to save settings and close the dialog.
Click Enable (currently showing "Off") to connect. The button label changes to "On" and settings are saved.
Watch the status label to the right of the button. It reads "Connected" in green when the broker accepts the connection.

What each control does¶

Control	Description	Default
Settings...	Opens the MQTT Settings dialog (MqttSettingsDialog) for broker connection, subscriptions, and publish button configuration.	New in v26.5.3. Replaces the inline Host/Port/User/Pass/TLS/Topics fields.
Publish buttons	Up to 12 configurable buttons; click publishes the configured payload to the configured topic.	Configured via MqttSettingsDialog Publish Buttons tab.
Message log	Displays received messages as `topic: value` lines and published messages as `TX topic: payload` lines. Also processes antenna alias updates from MQTT.	Capped to 50 entries.
Enable	Connects (On) or disconnects (Off); saves all settings on connect. Password is loaded from system keychain on first enable.	Off
Status label	Shows connection state with colour: green when connected, grey when disconnected, default on error.	Disconnected

Tips¶

Settings are saved to persistent storage only when you click OK in the MQTT Settings dialog, not when you click Enable to connect.
The CA cert field and its label are hidden when TLS is unchecked. Check TLS first to make the row appear.
The Message log keeps the last 50 message blocks. Older entries are dropped automatically. Both received and published messages appear in the log. Published messages are prefixed with TX (e.g., TX topic: payload).
Publish buttons are only active while connected. See Add or remove custom publish buttons to configure them.
If the system keychain password is not yet loaded, the status label shows "Waiting for keychain" until the password is retrieved.

Troubleshooting¶

Status label shows an error message instead of "Connected" — The broker refused the connection or is unreachable. Verify the Host, Port, and credentials. If TLS is enabled, confirm the broker is listening on port 8883 and the CA certificate path is correct.
Status label shows "Waiting for keychain" — The password has not yet been loaded from the system keychain. Click Enable again or restart the applet.
MQTT tray button is absent — AetherSDR was built without MQTT support. You need a build compiled with the HAVE_MQTT flag.
Port did not switch when I checked TLS — The auto-switch only triggers if the current port value is exactly 1883 (switching to 8883) or 8883 (switching to 1883). If you had entered a custom port, it is left unchanged.
Topics field accepts input but no messages appear — Confirm the broker is publishing to the exact topic strings entered. MQTT topic matching is case-sensitive.