Zigbee2MQTT

Last reviewed Aug 26, 2026 · 976 words

Two decisions made before you pair the first bulb determine whether Zigbee2MQTT is a joy or a recurring chore: which coordinator stick you buy, and which Zigbee channel you set. Both are cheap to get right on day one and expensive to change on day 60, because changing either means re-pairing most of the devices in the house. Get them right and Zigbee2MQTT gives you local, vendor-neutral control of well over 3,000 supported device models from a 256 MB container that reports into Home Assistant automatically.

Buy a Zigbee 3.0 coordinator and a USB extension cable

The coordinator is the radio that owns the network. The reliable mainstream choices are the Sonoff Zigbee 3.0 USB Dongle Plus in either its CC2652P ("ZBDongle-P") or EFR32MG21 ("ZBDongle-E") variant, both around 20 to 30 dollars at last check, and for Ethernet placement the SMLIGHT SLZB-06 family, which sits anywhere on the LAN and is addressed as tcp://192.168.1.50:6638 instead of a serial port. Older CC2531 sticks are still sold and are not worth it; they cap out at a few dozen devices and drop connections. Whatever you buy, plug it into a 1-metre USB 2.0 extension cable and route it away from the server. USB 3.0 ports and SSDs radiate noise in the 2.4 GHz band and the symptom is intermittent pairing failures that look like a software bug.

Pick the channel now, because you will not want to later

Zigbee and Wi-Fi share 2.4 GHz. Zigbee2MQTT defaults to channel 11, which overlaps Wi-Fi channel 1. If your access points sit on Wi-Fi channels 1 and 6, Zigbee channel 25 is usually the cleanest; if they sit on 6 and 11, channel 15 or 20. Set it in configuration.yaml under advanced: channel: before the first pairing. Changing it afterwards forces every battery device to be re-paired by hand, and some mains devices too. Also set advanced: network_key: GENERATE and pan_id: GENERATE on that first boot so your network does not share the well-known defaults with the neighbours.

The Compose file

services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus-if00-port0:/dev/ttyUSB0
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/London
    restart: unless-stopped

Use the /dev/serial/by-id/ path rather than /dev/ttyUSB0 on the host side; the numbered name changes when you plug in another USB device and the container will come up pointing at nothing. Zigbee2MQTT needs an MQTT broker; Mosquitto is the usual choice and EMQX works if you want a dashboard. The minimum data/configuration.yaml:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
serial:
  port: /dev/ttyUSB0
frontend:
  enabled: true
  port: 8080
homeassistant:
  enabled: true
advanced:
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE

Recent major releases changed several of these keys from booleans to nested objects (frontend and homeassistant in particular), so if you copy a config from an older tutorial and the container refuses to start, that is why.

Pairing works from the web UI, and it is the fiddly part

The frontend on port 8080 has a "Permit join" button that opens the network for 254 seconds. Put the device into pairing mode (usually a reset via holding a button or power-cycling a bulb 5 times), and it appears in the device list with its model identified and its entities published. With homeassistant.enabled: true, Home Assistant's MQTT integration discovers each device automatically and you get lights, sensors, and switches with no YAML. The catalogue's "pairing can be finicky" is accurate. Three rules fix most of it: pair devices where they will live rather than next to the coordinator, pair mains-powered devices first because they act as routers and extend the mesh, and pair battery devices last through those routers. A network with only battery sensors and one coordinator has no mesh at all and a range of one room.

Zigbee2MQTT or ZHA

Home Assistant's built-in ZHA integration uses the same coordinators and skips the MQTT broker, and for a household that only ever uses Home Assistant it is the simpler path. Zigbee2MQTT wins on device support (the community adds new devices faster, and unsupported devices can be added with a converter file), on exposing every device attribute, and on being independent of Home Assistant: Node-RED and anything else that speaks MQTT can consume the same topics. If you are in the first month with Home Assistant, the first-month walkthrough covers where Zigbee fits; if you are choosing platforms, Home Assistant vs openHAB will not change this advice because both speak MQTT.

Back up the data folder, especially the coordinator backup

Everything lives in data/: configuration.yaml, database.db with the device list, state.json, and coordinator_backup.json, which is a snapshot of the coordinator's network state. That last file is what lets you move to a new stick of the same family without re-pairing anything. Back the folder up before every update, and update the coordinator firmware roughly once a year rather than chasing every release.

What I'd do

A ZBDongle-E or SLZB-06 on an extension cable, channel chosen against your Wi-Fi, generated network key, Mosquitto next to it in the same Compose file, homeassistant.enabled: true. Pair 3 or 4 mains-powered plugs or bulbs around the house first, then the sensors. Nightly backup of data/. Run that way, the stick and the container do their job for years and the vendor hubs go in a drawer, which is the reason people leave SmartThings in the first place.