Home Assistant Zigbee2MQTT Setup: Coordinator, Add-on, and Pairing Devices

This post may contain affiliate links. As an Amazon Associate we earn from qualifying purchases. Disclosure.

The usual reason people move from ZHA to Zigbee2MQTT is dumb. A cheap Tuya motion sensor that ZHA reads wrongly or only half exposes, while Zigbee2MQTT already has a converter for it. That's the whole pitch, really: faster device support and far more control. I don't have a long migration track record of my own to point to, so this guide leans on the project's documentation and on what long-time users report.

This guide walks through the complete setup. Coordinator hardware, the add-on install, the MQTT broker, and pairing your first device. No fluff.

TL;DR: Zigbee2MQTT is a Home Assistant add-on that talks to your Zigbee devices through an MQTT broker instead of the built-in ZHA integration. It supports more than 5,700 devices (Zigbee2MQTT documentation, 2026), more than ZHA. You need a USB or Ethernet coordinator (SkyConnect or SLZB-06), the Mosquitto broker add-on, and Zigbee2MQTT itself.

What Is Zigbee2MQTT and Why Pick It Over ZHA?

Zigbee2MQTT is open-source software that bridges your Zigbee radio to MQTT, the lightweight messaging protocol most smart home stacks speak. It currently supports more than 5,700 devices from over 600 vendors (Zigbee2MQTT supported devices, 2026), which is a wider net than the built-in ZHA integration casts. Every device shows up in Home Assistant automatically through MQTT discovery.

So why bother, when ZHA ships in the box and works fine? Two reasons. First, device support. New and obscure sensors (the no-name Tuya and Aqara stuff) land in Zigbee2MQTT weeks before ZHA, sometimes months. Second, control. You get a proper web dashboard, OTA firmware updates, network maps, and per-device settings ZHA simply doesn't expose.

The downside is honest: it's another moving part. ZHA is one integration. Zigbee2MQTT is two add-ons plus a broker. If you want the absolute simplest setup and your devices are all mainstream, ZHA is genuinely fine. The moment you hit one of its walls, an unsupported sensor or a setting it doesn't expose, Zigbee2MQTT starts to make sense.

What Coordinator Hardware Do You Need?

You need a Zigbee coordinator, the radio that actually talks to your devices, and the two worth a look are the Home Assistant Connect ZBT-1 (formerly SkyConnect) at around $30 and the SMLIGHT SLZB-06 at around $40. Home Assistant's own product page now lists the ZBT-1 as no longer in production and points new buyers to the newer ZBT-2, so check what's in stock, but everything below about the ZBT-1 still applies to the many that are installed. The ZBT-1 is a USB stick. The SLZB-06 is a Power-over-Ethernet device you mount anywhere on your network, away from USB interference.

Here's the thing nobody tells beginners: USB 3.0 ports and cheap USB sticks wreck 2.4GHz Zigbee. The interference is real and it's brutal. Home Assistant's ZBT-1 page says USB 3.0 ports (the blue ones) are known to cause significant noise and interference for 2.4 GHz radios, which is why the stick ships with an extension cable, and it warns that skipping the cable can mean dropouts and pairing failures. That applies to the USB 3.0 ports on a Raspberry Pi 5 as much as to any other host. Zigbee2MQTT's docs agree: even a 50 cm extension, preferably shielded, helps.

ZBT-1 vs SLZB-06 vs SkyConnect

There's a naming trap worth clearing up first. The SkyConnect and the Connect ZBT-1 are the same physical stick. Nabu Casa rebranded SkyConnect to ZBT-1, so any old guide naming SkyConnect applies directly to the ZBT-1 you'll buy today. Same EFR32MG21 chip, same firmware, same behavior. Don't overthink it.

The ZBT-1 is the safe default. It's first-party hardware from the Home Assistant team and works with both ZHA and Zigbee2MQTT. Plug it into a USB 2.0 extension cable, set the serial path, done.

The SLZB-06 wins in one scenario, and it's a big one. Range. Because it connects over Ethernet instead of USB, you place the radio anywhere a network cable reaches, not chained to your server. A Home Assistant box often ends up in a metal rack next to a router, a switch, and a NAS or two. Awful spot for a 2.4GHz radio. An SLZB-06 on a PoE cable can hang in a hallway instead, and one cable carries both power and data.

