Setting up Zigbee2MQTT on Home Assistant OS
What you need
Raspberry Pi running HAOS
Zigbee USB dongle plugged in
Mosquitto broker (MQTT) installed
Step 1 — Install Mosquitto broker
Settings → Apps → Install app → search Mosquitto broker → Install → Start
Step 2 — Add the Z2MQTT repository
Settings → Apps → Install app → three-dot menu (⋮) top right → Repositories → add:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
Step 3 — Install Zigbee2MQTT
Search for Zigbee2MQTT → install the non-Edge, non-Proxy version
Step 4 — Configure the dongle
Go to Zigbee2MQTT → Configuration → expand serial:
Port: /dev/serial/by-id/ — use the full path of your dongle (it'll appear in the onboarding screen)
Adapter: ember (for SONOFF dongles)
Save.
Step 5 — Start it
Info tab → Start → check Log tab for successful connection
Step 6 — Open the web UI
Info tab → Open Web UI → this is your Z2MQTT control panel
Step 7 — Pair devices
Click Enable join in the Z2MQTT sidebar, then put each device into pairing mode. They'll appear automatically.
Notes
Don't run ZHA and Z2MQTT at the same time — they'll fight over the dongle
If starting fresh, just never install ZHA at all
The Z2MQTT web UI is your main tool for managing devices
Please log in or sign up to comment.