If you're using ZHA (Zigbee Home Automation) — the built-in Zigbee integration in HA — you're doing fine. ZHA works. But if you've ever wanted to see signal strength for every device, view the mesh routing map, use an MQTT explorer to debug, or easily move your entire Zigbee network to new hardware someday, Zigbee2MQTT is the better path.

I switched from ZHA to Zigbee2MQTT two years ago. The main reasons: more devices are supported (Z2M has the largest Zigbee device database), the Zigbee2MQTT dashboard gives you network visibility ZHA doesn't, and the MQTT architecture means HA and your Zigbee network are decoupled — if HA breaks, your Zigbee devices still talk to each other.

Here's the complete setup from scratch.

What You Need

  • Running Home Assistant OS or Supervised instance
  • A Zigbee USB coordinator dongle — recommended: Sonoff ZBDongle-E (~$20) or SMLIGHT SLZB-06 (~$45 for Ethernet version)
  • Your existing Zigbee devices (or devices you're about to buy)

Note on dongles: The Sonoff ZBDongle-E uses the Silicon Labs EFR32MG21 chip and has excellent range. Plug it into a USB port on your HA device. If you're using a Pi, use a USB extension cable and move the dongle away from the Pi's electronics — USB 3.0 interference kills Zigbee range.

The SLZB-06 is an Ethernet-based coordinator — you plug it into your network switch instead of USB. This eliminates any USB interference issues and you can place it anywhere in your home for better mesh coverage.

Step 1: Install Mosquitto MQTT Broker

Zigbee2MQTT communicates via MQTT. Mosquitto is the local MQTT broker that routes messages between Z2M and Home Assistant.

Go to Settings → Add-ons → Add-on Store. Search for Mosquitto broker. Install it. After installation:

  • Click Start
  • Toggle on Start on boot
  • Toggle on Watchdog (restarts the broker if it crashes)

Mosquitto is now running on your HA device. It listens on port 1883.

Step 2: Configure MQTT Integration in HA

Go to Settings → Devices & Services → Add Integration. Search for MQTT.

If Mosquitto is running, HA will auto-detect it and ask if you want to use the official Home Assistant add-on. Click Yes. Done. The MQTT integration is now connected to your local Mosquitto broker.

If you don't see the auto-detect option, configure manually: broker address core-mosquitto, port 1883, with the HA system user credentials.

Zigbee2MQTT Home Assistant Integration

Step 3: Add the Zigbee2MQTT Repository

The Z2M add-on isn't in the default HA add-on store — you need to add the repository manually.

Go to Settings → Add-ons → Add-on Store. Click the three-dot menu (top right) → Repositories. In the field, enter:

https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Click Add then Close. Refresh the page.

Now search for Zigbee2MQTT in the add-on store. Make sure you pick the main one (not Edge or Proxy). Install it.

Step 4: Find Your USB Dongle Path

Before configuring Z2M, you need the serial path for your Zigbee dongle.

Plug your USB dongle into your HA device. Go to Settings → System → Hardware. Click All Hardware. Scroll down to find your dongle — it usually appears as something like:

/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...

Copy the full path from the by-id section. Using the by-id path instead of /dev/ttyUSB0 is important — the by-id path is persistent across reboots and doesn't change if you plug in other USB devices.

If you're using the SLZB-06 (Ethernet coordinator), your serial path will be a TCP address like tcp://192.168.1.50:6638.

Step 5: Configure Zigbee2MQTT

Before starting Z2M, click on the Configuration tab in the Zigbee2MQTT add-on. You'll see a YAML configuration editor.

Set the minimal configuration:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://core-mosquitto:1883

serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX

frontend:
  enabled: true
  port: 8099

Replace the serial port path with yours. Save the configuration.

Go to the Info tab and click Start. Watch the log output — it should show Z2M connecting to MQTT and starting the Zigbee coordinator. You should see something like:

Zigbee2MQTT:info  2026-03-30 - Starting Zigbee2MQTT version X.X.X
Zigbee2MQTT:info  2026-03-30 - MQTT connected
Zigbee2MQTT:info  2026-03-30 - Coordinator firmware version: ...

Enable Start on boot and Show in sidebar.

Step 6: Pair Your First Device

Click Zigbee2MQTT in the sidebar to open the Z2M web interface.

Click Permit join (All) — this opens your Zigbee network to new devices for 255 seconds. Now put your Zigbee device in pairing mode (this varies by device — usually hold the button until the LED flashes rapidly or the device resets).

Watch the Z2M dashboard. Within 30–60 seconds, the device should appear. Z2M will show the device model, manufacturer, and any available entities.

HA will automatically create entities for the device via MQTT Discovery. Go to Settings → Devices & Services → MQTT — your paired device should appear there.

Navigating the Z2M Dashboard

The Zigbee2MQTT dashboard shows you things ZHA never could:

Devices tab: All paired devices, their LQI (Link Quality Indicator — signal strength 0-255), last seen timestamp, and device details. If a device shows LQI below 50, it's having connectivity issues.

Map tab: Visual representation of your Zigbee mesh. Shows which devices route through which. Routers (always-on devices like Zigbee bulbs or plug-in sensors) show as hexagons. Battery devices show as circles and route through nearby routers. If a battery device has no path to the coordinator except through one router, it's vulnerable — add a router device nearby.

Groups: Create Zigbee groups to control multiple devices simultaneously. Group commands happen at the Zigbee protocol level, so multiple lights in a group turn on/off simultaneously without the slight delay you get from HA calling multiple entities.

Settings: Configure advanced options like channel, transmit power, OTA (firmware updates for compatible devices), and permit join settings.

Z2M vs ZHA: When to Choose Each

Stick with ZHA if:

  • You want the simpler setup with fewer moving parts
  • You have a small number of Zigbee devices
  • You don't need advanced network visualization or debugging

Use Zigbee2MQTT if:

  • You have more than 20 Zigbee devices
  • You want to see and optimize your mesh network
  • You have devices that ZHA doesn't support (Z2M has more coverage)
  • You want to be able to move your Zigbee network to different hardware easily
  • You're comfortable with a bit more initial setup complexity

Both are local, both are fast, both work well in HA. Z2M is just more powerful and visible.

Once it's running, check the Map tab first thing. You'll immediately see which devices are healthy, which have weak signal, and whether your router distribution is optimal. It's the kind of network visibility that makes troubleshooting Zigbee issues dramatically easier.