Not every device is going to connect to your broker

You may have a Zigbee gateway, or a cloud platform, that already publishes its data to some other MQTT broker. It is not going to move house just because you installed EMQX. To get those external messages into your EMQX — and from there into a rule, or into Home Assistant — you need a way in. That way in is called a Source.

The Sink from Part 5 sends data out. A Source is the opposite: it collects data from a remote broker and hands it to a rule. This is data import, and it is the missing half of the picture.

Connecting two MQTT brokers this way is what most people call an MQTT broker bridge. The EMQX 5.x documentation calls it MQTT Broker Data Integration, which is the term you will hit in the official docs. Whichever name you use, the mechanism is the same: EMQX connects to another MQTT service as a client, and exchanges messages in both directions.

The two directions are not separate features. Both share the same Connector you met in Part 5, and one connection can carry several bridge rules, each with its own topic mapping and its own transformation.

flowchart LR
  subgraph EG["Egress — a Sink"]
    direction LR
    L1["Local topic t/1"] --> S1["MQTT Sink"] --> R1["Remote pub/t/1"]
  end
  subgraph IN["Ingress — a Source"]
    direction LR
    R2["Remote f/1"] --> S2["MQTT Source"] --> P["Republish action"] --> L2["Local sub/f/1"]
  end

Five steps, following the official tutorial

The worked example below is the one in the official tutorial: bridge whatever a remote broker receives on f/# onto your local sub/#. The remote broker is the public test broker broker.emqx.io, so you can run this without owning a second broker of your own. The menu paths are written against the EMQX 5.8.9 (Open Source) Dashboard, which is the version this guide follows throughout.

1. Step 1

   Create the MQTT Broker Connector

   In the Dashboard go to Integration → Connectors → Create and pick MQTT Broker. Name it my_mqtt_bridge and set the server to:

   broker.emqx.io:1883

   If the remote broker requires authentication, fill in the credentials here. Then click Create.

2. Step 2

   Create the rule and add the MQTT Source

   Go to Integration → Rules → Create. On the Data Inputs tab, delete the default Message input, click Add Input, pick MQTT Broker, and choose the Connector you just made. Then set the subscribe Topic and the QoS. The tutorial uses:

   $share/1/f/#

   That leading $share/1/ is a shared subscription, and the next section explains why it is there rather than a plain f/#.

3. Step 3

   Check the rule SQL

   Once the Source is added, the rule SQL rewrites itself and becomes this on its own:

   SELECT * FROM "$bridges/mqtt:my_source"

   Read it as a sentence: the data source for this rule is that MQTT broker bridge, not a local topic. You did not type it; adding the Source produced it.

4. Step 4

   Add the Republish action

   Switch to the Action Outputs tab, click + Add Action and pick Republish. Three fields:

   Topic — sub/${topic}

   QoS — ${qos}

   Payload — ${payload}

   The ${topic} in there is the topic of the original remote message. So a remote f/1 becomes a local sub/f/1: the prefix is yours, the tail is theirs.

5. Step 5

   Create it and verify

   Click Create to finish the rule. Then test it end to end: subscribe to sub/# locally, publish a message to f/1 on the remote broker, and it should arrive locally on sub/f/1. If it does not, the first row of the troubleshooting table further down is exactly this case.

