Setting Up Zigbee2MQTT on HA Green — Mosquitto, Connect ZBT-2, and Ditching ZHA

Andrea Leandri
5 days ago
5 min read

Skill level: Beginner to Intermediate | Time to complete: 45-60 minutes

What you'll build: A fully working Zigbee stack using Mosquitto as the MQTT broker and Zigbee2MQTT as the coordinator, replacing HA's default ZHA integration. Once done you'll pair a first Zigbee device to confirm everything is working end to end.

Why Zigbee2MQTT Instead of ZHA?

Home Assistant ships with ZHA (Zigbee Home Automation). It works for a small number of devices but Zigbee2MQTT is the better long-term choice: broader device support covering thousands of devices often before ZHA, more control over device settings and OTA firmware updates, better diagnostics including a live mesh map, and explicit configuration so you always know what is happening.

The Home Assistant Connect ZBT-2

The Home Assistant Connect ZBT-2 is an external USB-C Zigbee and Thread coordinator made by Nabu Casa. It looks like a small antenna with a flat base and connects to any spare USB port on your HA Green (or Raspberry Pi) via the included USB-C cable. It is a significant upgrade over the original ZBT-1: a larger optimised antenna for better range, a faster 460,800 bps baud rate (4x the ZBT-1), and the newer Silicon Labs MG24 chip for improved performance and stability. It supports Zigbee 3.0, Thread, and Matter - but only one protocol at a time.

When HA detects the ZBT-2 plugged in, it automatically offers to set up ZHA with it. This is the first thing you need to stop. If ZHA has the stick, Zigbee2MQTT cannot use it. The two cannot share the hardware.

The ZBT-2's serial port path follows this pattern:

/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_<your-serial-number>-if00-port0

The serial number in the middle is unique to your device. You will find the exact path during setup.

What You'll Need

HA Green - running HA OS
Home Assistant Connect ZBT-2 - plugged into a USB port on the HA Green via the included USB-C cable
Mosquitto broker add-on - the MQTT broker, already installed if you followed the PS5 Cinema Mode guide on this site
Zigbee2MQTT add-on - available via a custom repository added to the HA add-on store
One Zigbee device - for the verification step at the end

Part 1: Plug In the ZBT-2

Connect the ZBT-2 to a USB port on your HA Green using the included USB-C cable. Position it away from other USB devices and electronics if possible - the antenna performs best with a clear line of sight to your Zigbee devices. HA will detect it automatically within a few seconds and may prompt you to set up ZHA or a Thread network. Dismiss or ignore that prompt for now - you will be using Zigbee2MQTT instead.

Part 2: Install Mosquitto

Already have Mosquitto from the PS5 Cinema Mode guide? Skip to Part 3.

Settings → Add-ons → Add-on Store → search Mosquitto broker. Install the one by the Home Assistant team. Start it and enable Start on boot and Watchdog. Leave all configuration at defaults.

Then add the MQTT integration: Settings → Devices & Services → Add Integration → search MQTT. HA detects Mosquitto automatically. Accept all defaults.

Part 3: Disable ZHA and Free the ZBT-2

This must happen before Zigbee2MQTT is configured. If ZHA is holding the ZBT-2's serial port when Z2M tries to open it, Z2M will fail with a cryptic port in use error.

Settings → Devices & Services → find the Zigbee Home Automation card
If you have already paired devices via ZHA, note them down - you will need to re-pair them in Z2M. There is no migration path between ZHA and Z2M device databases.
Click the ZHA card → three-dot menu → Delete → confirm
Settings → System → Restart → Restart Home Assistant (full restart required, not config reload)

Do not skip the restart. Even after deleting ZHA, the serial port can remain locked until HA restarts fully.

Part 4: Find Your ZBT-2 Serial Port Path

Settings → System → Hardware → All Hardware. Search for zbt. You should see an entry like:

/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_10B41DE58F04-if00-port0

The alphanumeric string in the middle is your device's unique serial number. Copy the full path exactly. Alternatively, in the Terminal add-on run: ls /dev/serial/by-id/ to list all connected serial devices.

