Getting to know EMQX and the MQTT Broker

Why this matters

The Mosquitto built into Home Assistant is many people's first MQTT broker, but all it gives you is a bare-bones config file and scattered connection records. Once you have pushed dozens of sensors, switches and telemetry feeds through it, you start to need an admin interface that shows you at a glance who is online, who is subscribed, and whether messages are actually going out — and that is where EMQX earns its place.

This chapter starts with the MQTT broker model: why a publisher, a subscriber and a topic never need to know about one another, what part the broker plays between them, and what EMQX adds on top of those roles that a modern broker is expected to have. Chapters 2, 3 and 4 then take you through the install, the Dashboard, and building a mental model of MQTT.

Core concepts

MQTT (Message Queuing Telemetry Transport) is the lightweight messaging protocol most used in the Internet of Things. Instead of a client asking a server for data directly, it uses the publish/subscribe model: a publisher sends messages out sorted by topic, and a subscriber subscribes only to the topics it cares about; the server acting as the broker routes and filters every incoming message, then delivers it to every subscriber interested in that topic.

The relationship between the three is the point: publishers and subscribers are fully decoupled, neither needs to know the other exists, and the only thing they share is a topic agreed in advance. Add a sensor and you add a publisher; add a screen and you add a subscriber; no other endpoint has to change. EMQX supports MQTT 3.1, 3.1.1 and 5.0, and lets a web browser publish MQTT messages directly over WebSocket, which Mosquitto does not do by default.

EMQX is designed for high concurrency and high availability. It is built on the Erlang/OTP platform, uses a fully asynchronous architecture, and layers connections, sessions, routing and clustering separately, and it keeps sending and receiving messages separate from the Dashboard. That is why a single node can carry connections in the millions, and why several nodes can be joined into a cluster to scale out.

Terms at a glance

Hands-on

1. Check whether the add-on is running

   In Home Assistant's left sidebar, go to Settings → Add-ons and find Woow EMQX. If it is already installed, you will see it reported as running.

2. Open the Web UI

   Click Open Web UI on the add-on to open the EMQX Dashboard in your browser. If you cannot get in yet, go back to Chapter 2 and finish the install and start it.

3. Sign in with the default account and look around

   For the first login, use the username admin and the password public. You will be asked to change it to a password of your own; do that, then look over the main interface.

4. Find where the version is shown

   Locate the page in the Dashboard that shows the version and license information. Chapter 3 then walks you through the sidebar modules one by one.

EMQX compared with Mosquitto

If you are moving over from the Mosquitto built into Home Assistant, the first thing you will want to know is what actually differs. The Woow EMQX add-on README already carries a comparison table; here are the main points.

The conclusion is not that you have to replace Mosquitto today: if your host is tight on resources and all you need is a plain broker, Mosquitto is still very light. But if you want visual management, subscription diagnostics, a WebSocket test client, the Rule Engine and room to grow later, the moderate resource use of EMQX buys you noticeably more to work with.

EMQX 5.x architecture and clustering

EMQX 5.x separates the Dashboard from message processing: the Dashboard only gives you a visual way to work, and EMQX keeps sending and receiving messages whether or not the Dashboard is open. The engine that actually handles messages is a framework built on Erlang/OTP, designed in four layers — connection, session, route and cluster — which keeps the structure clear and makes it straightforward to scale out.

A cluster is how EMQX delivers high availability: several EMQX nodes make up a single broker service, so when one of them fails the MQTT service does not stop, and adding nodes raises the overall throughput. The add-on you are running defaults to a single node, which is enough, but understanding what a cluster is for gives you the mental model for where to expand once you have more devices.

In your actual setup, the EMQX version bundled with the Woow EMQX add-on is 5.8.9 (Open Source), while the add-on's own version is 5.9.0 — that 5.9.0 only adds the ngrok tunnel, and the underlying broker is still 5.8.9. Everything that follows is written against the facts and menu paths of 5.8.9.

Troubleshooting

• Still not sure what a broker does? Think of the broker as a post office or a router. The publisher writes the envelope (the topic) and drops the letter in, and the broker delivers it only to the recipients who subscribed to that envelope. Subscribers do not know the senders, and senders do not know the subscribers.
• Cannot find EMQX? First check that the add-on is installed and started. If you want to open the Dashboard on its own, Chapters 2 and 3 walk you through port 18083 and Ingress.
• Can Mosquitto and EMQX run side by side? Both use port 1883, so they cannot both be started. Chapters 2 and 8 cover how to handle that in their port conflict sections.
• Dashboard will not open? Check the add-on log for errors first, then make sure nothing else is holding port 18083. Tunnel and Ingress settings are covered in later chapters.

FAQ

Official sources

• Woow EMQX add-on README (pinned commit, includes the Mosquitto comparison)
• EMQX 5.8 Concept FAQ (pinned docs branch)
• EMQX 5.8 Feature FAQ
• EMQX 5.8 Feature Comparison (includes cluster specs)