ZigDash

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

Two ways to move

Second adapterSame adapter
CostA 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 moveEverything keeps working: ZHA keeps the old adapterZigbee is off until each device is paired again
PaceRoom by room, over days if you likeAll at once
Going backEasy: unplug the new adapter, ZHA never stoppedRestore the ZHA backup (see Going back)

Second adapter

  1. 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.
  2. Keep the two adapters apart, each on a USB extension cable.
  3. 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.
  4. Move one room at a time: pair its mains-powered devices first (bulbs, plugs, in-wall switches: they are routers), then its battery devices.
  5. When every device is moved, disable ZHA (below) and keep the old adapter as a spare.

Same adapter

  1. Download the ZHA backup (see Before you start), right before you begin.
  2. Disable ZHA: Settings › Devices & services › Zigbee Home Automation, the ⋮ next to Zigbee Home Automation › Disable. Not Delete.
  3. Set up Zigbee2MQTT on the same adapter (with apps or Docker), leaving the network key and PAN ID on GENERATE.
  4. Switch off your mains-powered Zigbee devices at the wall or the breaker. Otherwise they keep looking for the old network.
  5. Switch them back on one by one, and pair each as it comes on. Then pair the battery devices.

Your adapter

Zigbee2MQTT's adapter pages have the details.

Home Assistant with apps (Home Assistant OS)

  1. In Settings › Apps, install and start Mosquitto broker. Home Assistant then offers the MQTT integration under Settings › Devices & services: accept it.
  2. Add the Zigbee2MQTT repository (in the app store, ⋮ › Repositories: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), then install Zigbee2MQTT.
  3. In its Configuration tab, set the serial port and adapter from your adapter, for example:
    port: /dev/serial/by-id/usb-...
    adapter: ember
    For the second-adapter way, also set the channel (see above) before the first start.
  4. 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

  1. 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.
  2. 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.
  3. 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

Going back

Tested: on 17 November 2026, with Home Assistant 2026.11 and a Sonoff ZBDongle-E, ZHA's network came back exactly (channel, PAN ID and network key). We haven't yet checked it with devices paired, so keep the backup file.

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.

Tell us how it went. This guide is new. If a step was wrong or missing, write to support@zigdash.app or the community.