Make your first MQTT connection
Make your first MQTT connection: publish and subscribe with the built-in WebSocket test client on the EMQX Diagnose page, verify QoS, and learn the basic moves of connecting and subscribing.
Why this matters
Your add-on already has EMQX 5.8.9 running, but you have probably never watched an MQTT message travel through the broker with your own eyes. Chapter 4 built the mental model on paper; this chapter is the first-contact step that fills the gap. Use the WebSocket test client built into EMQX to publish and subscribe straight from the browser: send a message, take it back on the same connection, and see for yourself how the QoS levels differ when the message is delivered.
By the end you will have the fastest way to answer "is the broker actually working?" — no third-party program to install, not one line of code to write, and you can still verify how connections, topics, payloads and QoS behave. Every later chapter that tests against a live instance comes back to this WebSocket client.
Core concepts
MQTT works by publish/subscribe: a publisher sends a message on a topic, a subscriber subscribes only to the topics it cares about, and the broker in the server role routes every message. The most direct way to check that is to open both ends — publish on one, subscribe on the other — and see whether the broker delivers the message to the right subscriber.
EMQX gives you several tools for this: the desktop client MQTTX, the command-line MQTTX CLI, the browser build MQTTX Web, and the WebSocket Client built into the EMQX Dashboard. The first three all have to be installed or kept in mind somewhere else; the built-in one does not. It speaks MQTT over WebSocket, connects on port 8083 by default, and does all three actions — connect, subscribe and publish — right there in the page, which makes it the right choice for your first test tool.
Terms at a glance
| Term | Plain English | In one line |
|---|---|---|
| Publish | send a message | Send a message to a topic |
| Subscribe | ask for a topic | Declare which topics you want messages from |
| Topic | message address | The hierarchical name that classifies a message |
| Payload | message body | The data a publish actually carries |
| QoS | delivery guarantee | How strongly message delivery is guaranteed (0/1/2) |
| Retained | last message kept | The broker remembers the last message and a new subscriber receives it at once |
| WebSocket | browser transport | The transport that lets a browser speak MQTT |
Hands-on
Open the WebSocket client
Log in to the EMQX Dashboard (if you changed the username and password in Chapter 2, use your own). In the left menu, click Diagnose → WebSocket Client.
Make the first connection
In the Connection block, leave Host as
localhost(if you are coming in from another device, change it to your Home Assistant address) and Port as8083; leave Username and Password empty while no authentication is set up yet. Click Connect, and when the status turns to Connected you are through.Subscribe, then publish
In the Subscription block, set Topic to
testtopic/#and click Subscribe. Then in the Publish block set Topic totesttopic/1, fill Payload with{"msg":"Hello"}, start with QoS0, and click Publish. The same message shows up in the Received area below, because you are the subscriber as well.Verify QoS
Change the Publish QoS to
1(or even2), send another message, and watch it reach Received just the same. Get a feel for what "QoS 0 best effort, QoS 1 at least once, QoS 2 exactly once" means for real delivery, then read the "Verify QoS" topic below for where each of the three fits.
A tour of the WebSocket test client
The Diagnose menu holds a few debugging tools: Alarms, WebSocket Client, Topic Monitoring, Slow Subscriptions and Log Trace. Of those, Alarms, Topic Monitoring and Slow Subscriptions only exist in the paid EMQX Enterprise edition, so on Open Source 5.8.9 the two you will really use are WebSocket Client and Log Trace — do not spend time hunting the Open Source interface for items only Enterprise has.
WebSocket Client covers three stages — connect, subscribe, publish — and also shows what you sent (Published) and what came back (Received). Click + to open several WebSocket connections at once, each independent of the others. One behavior to keep in mind: refreshing this page clears every connection and all the sent and received data — it is a quick test tool, not a place to keep connection history.
One more trap to watch for: the Topic in the Publish block cannot carry the + or # wildcards; only a Subscription topic may use wildcards.
Verify QoS
QoS (Quality of Service) is the MQTT mechanism that controls how strongly the delivery of a single message is guaranteed. EMQX supports all three QoS levels at both ends, and you can pick one for both the subscription and the publish in the WebSocket client.
| QoS | Name | Guarantee | Typical use |
|---|---|---|---|
| 0 | At most once | No guarantee of delivery, and none against duplicates | Periodic sensor readings, where dropping one does no harm |
| 1 | At least once | Delivery guaranteed, but it may arrive twice | State changes where a repeat or two is acceptable |
| 2 | Exactly once | Delivery guaranteed, and never duplicated | Switches and control commands, where a repeat is not allowed |
The cheapest way to test is to publish to a topic you subscribe to yourself: when the publisher and the subscriber are the same end, the broker still routes the message back across, so the Received rows let you confirm with your own eyes whether the same message comes back after a QoS change and whether it arrives twice. To verify retained messages as well, tick Retain when you publish and a new subscriber immediately receives the last message on that topic — retained and QoS are two separate things, and Chapter 4 already built that mental model.
Troubleshooting
- Connect does nothing, or keeps failing: first check whether another service (WebRTC, for example) has taken 8083 — the same kind of port conflict as in Chapter 2. If you are coming in from another device, Host has to be the Home Assistant host address, not
localhost. - You subscribed but nothing arrives: check that your subscription topic covers the publish topic with a wildcard (only a subscription to
testtopic/#matchestesttopic/1). After a successful publish the Received area should hold a row; if there is not a single one, the broker did not actually route the message. - The same message arrives more than once: QoS 1 guarantees at-least-once delivery, so a duplicate is possible. Choose QoS 2 when you need exactly one copy, and do not read a possible repeat as a broker fault.
- Everything disappears after you refresh the page: that is the built-in WebSocket client clearing itself by default, not a bug. If you need to keep connection history or several saved setups, switch to the desktop MQTTX tool; that is what suits ongoing testing.
FAQ
How does the built-in WebSocket client differ from MQTTX?
The built-in client lives inside the EMQX Dashboard, needs no install and is the fastest way to glance at messages. MQTTX (desktop, CLI and web) does more: it saves several connections and supports finer MQTT 5.0 settings, which suits ongoing debugging and development. Both talk to the broker the same way, so there is no rule that you must use one of them.
Why does the test use 8083 rather than 1883?
The built-in client is the channel where the browser runs MQTT over WebSocket right in the page, and that goes over 8083. 1883 is plain TCP MQTT, which a browser cannot open directly; to reach 1883 you need a tool such as the desktop MQTTX or the CLI. Both are MQTT — only the transport layer differs.
Which of QoS 0, 1 and 2 should I actually choose?
Pick 0 for data you can afford to drop, 1 for data that must go out but may repeat, and 2 for critical control that must not repeat, such as a switch. Publish once at each of the three first, look at the difference in what you receive on the same connection, then choose by your real situation.
Can the tool hold several connections at once?
Yes. Click + to open several WebSocket Clients at the same time, each with its own connection state and its own sent and received rows. If you want to simulate one publisher and one subscriber, it is easier to open two connections and use one for subscribing and the other for publishing.