Part 5: Install Zigbee2MQTT

5.1 Add the repository

Zigbee2MQTT is not in the default HA add-on store. Settings → Add-ons → Add-on Store → three-dot menu top right → Repositories. Add:

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

Close and the store refreshes. Search Zigbee2MQTT and install it.

5.2 Configure before starting - ZBT-2 specific settings

In the Configuration tab, set the following. These three serial settings are specific to the ZBT-2 and different from older coordinators - all three are required.

serial:
  port: /dev/serial/by-id/usb-Nabu_Casa_ZBT-2_YOUR_SERIAL-if00-port0
  adapter: ember
  baudrate: 460800
  rtscts: true

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

adapter: ember - the ZBT-2 uses the Silicon Labs MG24 chip which runs the EmberZNet protocol stack. Without this Z2M will fail to communicate with the coordinator.
baudrate: 460800 - the ZBT-2 runs at 460,800 bps, 4x faster than older coordinators. Using the wrong baud rate causes communication failures.
rtscts: true - enables hardware flow control, required for reliable communication at the higher baud rate via the ZBT-2's ESP32-S3 USB bridge.

Critical: use mqtt://core-mosquitto:1883, not localhost. In HA OS, add-ons communicate via the internal hostname core-mosquitto. This is the most common Z2M setup mistake.

5.3 Start and verify

Info tab → Start. Enable Start on boot and Watchdog. Click Open Web UI. After 15-20 seconds you should see the Zigbee2MQTT dashboard. If you see it, the stack is working.

If it fails, check the Log tab immediately. Common errors: Error while opening serialport means ZHA was not fully removed - repeat Part 3 and restart HA. ECONNREFUSED means MQTT connection failed - check the server is mqtt://core-mosquitto:1883. Unsupported adapter type means adapter: ember is missing from the serial config.

Part 6: Pair Your First Zigbee Device

In the Z2M web UI, click Permit join (All) → button turns green, 254 second countdown starts
Put your device in pairing mode: IKEA bulb = power cycle 6 times; IKEA plug = hold reset 10 seconds; Aqara sensor = hold button until LED flashes 3 times; Sonoff ZBMINI = hold button 5 seconds
Watch the Devices tab → your device appears within 30-60 seconds with manufacturer and model name
Click Permit join (All) again to close pairing mode
Settings → Devices & Services → Zigbee2MQTT → your device should appear with all its entities

The Zigbee Mesh Map

In the Z2M web UI go to the Map tab. You'll see your devices as nodes connected by lines. Mains-powered devices (bulbs, plugs) are routers that extend the mesh and relay signals for battery-powered end devices. The ZBT-2's optimised antenna gives it significantly better range than the ZBT-1 and most USB stick coordinators, so devices further from the HA Green will be more reliable. As you add more mains-powered Zigbee devices the mesh grows and the whole network becomes more stable.

Troubleshooting

ZBT-2 not detected at all: Check the USB-C cable is firmly connected to both the ZBT-2 and the HA Green. Try a different USB port.
serialport error on start: ZHA was not fully removed or HA was not restarted after removing it. Repeat Part 3 and do a full HA restart.
ECONNREFUSED on start: MQTT server address is wrong. Must be mqtt://core-mosquitto:1883, not localhost.
Unsupported adapter type error: Missing adapter: ember in the serial config. Do not leave this out - it is required for the ZBT-2.
Communication errors or devices not responding: Check baudrate is 460800 and rtscts is true. Wrong values here cause silent failures.
Device does not appear during pairing: Permit join must be active. Try moving the device closer to the ZBT-2 antenna.
Device appears in Z2M but not in HA: Wait 60 seconds for MQTT discovery. Check Settings → Devices & Services → Zigbee2MQTT.

Guide written by a Home Assistant enthusiast in Utrecht. The ZHA conflict is the silent killer of Z2M setups - now you know to kill it first. And the three ZBT-2 specific settings (ember, 460800, rtscts) are what separate a working setup from a frustrating one.