GuideUpdated April 2026 · 12 min read

Zigbee2MQTT: Full Setup Guide for Home Assistant

Zigbee2MQTT gives you direct control over 3,000+ Zigbee devices via MQTT — more devices, more attributes, and more flexibility than ZHA. This guide covers installing the Mosquitto broker, configuring Zigbee2MQTT, pairing your first devices, and integrating with Home Assistant.

What you're setting up

1Mosquitto MQTT Broker — the message bus that carries all Zigbee data
2Zigbee2MQTT add-on — reads your USB coordinator, publishes device states to MQTT
3MQTT Integration in HA — auto-discovers all Z2M devices as HA entities

Prerequisites

✓

Home Assistant OS or Supervised

Add-ons are not available on HA Core or Container

✓

Zigbee USB coordinator

SONOFF Dongle Plus or SkyConnect recommended

✓

USB port on HA host

Or use a USB extension cable to avoid interference

✓

5 minutes

Seriously — this is fast once you know the steps

Step 1 — Install Mosquitto MQTT Broker

1

Add the Mosquitto add-on

Go to Settings → Add-ons → Add-on Store. Search for Mosquitto broker, click it, and hit Install. Enable Start on boot and Watchdog, then start it.

2

Add an MQTT user

Go to Settings → People → Users → Create user. Name it mqtt_user with a strong password. This is what Zigbee2MQTT and HA will authenticate with.

3

Add MQTT Integration to HA

Go to Settings → Devices & Services → Add Integration → MQTT. Broker: core-mosquitto, Port: 1883, enter your mqtt_user credentials. HA is now connected to the broker.

Step 2 — Find your coordinator's USB path

Plug in your Zigbee USB stick. In HA, go to Settings → System → Hardware and click the three-dot menu → All Hardware. Find your coordinator — it will be something like:

/dev/ttyUSB0 ← SONOFF Dongle Plus (CH340 chip)

/dev/ttyACM0 ← SkyConnect or CP2102 based dongles

/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus...

Tip: Always use the /dev/serial/by-id/path — it's stable across reboots. The /dev/ttyUSB0 path can change if you add other USB devices.

Step 3 — Install Zigbee2MQTT add-on

The official Z2M add-on is not in the default store — add the repository first:

1

Add the Z2M repository

Settings → Add-ons → Add-on Store → three-dot menu → Repositories. Add:

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

Install Zigbee2MQTT

Refresh the page, find "Zigbee2MQTT" in the store, install it. Enable Start on boot and Watchdog.

3

Configure the add-on before starting

Go to the Zigbee2MQTT add-on → Configuration tab. Set:

Zigbee2MQTT configuration.yaml

Edit this in the add-on's Configuration tab or directly at /config/zigbee2mqtt/configuration.yaml:

homeassistant:
  enabled: true          # Auto-discover all devices in HA

mqtt:
  server: mqtt://core-mosquitto:1883
  user: mqtt_user
  password: your_mqtt_password
  base_topic: zigbee2mqtt

serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus-if00
  # adapter: deconz      # uncomment for ConBee / RaspBee
  # adapter: ezsp        # uncomment for SkyConnect

# Zigbee network settings
advanced:
  network_key: GENERATE  # Z2M generates a unique key on first start
  pan_id: GENERATE
  channel: 15            # 15, 20, or 25 avoid WiFi 2.4 GHz overlap
  log_level: warning     # reduce to 'info' for debugging

# Frontend (optional — web UI at HA sidebar)
frontend:
  enabled: true
  port: 8099

# OTA firmware updates for supported devices
ota:
  update_check_interval: 1440  # check daily (minutes)

Step 4 — Pair your first device

Put Z2M in pairing mode first — open the Zigbee2MQTT frontend (sidebar → Zigbee2MQTT) and click Permit join (All). You have 254 seconds to pair.

SONOFF ZBMINIL2 relayHold the button for 5 seconds until LED flashes rapidly
Aqara sensorsPress reset button 3 times quickly with a pin
Ikea bulbsToggle power 6 times (on-off pattern) within 5 seconds
Philips Hue bulbsUse Touchlink factory reset or the Hue Dimmer Switch 3-tap method
Most sensorsLong press the pairing button until LED blinks 3x

Once paired, the device appears in the Z2M frontend under Devices and is auto-discovered in Home Assistant within seconds.

Zigbee mesh health tips

Keep coordinator central

Place the USB dongle centrally in your home — not in a back room. Use a USB extension cable to move it away from the PC/Pi USB interference field.

USB 2.0 port only

Plug the Zigbee dongle into a USB 2.0 port, not USB 3.0. USB 3.0 generates 2.4 GHz interference that degrades Zigbee range by 30–50%.

Add router devices first

Add mains-powered devices (plugs, switches, bulbs) before battery sensors. They become mesh routers and extend range for everything added later.

Check the network map

Zigbee2MQTT frontend → Map. You should see most devices within 1–2 hops of the coordinator. Long chains of 4+ hops cause latency and drop-outs.

Avoid channel 11

Zigbee channel 11 overlaps with WiFi channel 1. Use channel 15, 20, or 25. Set it in configuration.yaml before pairing your first device.

Group updates

Use Z2M Groups to send a single command to multiple devices (e.g., all lights off). Far more efficient than individual HA service calls.

Useful MQTT commands

Use the MQTT integration's dev tool (Developer Tools → MQTT) or any MQTT client:

# Get device state
Topic:   zigbee2mqtt/Living Room Light
Payload: (subscribe — no payload needed)

# Turn a device on/off
Topic:   zigbee2mqtt/Living Room Light/set
Payload: {"state": "ON"}
Payload: {"state": "OFF"}
Payload: {"state": "TOGGLE"}

# Set brightness and color temp (bulbs)
Topic:   zigbee2mqtt/Bedroom Bulb/set
Payload: {"brightness": 128, "color_temp": 350}

# Request OTA firmware update
Topic:   zigbee2mqtt/bridge/request/device/ota_update/update
Payload: {"id": "0x00158d0001234567"}

# Rename a device
Topic:   zigbee2mqtt/bridge/request/device/rename
Payload: {"from": "0x00158d0001234567", "to": "Kitchen Sensor"}

Frequently Asked Questions

Related Guides