Moving from ZHA to Zigbee2MQTT
ZHA is Home Assistant's own Zigbee. ZigDash works with Zigbee2MQTT, so it can't show devices that are in ZHA. Moving means pairing your devices again with Zigbee2MQTT. Home Assistant keeps using them afterwards, through its MQTT integration.
Before you start
- Which installation? If Home Assistant's Settings menu shows Apps (Add-ons on older versions), you have Home Assistant OS: see with apps. If it doesn't, Home Assistant runs in Docker (Container): see Docker.
- Which adapter? Open Settings › Devices & services › Zigbee Home Automation. Under Hubs, the adapter is listed by its model, for example SONOFF ZBDongle-E. Then check your adapter.
- Back up ZHA. On that page, tap the ⚙ next to Zigbee Home Automation, then Download backup. Keep the file. The same page's Network information shows the channel, radio type and serial port.
- What changes in Home Assistant. Your devices come back as new MQTT devices with new entity IDs. Automations, scripts and dashboards that use them must be pointed at the new ones, and their history starts again. Groups and bindings made in ZHA are made again in Zigbee2MQTT.
- Time. Each device is reset and paired again, one by one. We don't have honest timings yet; plan an evening for a small home and more for a big one.
Two ways to move
| Second adapter | Same adapter | |
|---|---|---|
| Cost | A new adapter, about 30–60 EUR (for example a Home Assistant Connect ZBT-2, or an SMLIGHT SLZB-06M or SLZB-07) | Free |
| While you move | Everything keeps working: ZHA keeps the old adapter | Zigbee is off until each device is paired again |
| Pace | Room by room, over days if you like | All at once |
| Going back | Easy: unplug the new adapter, ZHA never stopped | Restore the ZHA backup (see Going back) |
Second adapter
- Set up Zigbee2MQTT on the new adapter (with apps or Docker) with its own network. Choose all of this before Zigbee2MQTT's first start, since changing the channel later can mean pairing again:
- leave the network key and PAN ID on
GENERATE(the default); - pick a channel different from ZHA's (ZHA's ⚙ › Network information shows it); Home Assistant advises 15, 20 or 25.
- leave the network key and PAN ID on
- Keep the two adapters apart, each on a USB extension cable.
- On Home Assistant OS, when you plug in the new adapter, Home Assistant may offer to set it up for ZHA or Thread. Ignore that: the adapter is for Zigbee2MQTT.
- Move one room at a time: pair its mains-powered devices first (bulbs, plugs, in-wall switches: they are routers), then its battery devices.
- When every device is moved, disable ZHA (below) and keep the old adapter as a spare.
Same adapter
- Download the ZHA backup (see Before you start), right before you begin.
- Disable ZHA: Settings › Devices & services › Zigbee Home Automation, the ⋮ next to Zigbee Home Automation › Disable. Not Delete.
- Set up Zigbee2MQTT on the same adapter (with apps or Docker), leaving the network key and PAN ID on
GENERATE. - Switch off your mains-powered Zigbee devices at the wall or the breaker. Otherwise they keep looking for the old network.
- Switch them back on one by one, and pair each as it comes on. Then pair the battery devices.
Your adapter
- Silicon Labs (Home Assistant Connect ZBT-1 and ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M and SLZB-07):
adapter: ember. The ZBT-2 also needsbaudrate: 460800; the ZBDongle-E needsrtscts: false; the SLZB-06M needs firmware 20240510 or later. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 and SLZB-06P7):
adapter: zstack. - ConBee or RaspBee:
adapter: deconz. - CC2531 or ZiGate: too old or no longer maintained for a good Zigbee2MQTT network. Use the second-adapter way with a new adapter.
- A network adapter (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, MR series): ZHA shows it as
socket://IP:6638; in Zigbee2MQTT it istcp://IP:6638, and Docker needs no USB line. - Multiprotocol (ZBT-1 or Yellow running Zigbee and Thread together; the hardware's page in Home Assistant says so): Zigbee2MQTT can't use multiprotocol firmware. For the same-adapter way, turn multiprotocol off while still on ZHA, with Home Assistant's own procedure (ZBT-1, Yellow). Thread devices that used it stop working until another Thread border router takes them. For the second-adapter way, leave it alone and buy the new adapter as Zigbee-only.
Zigbee2MQTT's adapter pages have the details.
Home Assistant with apps (Home Assistant OS)
- In Settings › Apps, install and start Mosquitto broker. Home Assistant then offers the MQTT integration under Settings › Devices & services: accept it.
- Add the Zigbee2MQTT repository (in the app store, ⋮ › Repositories:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), then install Zigbee2MQTT. - In its Configuration tab, set the serial port and adapter from your adapter, for example:
For the second-adapter way, also set the channel (see above) before the first start.port: /dev/serial/by-id/usb-... adapter: ember - Start Zigbee2MQTT and open its web page from the app's page. Then pair.
Home Assistant in Docker (no apps)
Without apps, Mosquitto and Zigbee2MQTT run as their own containers next to Home Assistant. In a new folder:
1. compose.yaml (put your adapter's path in devices; ls /dev/serial/by-id/ shows it):
services:
mosquitto:
image: eclipse-mosquitto:2
restart: unless-stopped
ports:
- 1883:1883
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
zigbee2mqtt:
image: ghcr.io/koenkk/zigbee2mqtt
restart: unless-stopped
depends_on:
- mosquitto
ports:
- 8080:8080
volumes:
- ./zigbee2mqtt:/app/data
- /run/udev:/run/udev:ro
environment:
- TZ=Europe/Berlin
devices:
- /dev/serial/by-id/usb-...:/dev/ttyACM0
With a network adapter, leave out devices and the udev line.
2. mosquitto/config/mosquitto.conf:
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
Make the MQTT user (it asks for a password twice; the file must belong to Mosquitto's own user, or Mosquitto won't start):
docker run -it --rm -v "$PWD/mosquitto/config:/mosquitto/config" eclipse-mosquitto:2 \
sh -c "mosquitto_passwd -c /mosquitto/config/passwd zigbee && chown mosquitto:mosquitto /mosquitto/config/passwd"
3. zigbee2mqtt/configuration.yaml (the adapter lines from your adapter):
homeassistant:
enabled: true
frontend:
enabled: true
port: 8080
mqtt:
server: mqtt://mosquitto:1883
user: zigbee
password: your-password
serial:
port: /dev/ttyACM0 # a network adapter: tcp://IP:6638
adapter: ember
advanced:
network_key: GENERATE
pan_id: GENERATE
ext_pan_id: GENERATE
channel: 20 # second adapter: not ZHA's channel
4. For the same-adapter way, ZHA is disabled now (see above). If Home Assistant's own container maps the adapter, remove that line from its compose file or docker run: only one container can use the adapter.
5. docker compose up -d, then open http://the-machine:8080: Zigbee2MQTT's web page.
6. In Home Assistant: Settings › Devices & services › Add integration › MQTT. Broker: the machine's IP address, port 1883, user zigbee and the password.
Pairing the devices
- On Zigbee2MQTT's web page, tap Permit join (open for about four minutes). To pair through a router near the device, pick that router in the permit join menu: useful for Aqara and other picky devices.
- Reset the device to pairing mode, the way its maker says: a long press for most sensors, a few on/off cycles for bulbs, a series of switch flips for some in-wall switches.
- When it shows up, give it its name and room in Zigbee2MQTT. Then the next one.
Mains-powered devices first, battery devices after, so the new network has routes.
After the move
- ZigDash: open it and tap Find my setup. It finds Mosquitto on your network; log in with the MQTT user. Or choose Home Assistant and sign in: that now works too, since Home Assistant has the MQTT integration.
- Names and rooms: ZigDash's Settings › Import from Home Assistant brings the names and rooms you gave the new devices in Home Assistant.
- Home Assistant: point automations, scripts and dashboards at the new devices. When you're sure, delete the ZHA integration.
Going back
- Second adapter: stop Zigbee2MQTT and unplug the new adapter. ZHA never stopped. Devices you already moved need pairing to ZHA again.
- Same adapter: stop Zigbee2MQTT, then on ZHA's page tap Enable. ZHA says "Network settings do not match most recent backup", because the adapter now holds Zigbee2MQTT's network. Open Settings › Repairs › "Zigbee network settings have changed" and choose Restore backup (recommended). ZHA's network comes back as it was. Devices you had paired to Zigbee2MQTT need pairing to ZHA again. If no repair appears, use ⚙ › Migrate adapter with the backup you downloaded.
Keeping the network without pairing again
There is a third way: copying ZHA's network into Zigbee2MQTT so devices don't need pairing again. Zigbee2MQTT doesn't support it, a wrong value can wipe the network, and it only makes sense for big homes (say, over 60 devices). If you want to read about it: the Zigbee2MQTT maintainer's answer, and community reports in discussion 24478 and discussion 26716.