Dozens of sensors, and no way to look at any of them

Mosquitto gives you a bare-bones config file and connection records scattered through a log. That is genuinely enough while you have five devices and you remember all five of them.

It stops being enough at the point where you cannot answer a simple question without guessing. Which of these three questions have you already asked yourself out loud?

Every one of those is a question about state you cannot see. An admin interface that shows who is online, who is subscribed, and whether messages are going out is where EMQX earns its place next to Home Assistant.

This part does two things. First it builds the model — publisher, subscriber, topic, broker — because everything in the eight parts after this one is a variation on those four words. Then it installs the thing. Part 2 takes you round the Dashboard and into MQTT proper.

Three parts that never have to know about each other

MQTT stands for Message Queuing Telemetry Transport. It is the lightweight messaging protocol most used in the Internet of Things, and the reason it caught on is a single design decision: a client does not ask a server for data.

Instead it uses the publish/subscribe model. A publisher sends messages out sorted by topic. A subscriber subscribes only to the topics it cares about. The server in the middle — the broker — routes and filters every incoming message and delivers it to every subscriber interested in that topic.

The relationship between the three is the whole point. Publishers and subscribers are fully decoupled. Neither needs to know the other exists. The only thing they share is a topic agreed in advance.

That decoupling is what makes the system cheap to grow. Add a sensor and you have added a publisher. Add a screen and you have added a subscriber. No other endpoint has to change, and nothing has to be told about the new arrival.

It also explains the one failure that catches everybody once. A topic is a hierarchical name, agreed in advance — living-room/temperature reads as a room, then a reading inside it. Nothing enforces that agreement. If the sensor publishes to living-room/temperature and Home Assistant subscribes to livingroom/temperature, both sides are working perfectly and nothing arrives, because as far as the broker is concerned those are two unrelated topics with no subscribers in common. No error appears anywhere. Part 2 goes into how topic names are built and matched; for now, take the silence seriously.

