Starting Home Assistant with Zigbee
You want Home Assistant, Zigbee lights and sensors, and your home on your phone. This page covers the hardware, and the steps from an empty Home Assistant to your devices in ZigDash.
ZHA or Zigbee2MQTT?
Home Assistant can run Zigbee in two ways, and you choose once, when you plug in the Zigbee adapter. Changing later means pairing every device again.
| ZHA | Zigbee2MQTT | |
|---|---|---|
| What it is | Home Assistant's own Zigbee, built in | A separate app, connected through MQTT |
| Setting up | A few taps | Two apps to install: Mosquitto and Zigbee2MQTT |
| Devices | Many | A very long supported-device list, and more settings per device |
| Without Home Assistant | No | Yes: your Zigbee keeps its own web page |
| ZigDash | Doesn't work | Works |
Both are good. If you want ZigDash on your phone or a wall tablet, choose Zigbee2MQTT. Already on ZHA? See Moving from ZHA.
What to get
- Something to run Home Assistant: a Home Assistant Green (ready to plug in), or a Raspberry Pi 4 or 5, or a small PC you install Home Assistant OS on.
- A Zigbee adapter (also called a coordinator):
- Home Assistant Connect ZBT-2 or ZBT-1: Home Assistant's own USB adapters.
- Sonoff ZBDongle-E or ZBDongle-P: cheap and widely used USB adapters.
- SMLIGHT SLZB-06: a network adapter that sits on your router, so you can place it in the middle of the house.
- For a USB adapter, a USB extension cable of a metre or so. USB 3 ports, SSDs and Wi-Fi disturb Zigbee when the adapter is plugged in right next to them.
From an empty Home Assistant to ZigDash
These steps are for Home Assistant OS, where Settings shows Apps (Add-ons on older versions). Home Assistant Green and the Pi image are Home Assistant OS. In Docker, see Home Assistant in Docker.
- Set up Home Assistant and make your user.
- Plug in the Zigbee adapter on its extension cable. Home Assistant may find it and offer to set it up for ZHA or Thread. Choose Ignore: the adapter is for Zigbee2MQTT.
- In Settings › Apps, install and start Mosquitto broker. Home Assistant then offers the MQTT integration under Settings › Devices & services: accept it.
- Zigbee2MQTT isn't in the default app store. In the app store, open ⋮ › Repositories and add
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt, then install Zigbee2MQTT. - In its Configuration tab, set the serial port and the adapter type from the adapter list, then start it and open its web page.
- Pair your devices: in Zigbee2MQTT's web page, turn on Permit join, then put each device in pairing mode (usually a long press, or switching a bulb on and off a few times). Mains-powered devices first, then battery ones.
- On your phone, install ZigDash, tap Find my setup, choose Home Assistant, and sign in with Home Assistant. The dashboard builds itself from your devices. More detail: ZigDash with Home Assistant.
Without Home Assistant
If you only want Zigbee devices on your phone, you don't need Home Assistant: an SMLIGHT SMHUB runs Zigbee2MQTT itself. See Hubs we recommend. You can add Home Assistant later; it connects to the same Zigbee2MQTT.