Your first connection#

This chapter walks you through connecting MQTT.fx to a broker for the first time — either as a quick ad-hoc connection or using a saved connection profile — and explains the feedback the connection bar gives you while connecting, after connecting, and when something goes wrong.

Before you start#

You need a broker to connect to: a broker running on your own machine, a broker on your network, or a public or cloud test broker. You will need its address (hostname or IP) and port.

MQTT brokers commonly listen on:

• 1883 — plain (unencrypted) MQTT
• 8883 — MQTT over TLS

A plain connection on port 1883 is the simplest way to make your first connection. For encrypted or authenticated brokers, see TLS and security and Authentication.

The connection bar#

The connection bar runs across the top of the main window. It is where you choose what to connect to, start and stop the connection, and see the current connection status. It has two modes, switched with the toggle button at its left edge:

• Profile mode (document icon) — connect using a saved connection profile.
• Ad-hoc mode (lightning-bolt icon) — type a broker address and port and connect immediately, without saving a profile.

To the right of the connect controls, the bar shows a status indicator and — once connected — small badges describing the live connection (see After you connect).

Quick connect: an ad-hoc connection#

Use an ad-hoc connection for a fast, throwaway test against a broker.

1. Click the mode toggle to switch to ad-hoc mode (the lightning-bolt icon).
2. Enter the Broker Address. The Port field defaults to 1883; change it if needed (it accepts digits only).
3. Click Connect, or press Enter in either field.

An ad-hoc connection uses default connection options: a randomly generated client ID, MQTT 5.0, no TLS, and no authentication. It is saved under the name Ad-Hoc Profile.

Watch out: because an ad-hoc connection has no TLS and no credentials, it only succeeds against a broker that accepts anonymous connections on the port you gave. If your broker requires TLS or a username/password, create a connection profile instead.

Connect using a saved profile#

For anything you will connect to more than once — and for any broker that needs TLS or authentication — use a connection profile.

1. Make sure the mode toggle is in profile mode (the document icon).
2. Pick a profile from the drop-down list. (To create or change one, click the gear button — Edit Profiles — next to the list. See Connection profiles.)
3. Click Connect.

The Connect button stays disabled until a profile is selected. The profile you last used is remembered and reselected the next time you start MQTT.fx.

While connecting#

When you start a connection, the status line shows Connecting, a progress indicator spins, and a Cancel button appears next to it. Click Cancel to abort a connection attempt that is taking too long (for example, a wrong address or an unreachable broker).

The round status indicator on the bar reflects the connection state:

After you connect#

On a successful connection the status line clears, the indicator turns green, and the connection bar shows badges describing the live connection:

• Security — a lock icon if the connection uses TLS, or an unlock icon if it does not.
• MQTT version — MQTT 3 or MQTT 5, matching the version actually used.
• Authentication — an icon appears when the connection uses a username/password; its tooltip shows the user name.
• Last Will — an icon appears when the profile has a Last Will & Testament; its tooltip shows the will topic.

While connected, the profile selector and Edit Profiles button are locked, and the Disconnect button becomes available.

To end the connection, click Disconnect. MQTT.fx disconnects cleanly and saves your configuration. (A clean disconnect does not trigger the profile's Last Will message — see Connection profiles.)

When a connection fails#

If the connection cannot be established, the status indicator turns red and the status line shows the reason reported by the connection attempt.

Common causes:

• Wrong address or port — the broker is unreachable on that host/port.
• TLS required — the broker expects TLS but the profile has it disabled (or vice versa). See TLS and security.
• Authentication required or rejected — the broker needs valid credentials. See Authentication.
• Blocked by a firewall or proxy — the connection cannot leave your network. See the proxy settings in TLS and security.

The Log contains more detail than the status line and is the best place to look when the reason is not obvious.

If the connection drops#

If an established connection is lost (for example, the network goes down or the broker restarts), MQTT.fx reports it in the status line:

• With Auto Reconnect enabled on the profile, it shows Broker connection lost: Retrying… and attempts to reconnect.
• Without Auto Reconnect, it shows Broker connection lost: Resetting client. and stays disconnected until you connect again.

Enable Auto Reconnect in the profile's general options for connections you want MQTT.fx to restore automatically.

Tips and caveats#

• Start with a plain connection on port 1883 to confirm reachability, then layer on TLS and authentication once the basic connection works.
• If you get a "client already connected" style rejection, the broker may already have a client with the same Client ID — generate a new one in the profile.
• Use ad-hoc mode to probe a broker quickly; promote it to a saved profile once you know the connection works.

Related#

• Connection profiles
• TLS and security
• Authentication
• Publish and subscribe
• Logging and debugging
• Troubleshooting