flowchart LR
  P1["A temperature sensor
publishes to the topic
living-room/temperature"] --> B["EMQX, the broker
routes and filters
every message
that arrives"]
  P2["A second sensor,
added next month,
publishes to its own topic"] --> B
  B --> S1["Home Assistant,
subscribed to
living-room/temperature"]
  B --> S2["A browser page over
WebSocket, subscribed
to the same topic"]

Two capabilities are worth naming this early, because they come up constantly later. EMQX supports MQTT 3.1, 3.1.1 and 5.0, so an older device that only speaks 3.1.1 and a new one that speaks 5.0 can sit on the same broker. And it lets a web browser publish MQTT messages directly over WebSocket, which Mosquitto does not do by default. That second one is why the Dashboard can carry a working test client you can publish from without installing anything.

What the extra resources actually buy you

If you are moving over from the Mosquitto built into Home Assistant, the first thing you want is a straight comparison. The Woow EMQX add-on README carries one; these are the main points from it.

Read the bottom two rows together, because on their own each one is misleading. “Millions” is not a number your house will ever need. “Moderate” resource use is a real cost you pay every day. Nobody installs EMQX at home for the connection ceiling.

The honest conclusion is the one the source draws: you do not have to replace Mosquitto today. It is still very light, and if all you need is a plain broker it is still enough. But if you want visual management, subscription diagnostics, a WebSocket test client, the Rule Engine, and room to grow later, the moderate resource use buys you noticeably more to work with.

The Dashboard is not the broker

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. That layering is why a single node can carry connections in the millions, and why several nodes can be joined into a cluster to scale out.

One separation in 5.x matters more than the rest for anyone running this at home. EMQX 5.x separates the Dashboard from message processing. The Dashboard only gives you a visual way to work. EMQX keeps sending and receiving messages whether or not the Dashboard is open.

flowchart LR
  L1["Connection
the socket a device opens"] --> L2["Session
who this client is and
what it subscribed to"] --> L3["Route
which subscribers this
topic has to reach"] --> L4["Cluster
one node here, more
nodes if you add them"]
  DASH["The Dashboard, port 18083
a visual way to work"] -.-> L2
  DASH -.-> L3

What a cluster is, and why you do not need one

A cluster is how EMQX delivers high availability: several EMQX nodes make up a single broker service. When one of them fails, the MQTT service does not stop, and adding nodes raises overall throughput.

The add-on you are about to install defaults to a single node, and that is enough. Understanding what a cluster is for is worth the two minutes anyway, because it gives you the mental model for where the expansion joint is, once you have more devices and a real throughput or redundancy requirement.

Two version numbers that do not match, on purpose

This trips people up on day one, so it is worth stating plainly. The EMQX version bundled with the Woow EMQX add-on is 5.8.9 (Open Source). The add-on's own version is 5.9.0. Those are two different things being counted.

So if you go looking for a 5.9 feature in the broker, you will not find one, because there isn't one. Everything that follows is written against the facts and menu paths of 5.8.9.

Repository, install, start, log in

The Home Assistant add-on store does not carry Woow EMQX by default, so the first move is adding the WoowTech repository to your Home Assistant. A repository is just an address you paste in once; after that the store knows where to look.

Woow EMQX is a Home Assistant add-on that WOOWTECH maintains as a fork of hassio-addons/addon-emqx. It ships EMQX 5.8.9 (Open Source) on the Erlang/OTP runtime, with a built-in SQLite store for its settings.

The install itself is not hard. What makes it go wrong is starting it before three words mean anything to you, because then the add-on refuses to run and you are left in front of a log with no idea why. The three are worth reading once now, in this order:

The whole run is five moves: add the repository, install, start, log in for the first time with admin / public, change the default password.

1. Step 1

   Add the WoowTech repository

   In Home Assistant, go to Settings → Add-ons → Add-on store, open the ⋯ menu at the top right, choose Add repository, paste in the address below and click Add.

   https://github.com/WOOWTECH/Woow_ha_emqx

   Paste the whole thing, including the trailing Woow_ha_emqx. A truncated address is the most common reason the add-on never shows up afterwards.

2. Step 2

   Install Woow EMQX

   Refresh the store, find Woow EMQX, open it and click Install. The download can take a while — this is a broker with a full web interface inside it, not a small integration. Leave it alone until it finishes.

3. Step 3

   Check host_network, then Start

   On the add-on page, check that host_network is enabled, then click Start. Afterwards, read the log and confirm there is no port already in use error. That log line is the single most useful thing on the page at this moment, and it is the one people skip.

4. Step 4

   Open the Web UI and log in for the first time

   Click Open Web UI. Log in with the user name admin and the password public. If you are asked to change the password, change it there and then, and do not use public again before you create real MQTT accounts in a later chapter.

5. Step 5

   Find where the version is shown

   Locate the page in the Dashboard that shows the version and license information, and note down what it says. You will want that version number the day you need to report a problem or check whether a documented feature exists in your build. Part 2 then walks you through the sidebar modules one by one.

The default password, and why it is not really a password

The default account for the EMQX Dashboard is admin / public. The official documentation is explicit about what happens next: the first time you log in with the default credentials, EMQX detects that you are still on the default password and forces you to change it. The new password cannot be the same as the old one, and keeping public for real use is not recommended.

This is the first real step in protecting the admin surface, and it deserves the weight. The Dashboard is the way in to controlling the whole broker — anyone who guesses admin / public can rewrite all of your authentication and authorization. In this part you only have to change the Dashboard login password. Creating real MQTT accounts for your devices and for Home Assistant comes later in the series.

Five ports on your own host, and two doors to the Dashboard

The add-on runs with host_network: true. That means it does not seal its networking into a small virtual network inside the container. It sends and receives MQTT on the ports of the Home Assistant host itself.

Because of host_network, these five ports are open on the Home Assistant host itself. The add-on README lists the following defaults.

Day to day you only need two of them: 1883 for devices and Home Assistant, and 18083 to open the Dashboard. The rest are the WebSocket and TLS options, and they matter later in the series when you put the broker behind TLS.

If another service is holding one of the ports — WebRTC uses 8083, for example — you have to stop the conflicting side first, and then change the port on the Dashboard's Listeners page.

Ingress, or the port, and why there are two

The add-on also serves its admin interface through ingress mode. You can open the EMQX Dashboard straight from the Home Assistant sidebar, with no need to remember http://<host>:18083. The add-on's config.yaml already sets both ingress_port: 18083 and host_network: true, so there is nothing for you to configure here.

flowchart TD
  A["You want the
EMQX Dashboard"] --> B{"Which way in?"}
  B -->|"the EMQX icon in the
Home Assistant sidebar"| C["Ingress: Home Assistant
proxies it for you. No port to
remember, and no worry about
someone else connecting to it directly"]
  B -->|"you type the
address yourself"| D["Port 18083 on the Home
Assistant host, reached
directly over HTTP"]
  C --> E["The same Dashboard,
with the same admin login"]
  D --> E

Both routes reach the same Dashboard. The difference is security and convenience: Ingress is the reverse-proxy entry point Home Assistant provides, so there is no port to remember and no worry about someone else connecting to it directly. Going straight to 18083 is the fallback when the sidebar entry is not working, and it is also how you check whether the problem is EMQX or the Ingress layer in front of it.

Four failures, and what each one is telling you

Four things go wrong often enough to be worth naming. They happen in a fixed order — the store, the start, the Dashboard, the password — so working through them in that order finds the fault faster than picking the one that sounds most likely.

flowchart TD
  A["Something is wrong
after the install"] --> B{"Does Woow EMQX show
up in the add-on store?"}
  B -->|"no"| C["Refresh the page, or leave the store
and come back. Check you pasted the
whole address, ending in Woow_ha_emqx"]
  B -->|"yes"| D{"Does the add-on start?"}
  D -->|"no, the log says
a port is in use"| E["Mosquitto or WebRTC is holding
1883 or 8083. Stop that service
first, then start EMQX"]
  D -->|"yes, it reports running"| F{"Does the Dashboard open?"}
  F -->|"no"| G["Go in through Ingress, the EMQX icon
in the sidebar. Or check that nothing
else is holding 18083"]
  F -->|"yes"| H{"Were you asked to
change the password?"}
  H -->|"no"| I["This is not a fresh install. Change
admin and public by hand in the
Dashboard user settings"]
  H -->|"yes"| J["Change it, and stop
using public"]

1. 1

   You added the repository but Woow EMQX does not show up in the store

   Refresh the page, or leave the store and come back in. If it is still missing, check that you pasted the whole URL, including the trailing Woow_ha_emqx. A copy that stopped at WOOWTECH looks convincing and points at nothing installable.

2. 2

   It will not start, and the log says a port is in use

   The most likely cause is that the Mosquitto add-on or WebRTC is running at the same time, and both hold 1883 or 8083. Stop the conflicting service first, then start EMQX. Note that this is not something you can fix from inside EMQX — it never got far enough to have a Dashboard for you to change the setting in.

3. 3

   The Dashboard will not open

   Get in through Ingress — the EMQX icon in the sidebar — or use http://<home-assistant-host>:18083 instead, replacing the placeholder with your own host. Check that nothing else is holding 18083. If the add-on log shows errors, read those before you start changing ports.

4. 4

   You were never asked to change the password

   Then this is not a fresh install — somebody, possibly you, has been here before. If you are still on the default credentials, change them by hand in the Dashboard's user settings. Once you have changed it, really stop using public.

Still not sure what the broker is doing at all

If the model has not clicked yet, go back to the post office. The publisher writes the envelope, which is the topic, and drops the letter in. 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. Everything in the Dashboard is a view onto that one arrangement: who is holding an envelope open, and what came through it.

The ones that come up every time

Where to go from here