The Sonoff ZBDongle-P is the budget pick. It uses the older Texas Instruments CC2652P chip, which is well supported, but firmware flashing is fiddlier than the ZBT-1. If you're starting fresh and not counting every dollar, skip it and get the ZBT-1.

If your Home Assistant box lives in a closet full of metal and Wi-Fi gear, get the SLZB-06. Mount it centrally. Ethernet over PoE means the radio sits where your devices are, not where your server is. Which coordinator is right for you really comes down to one question: is your server in a good spot for radio, or a terrible one?

How Do You Install the Zigbee2MQTT Add-on?

Installing Zigbee2MQTT takes three add-ons in order: Mosquitto broker, Zigbee2MQTT, and the Studio Code Server for config edits. This guide assumes Home Assistant OS or Supervised, because add-ons need the Supervisor.

Start with the broker. Go to Settings, Add-ons, Add-on Store, and install Mosquitto broker. Start it. Then create a Home Assistant user for MQTT (Settings, People) called something like mqtt-user with a password you'll reuse. Mosquitto authenticates against Home Assistant users automatically, so you don't edit a config file for this part.

Next, add the Zigbee2MQTT repository. In the Add-on Store, click the three dots, Repositories, and paste the official Zigbee2MQTT add-on repo URL from the docs. Install the add-on. Before you start it, open the Configuration tab and set your serial port. For a USB coordinator that's usually /dev/ttyUSB0 or /dev/ttyACM0. For the SLZB-06 you use a TCP path like tcp://192.168.1.50:6638 instead.

Example Zigbee2MQTT Configuration

The add-on stores its settings in a configuration.yaml file under /config/zigbee2mqtt/. You can edit it through the Studio Code Server add-on, which is why we installed it. For a ZBT-1 on a USB port, a working baseline looks like this:

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://core-mosquitto:1883
  user: mqtt-user
  password: your-password-here
serial:
  port: /dev/ttyACM0
  adapter: ember
frontend:
  port: 8099
advanced:
  channel: 20
  network_key: GENERATE
  log_level: info

A few fields matter more than they look. The adapter: ember line tells Zigbee2MQTT to use the newer ember driver for the ZBT-1's Silicon Labs chip, which is what you want in 2026. For an SLZB-06, swap the serial block to port: tcp://192.168.1.50:6638 and set adapter: zstack, since it's a Texas Instruments chip rather than a Silicon Labs one. Set network_key: GENERATE once on a fresh install and Zigbee2MQTT creates a secure key; never share it. And pick a Zigbee channel away from your busiest Wi-Fi. Zigbee channels 15, 20 and 25 are the usual picks because they sit in the gaps between Wi-Fi channels 1, 6, and 11.

Configuring the MQTT Broker Connection

Tell Zigbee2MQTT how to reach the broker. In the add-on config, set the MQTT server to mqtt://core-mosquitto:1883, then the username and password to the mqtt-user account you made. Save. Start the add-on and watch the Log tab. You want to see "Connected to MQTT server" and "Started Zigbee2MQTT" without red errors.

Then enable Home Assistant integration in the Zigbee2MQTT settings (the homeassistant: true line) so devices publish to discovery topics automatically. The topic pattern looks like zigbee2mqtt/0x00158d0001234567, and state updates land on subtopics like zigbee2mqtt/living_room_plug. You'll rarely touch raw topics, but it helps to know they exist when you debug with an MQTT client like MQTT Explorer. Open the Web UI from the add-on page on port 8099.

How Do You Pair Zigbee Devices?

Pairing is two clicks plus a button press. In the Zigbee2MQTT Web UI, hit Permit join (All), then put your device in pairing mode, usually by holding its button 5 to 10 seconds until an LED blinks. The device appears in the dashboard within seconds once Zigbee2MQTT finishes interviewing it.

Always turn Permit join back off when you're done. Leaving it open is a minor security hole, because any device in range that's in pairing mode can join uninvited.

Pairing Troubleshooting

Most pairing failures trace to three things, and they're easy to rule out. First, distance. Pair the device within 6 feet of the coordinator on the first attempt, then move it to its final spot. The interview process is chatty and needs a clean signal. Second, battery contacts. A surprising number of "dead" new sensors just have a plastic pull tab still in the battery slot, or a coin cell that arrived half-drained. Swap in a fresh CR2032 before you blame the software. Third, the device thinks it's already paired. Many Zigbee gadgets need a factory reset (often a longer button hold, 10 to 15 seconds) before they'll re-advertise.