flowchart TD
  A["A message lands on f/1
at the remote broker"] --> B["MQTT Source subscribes
$share/1/f/#"]
  B --> C["Rule reads
$bridges/mqtt:my_source"]
  C --> D["Republish action writes
sub/${topic}"]
  D --> E["Local subscriber on sub/#
receives sub/f/1"]

Wildcards, shared subscriptions, and the seven fields

Two things are worth watching when you create an MQTT Source.

The first is the subscribe topic. It accepts the + and # wildcards, so one Source can pick up a whole family of remote topics rather than one at a time. The usual rules apply: + matches exactly one level, and # matches the rest and is only allowed at the end.

The second is the shared subscription. When EMQX runs as a cluster, or when the Connector has a connection pool open, several clients end up subscribed to the same topic at once — and each of them receives the message. That is not a bug, it is what a plain subscription means. The official advice is to spread that load with a shared subscription:

What the Source then hands to your rule SQL is a fixed set of seven fields:

A rule that wants those fields uses $bridges/mqtt:<name> as its data source, where <name> is the name of the Connector or Source. Get that name wrong and the rule still exists, still runs, and quietly gives you empty fields.

The egress side, for completeness

Going the other way is simpler, because no Republish is involved. You create an MQTT Sink (egress) that publishes a local topic to the remote broker. A rule of SELECT * FROM "t/#" pointed at the target pub/${topic} forwards your local t/1 to pub/t/1 on the remote broker. On the way out, QoS and retain can carry over from the original message through the ${qos} and ${flags.retain} placeholders.

To declare all of this in a config file instead of clicking through the Dashboard, create the matching ingress (Source) and egress (Sink) bridges in the rule_engine and connector/bridges sections, mirroring the rule's SQL.

Point Home Assistant at EMQX

Home Assistant's built-in MQTT integration needs the smallest of setups — a broker address plus credentials — which is why so many installations end up on Mosquitto and stay there. Your host does not have to. The main reason to switch to the Woow EMQX add-on (EMQX 5.8.9) is that it takes over the whole MQTT lifecycle: Dashboard, ACL, rules, monitoring. The one condition is that Home Assistant can actually reach your EMQX.

Two facts shape the setup, and both are about the add-on rather than about Home Assistant.

The Woow EMQX add-on uses host_network, which means it opens port 1883 (MQTT) directly on the host. So in the Home Assistant setup you can simply put homeassistant in Broker — or localhost — without hunting for a container address.

And the connection needs a user account in EMQX. Woow EMQX requires Authentication to be set up first, so nothing can connect without credentials. That fixes the order of operations: create the user in EMQX first, then create the integration in Home Assistant.

1. Step 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 the account Home Assistant will connect with, so write it down where you can find it again in two minutes.

2. Step 2

   Open the MQTT integration in Home Assistant

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

3. Step 3

   Fill in the broker connection details

   Four fields, and they are the whole configuration:

   Broker — homeassistant (or localhost)

   Port — 1883

   Username — the account you created in step 1

   Password — its password
4. Step 4

   Save and confirm

   After you save, Home Assistant should report that the connection succeeded. Now go back to the Clients page of the EMQX Dashboard: this MQTT client from Home Assistant will be sitting there, online. That is the confirmation worth trusting — it is the broker's own view, not a message from the side that just tried.

5. Step 5

   Check discovery

   If a set of discovery messages is already on the homeassistant/ topic, Home Assistant should find those devices by itself. If not, you can still add one by hand with Add device.

flowchart TD
  A["EMQX: Access Control → Authentication
Password-Based → Built-in Database"] --> B["A username and password
now exist in EMQX"]
  B --> C["HA: Settings → Devices & services
→ Add integration → MQTT"]
  C --> D["Broker homeassistant, Port 1883,
Username and Password from the top"]
  D --> E["HA reports the connection succeeded"]
  E --> F["The HA client appears on
the EMQX Clients page"]

Devices introduce themselves, and so does Home Assistant

Discovery is what makes the Home Assistant 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, Home Assistant creates the matching entity for you. Nothing to add by hand, no YAML.

The integration also announces itself, using two MQTT features that are easy to confuse:

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

flowchart TD
  A["The HA MQTT integration connects"] --> B["Publishes a birth message
on homeassistant/status"]
  A --> C["Subscribes to the discovery prefix
homeassistant/"]
  A --> D["Registers a will
with the broker"]
  C --> E["A device publishes a discovery message
in the expected format"]
  E --> F["HA creates the matching entity
on its own"]
  D --> G["Connection lost unexpectedly:
the broker publishes offline
on HA's behalf"]

One port, two brokers, and only one winner

Zigbee2MQTT (Z2M) is the common integration for bridging Zigbee devices onto MQTT, and it is usually the second thing you point at the new broker. 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 away from Mosquitto starts with one hard constraint: Mosquitto and EMQX cannot run at the same time. Both take port 1883.

The migration outline is four steps, and the order matters:

1. Step 1

   Disable your existing Mosquitto add-on

   This frees up 1883. Until it is done, nothing else in this list can succeed.

2. Step 2

   Point your existing devices and integrations at EMQX

   The broker of everything currently talking to Mosquitto now becomes homeassistant, port 1883, with the EMQX account.

3. Step 3

   Create the same MQTT users in EMQX

   And carry the retained message and ACL settings over to the EMQX side as well. This is the part that takes real time on a mature installation.

4. Step 4

   Start EMQX and confirm

   Check that Home Assistant, Z2M and your external devices all connect. All three, not just the one you were watching.

flowchart TD
  A["Mosquitto and EMQX
both want port 1883"] --> B["1 · Disable the Mosquitto add-on
to free up 1883"]
  B --> C["2 · Point existing devices and integrations
at EMQX — homeassistant, 1883"]
  C --> D["3 · Create the same MQTT users in EMQX,
carry retained messages and ACL over"]
  D --> E["4 · Start EMQX and confirm HA, Z2M
and external devices all connect"]

What you gain is worth stating plainly, because “why bother” is a fair question. Mosquitto has no graphical interface, no client list, no Rule Engine and no built-in WebSocket. EMQX gives you all four in the Dashboard, and that is exactly what EMQX adds over Mosquitto.

Eight symptoms and what to check for each

Four of these come from the bridging side and four from the Home Assistant side. In both halves, the answer is nearly always something ordinary rather than something deep.

The eight that come up most

Where to go from here