Home Assistant integration

Why this matters

Home Assistant's built-in MQTT integration needs the smallest of setups — a broker address plus credentials — but your Home Assistant host does not have to stay on Mosquitto forever. The main reason to switch to Woow EMQX is that it takes over the MQTT lifecycle: Dashboard, ACL, rules, monitoring — as long as HA can actually reach your EMQX.

This chapter wires EMQX up as HA's broker, lets discovery move MQTT devices into HA for you, and brings Zigbee2MQTT and your old Mosquitto setup under the same integration.

Core concepts

HA's MQTT integration is the integration built into Home Assistant for connecting to one MQTT broker. The Woow EMQX add-on is that broker: the add-on uses host_network, so it opens port 1883 (MQTT) directly on the host, and in the HA setup you can simply put homeassistant or localhost in Broker.

The connection needs a user account in EMQX: Woow EMQX requires Authentication to be set up first, so nothing can connect without credentials. The order is therefore: create the user under Access Control → Authentication in EMQX, then create the MQTT integration in HA and enter those credentials.

Terms at a glance

Hands-on

1. Create an MQTT user in EMQX

   Start in the EMQX Dashboard: Access Control → Authentication, pick Password-Based → Built-in Database, and create a username and password (this is what HA connects with).

2. Open the MQTT integration in Home Assistant

   In the HA panel: Settings → Devices & services → Add integration → search for MQTT. If it is not installed yet, HA offers to add it.

3. Fill in the broker connection details

   Put homeassistant (or localhost) in Broker, 1883 in the port field, the account you just created in Username, and its password in Password.

4. Save and confirm

   After you save, HA should report that the connection succeeded. Back on the Clients page of the EMQX Dashboard you will see this MQTT client from HA online.

5. Check discovery

   If a set of discovery messages is already on the homeassistant/ topic, HA should find the devices by itself; if not, add one by hand with "Add device".

The MQTT integration, discovery and birth/will

Discovery is what makes the HA MQTT integration convenient: the integration subscribes to the discovery prefix (the homeassistant/ topic by default), and when a device publishes a discovery message in the expected format, HA creates the matching entity for you, with nothing to add by hand.

The MQTT integration also uses a Birth Message and a Will to keep its own state and the broker's in step:

• Birth Message: the integration publishes an "I'm here" message the moment it comes online, so other subscribers know HA has connected.
• Will: the integration registers a will; if HA and the broker lose the connection unexpectedly, the broker sends an "offline" notice on HA's behalf.
• Status: those messages land on HA's status topic (homeassistant/status, for example), which is how everyone else — and your EMQX rules — can tell whether HA is online or offline.

In practice, showing whether HA is online usually relies on this status topic. To put an EMQX rule on the HA offline notice, point the rule's FROM clause at that event source.

Zigbee2MQTT and migrating from Mosquitto

Zigbee2MQTT (Z2M) is the common integration for bridging Zigbee devices onto MQTT. Because the Woow EMQX add-on runs with host_network, the broker address Z2M connects to is usually homeassistant or this add-on's slug (a0d7b954-emqx, for example), on port 1883, with the account you created in EMQX.

Migrating from Mosquitto starts with one constraint: Mosquitto and EMQX cannot run at the same time (both take 1883). The outline:

1. Disable your existing Mosquitto add-on to free up 1883.
2. Point the broker of your existing devices and integrations at EMQX (homeassistant, 1883, the EMQX account).
3. Create the same MQTT users in EMQX, and carry the retained message and ACL settings over to the EMQX side as well.
4. Start EMQX and confirm that HA, Z2M and your external devices all connect.

Mosquitto has no graphical interface, no client list, no Rule Engine and no built-in WebSocket; EMQX gives you all of them in the Dashboard, and that is exactly what EMQX adds over Mosquitto.

Troubleshooting

• The HA MQTT integration will not connect: check that EMQX is running, that Address is homeassistant or the correct host address, that the port is 1883, and that you created the account in EMQX (authentication).
• Discovery brings in no devices: check the discovery prefix (homeassistant/) and whether birth/will is working, whether the device published a discovery message at all, and whether HA has been upgraded.
• Running alongside Mosquitto fails: the two brokers are fighting over the same 1883. Stop Mosquitto first (or move the EMQX listener to another port), then start the other side.
• Z2M cannot reach EMQX: the broker host Z2M uses has to work (homeassistant or the add-on slug), and check that Z2M is using the account you created in EMQX, not the old Mosquitto one.

FAQ

Official sources

• Woow EMQX add-on README (pinned commit)
• Woow EMQX add-on DOCS.md (pinned commit)
• EMQX 5.8 MQTT concepts (pinned docs branch)