If the log shows "Device did not respond to interview," that's usually a finicky device, not a broken setup. Aqara sensors are notorious for this. Pull the battery, wait 30 seconds, reinsert, then immediately put it in pairing mode with Permit join already active. Keep a few fresh coin cells around for exactly this reason.

Network Map: Routers vs End Devices

Zigbee is a mesh, and understanding the two device roles makes the difference between a flaky network and a bulletproof one. Mains-powered devices like smart plugs and bulbs act as routers and extend your mesh, relaying messages for other devices. Battery sensors are end devices and don't relay anything. They just talk to their nearest router.

So pair a few plugs first, spread around the house, before you add distant battery sensors. Build the mesh outward. Want better range without buying a bigger coordinator? Add more routers. That's the whole trick. The Zigbee2MQTT Web UI has a Map tab that draws your actual mesh as a graph, with line thickness showing link quality. When a sensor drops, open that map first. A device hanging off a single weak line back to the coordinator is begging for a router placed between them. Zigbee2MQTT's own network guide recommends exactly that: add a mains-powered Zigbee device or a dedicated router, and keep the coordinator's adapter away from USB and HDMI ports. My own house leans on this effect, with a coordinator in the distribution board and a few dozen mostly mains-powered bulbs and switches, though I haven't measured range there yet.

A word of warning: not every mains-powered device makes a good router. Zigbee2MQTT's network guide singles out some versions of the Sonoff S26R2ZB plug as limited, and cheap no-name bulbs are a common suspect in forum threads. If a corner of your network keeps falling apart, check whether a flaky device is the router holding it together.

How Do You Migrate From ZHA to Zigbee2MQTT?

There's no clean one-click migration from ZHA to Zigbee2MQTT, so the honest answer is you re-pair every device. A Zigbee device can only be joined to one coordinator, which means each device has to be factory reset, leave the old network, and join the new one.

Here's a sensible order:

• Write down or screenshot your current ZHA device list with their locations.
• Disable or remove the ZHA integration so the two coordinators don't fight over the same radio. You can't run ZHA and Zigbee2MQTT on one coordinator at once.
• Set up Zigbee2MQTT fully and confirm it connects to MQTT before you touch a single device.
• Go room by room: reset each device, pair it, rename it, then move to the next.

That last step is where patience pays off.

The painful part isn't pairing, it's automations. Your entity IDs change. A light that was light.living_room under ZHA might come back as light.living_room_2 if the old entity still lingers. Clean up stale entities as you go, and budget time to fix the automations that reference them. Batch the devices over a couple of evenings and keep a checklist. Tedious? Absolutely. But you only do it once.

Common Errors and How To Fix Them

Three errors come up constantly in the forums, and all three have quick fixes. The most common is "Error: No such file or directory, cannot open /dev/ttyACM0." That means the serial path is wrong or the coordinator isn't detected. Check Settings, System, Hardware, All Hardware for the real device path, and confirm no other add-on (like ZHA) is holding the port.

The second is "MQTT error: connect ECONNREFUSED." Zigbee2MQTT can't reach the broker. Confirm the Mosquitto broker add-on is actually running, that the server line reads mqtt://core-mosquitto:1883, and that the mqtt-user password matches exactly. A stray space in the password breaks it silently.

The third is devices showing up in Zigbee2MQTT but not in Home Assistant. That's almost always the discovery setting. Confirm homeassistant: true is in your config and that the MQTT integration is added in Home Assistant under Settings, Devices and Services. Restart the MQTT integration and the missing entities usually appear within a minute. Still stuck after all that? Our Home Assistant not discovering devices guide covers the deeper cases.

Was the Switch Worth It?

For people with oddball sensors, easily. The faster device support alone justifies the extra add-on, and the network map takes the guesswork out of why one corner of the house keeps dropping. If your devices are mainstream and you hate maintenance, stick with ZHA and skip all this.

But if you buy oddball sensors, tinker on weekends, or want OTA updates and real diagnostics, Zigbee2MQTT is the better engine. Start with a Connect ZBT-1 on a USB 2.0 cable, install Mosquitto, then Zigbee2MQTT, and pair a couple of plugs before anything else. Build the mesh out from there. Once it's humming, you'll wonder why you waited.