How to Set Up Zigbee2MQTT From Scratch

If you have spent any time in the Home Assistant community, you have seen the Zigbee2MQTT vs ZHA debate. Both work. But after running both for over a year, I switched everything to Zigbee2MQTT and never looked back. The device support is broader, the updates are faster, and when something goes wrong, you get real debug logs instead of cryptic error codes.

This guide assumes you have Home Assistant running (on any hardware) and want to set up Zigbee2MQTT from zero. No prior MQTT knowledge required. By the end, you will have a working Zigbee network with your first device paired.

What You Need Before Starting

Let me be upfront about the hardware requirements so you can order everything in one go:

• A Zigbee coordinator: This is the USB stick that talks to your Zigbee devices. The Sonoff ZBDongle-E (based on the EFR32MG21 chip) is the current recommendation. It supports Zigbee 3.0, Thread, and has good range. Costs about $15-20 on Amazon.
• A USB extension cable: Seriously, do not skip this. USB 3.0 ports generate interference on the 2.4GHz band that Zigbee uses. A $3 extension cable moves the coordinator away from that interference and solves 80% of connectivity issues people report.
• Home Assistant with Supervisor: You need the Supervisor to install add-ons. If you run HAOS (Home Assistant OS), you already have it. If you run HA Container, you will need to run Zigbee2MQTT and Mosquitto as separate Docker containers.
• At least one Zigbee device to test with: An Aqara door sensor or IKEA TRADFRI bulb is cheap and well-supported.

Step 1: Install the Mosquitto MQTT Broker

Zigbee2MQTT communicates with Home Assistant through MQTT messages. You need an MQTT broker to handle that message passing. Mosquitto is the standard choice and runs as a Home Assistant add-on.

1. In Home Assistant, go to Settings, Add-ons, then click Add-on Store.
2. Search for "Mosquitto broker" and install the official Mosquitto add-on.
3. Before starting it, go to the Configuration tab. The defaults work for most setups. The key setting is the login credentials.
4. Create an MQTT user: go to Settings, People, Users, and create a new user (e.g., username: mqtt, password: something secure). This user does not need admin rights.
5. Start the Mosquitto add-on.
6. Home Assistant should auto-detect the MQTT integration. If it does not, go to Settings, Devices & Services, Add Integration, and search for MQTT. Use localhost as the broker address with the credentials you just created.

Step 2: Flash Your Coordinator (If Needed)

If you bought a Sonoff ZBDongle-E or ZBDongle-P, it comes pre-flashed with Zigbee coordinator firmware. You can skip this step unless you want to update to the latest firmware version.

To check if a firmware update is available, plug in the coordinator and check the Zigbee2MQTT logs after installation. It will report the current firmware version. Compare this with the latest version on the Koenkk/Z-Stack-firmware GitHub repository for TI-based coordinators, or the Darkxst/silabs-firmware-builder repository for Silicon Labs-based ones.

Flashing is straightforward but varies by coordinator model. The Zigbee2MQTT documentation has specific flashing guides for every supported coordinator. Follow those exactly, using the wrong firmware will brick your stick (recoverable, but annoying).

Step 3: Install Zigbee2MQTT

Back in the Home Assistant Add-on Store, Zigbee2MQTT is not in the default repository. You need to add the community repository first:

1. Click the three dots in the top right of the Add-on Store and select Repositories.
2. Add this URL: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
3. Refresh the page. Zigbee2MQTT should now appear in the store.
4. Install it.

Configure Zigbee2MQTT

Before starting, go to the Configuration tab. You need to set at least these values:

mqtt:
 server: mqtt://localhost:1883
 user: mqtt
 password: your_mqtt_password
serial:
 port: /dev/ttyUSB0
 adapter: zstack # or ezsp for Silicon Labs coordinators
frontend:
 port: 8099
advanced:
 network_key: GENERATE
 pan_id: GENERATE
 channel: 15

A few notes on this configuration:

• Serial port: Check Settings, System, Hardware in HA to find the correct port for your coordinator. It is usually /dev/ttyUSB0 or /dev/ttyACM0.
• Adapter type: Use zstack for TI-based coordinators (ZBDongle-P, CC2652) and ezsp for Silicon Labs (ZBDongle-E, EFR32).
• Network key: Set to GENERATE on first run. Zigbee2MQTT will create a random encryption key and save it. This key encrypts all traffic on your Zigbee network.
• Channel: Default is 11. I recommend 15 or 20 to avoid overlap with WiFi channels. Check our protocol comparison guide for more on channel selection.

Step 4: Start and Verify

Start the Zigbee2MQTT add-on. Watch the logs tab. A successful startup looks like this:

1. Connecting to MQTT broker... connected.
2. Starting Zigbee2MQTT with coordinator on /dev/ttyUSB0.
3. Coordinator firmware version: 20230507 (or similar).
4. Zigbee2MQTT started.

If you see errors about the serial port, double-check the port path. If you see MQTT connection failures, verify your Mosquitto credentials. These two issues account for 90% of first-time setup problems.

Open the Zigbee2MQTT frontend at http://your-ha-ip:8099 (or through the sidebar if you enabled the panel). You should see an empty device list with your coordinator shown at the top.

Step 5: Pair Your First Device

Click "Permit Join" in the Zigbee2MQTT frontend. This opens a 254-second window where new devices can join the network.

Now put your Zigbee device into pairing mode. For most devices:

• Aqara sensors: Hold the tiny reset button for 5 seconds until the LED flashes.
• IKEA TRADFRI bulbs: Turn the bulb off and on 6 times rapidly (on for 0.5s, off for 0.5s).
• Sonoff sensors: Hold the pairing button for 5 seconds.

The device should appear in the Zigbee2MQTT frontend within 30 seconds. It will also show up in Home Assistant as a new device under the MQTT integration, with all its entities (temperature, humidity, battery, etc.) automatically created.

Step 6: Essential Post-Setup Configuration

Enable Home Assistant Discovery

This should be on by default, but verify that homeassistant: true is in your Zigbee2MQTT configuration. This enables auto-discovery so devices appear in HA without manual entity creation.

Set Device-Friendly Names

In the Zigbee2MQTT frontend, click on each device and give it a human-readable name like "Kitchen Motion Sensor" instead of the default hex address. This name propagates to Home Assistant entities.

Build Your Mesh

Zigbee is a mesh network. Mains-powered devices (bulbs, smart plugs, repeaters) act as routers that extend range. Battery devices (sensors) are end devices that connect to the nearest router. For a strong mesh, aim for at least one mains-powered Zigbee device in every room. Check our coordinator setup guide for mesh planning tips.