Zigbee2MQTT Setup for Beginners: From Dongle to First Device

1. What Zigbee2MQTT Does (vs ZHA)

Zigbee is a low-power wireless protocol used by hundreds of smart home devices — Aqara sensors, IKEA bulbs, Sonoff switches, Philips Hue, and many more. To use them with Home Assistant, you need a Zigbee coordinator (a USB dongle) and software to bridge that network to HA.

You have two main options: ZHA (Zigbee Home Automation) — built into HA, simpler to set up — and Zigbee2MQTT — more powerful, supports more devices, and uses MQTT as the transport. Zigbee2MQTT supports over 3,000 devices (far more than ZHA) and gives you full access to every device attribute. It's the better choice if you have mixed brands or less common devices.

The trade-off: Zigbee2MQTT requires MQTT broker (Mosquitto) to be running. That's one extra add-on, but it takes two minutes to install and you'll likely use it for other things too.

2. Installing the Zigbee2MQTT Add-on

First, install the Mosquitto MQTT broker:

1. Go to Settings → Add-ons → Add-on Store
2. Search for Mosquitto broker, install it, and start it
3. Go to Settings → Devices & Services — HA will auto-discover Mosquitto and add the MQTT integration

Then add the Zigbee2MQTT repository and install the add-on:

1. In Add-on Store, click the three-dot menu (top right) → Repositories
2. Add: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
3. Search for Zigbee2MQTT, install it (don't start it yet)

3. Finding Your Coordinator's Serial Port

Plug the Sonoff Dongle Plus into a USB port on your HA device. To find its serial port:

1. Go to Settings → System → Hardware
2. Click All Hardware and look for a USB serial device — the Sonoff dongle will typically show up as /dev/ttyUSB0 or /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus...

4. Configuration YAML

Before starting Zigbee2MQTT, open its Configuration tab in the add-on and paste your complete configuration.yaml:

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883
serial:
  port: /dev/ttyUSB0
advanced:
  log_level: info
  network_key: GENERATE
frontend:
  port: 8099

Key settings explained:

• homeassistant: true — enables HA MQTT discovery so devices appear automatically in HA
• permit_join: false — keeps pairing mode off by default (you enable it per-session)
• network_key: GENERATE — on first start, generates a unique encryption key for your Zigbee network
• frontend: port: 8099 — enables the Zigbee2MQTT web UI, accessible at your HA IP on port 8099

Now start the Zigbee2MQTT add-on and watch the logs. You should see it connect to MQTT, initialize the coordinator, and log the network key it generated. Copy that key — it's stored in your config file automatically after first start.

5. Pairing Your First Device

To pair a device, you need to temporarily enable permit_join. There are two ways:

Option A — Zigbee2MQTT frontend: Open http://YOUR-HA-IP:8099, click Permit join (All), then trigger your device's pairing mode (usually hold the reset button 5–10 seconds until the LED flashes rapidly).

Option B — HA dashboard: The Z2M add-on exposes a permit_join switch in HA. Toggle it on, pair your device, toggle it off.

Once paired, your device appears in the Zigbee2MQTT frontend's device list within seconds. Rename it there — the friendly name becomes the entity name in HA.

6. Understanding the Device List and HA Entities

After pairing, each device in Zigbee2MQTT creates one or more entities in Home Assistant. A motion sensor might create:

• binary_sensor.motion_sensor_occupancy — motion detected on/off
• sensor.motion_sensor_battery — battery percentage
• sensor.motion_sensor_linkquality — Zigbee signal strength

Go to Settings → Devices & Services → MQTT in HA and find your device. You can rename entities here or through the device page. Give them sensible names now — it saves confusion later in automations.

7. Your First Automation Using a Zigbee Device

Let's create a motion-activated light automation. Go to Settings → Automations → Create Automation → Edit in YAML and paste:

alias: "Motion Light"
trigger:
  - platform: state
    entity_id: binary_sensor.motion_sensor_occupancy
    to: "on"
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room
    data:
      brightness: 200
      transition: 1
condition: []
mode: single

This automation fires whenever your motion sensor detects movement and turns on the living room light at brightness 200 (out of 255) with a 1-second transition. Adjust the entity IDs to match yours.

To also turn the light off when motion stops, add a second automation or use a more advanced script with wait_for_trigger — see our automation YAML guide for that pattern.

8. Troubleshooting

Zigbee2MQTT won't start — "Error: Failed to open serialport"

The serial port path is wrong. Check Settings → System → Hardware again and confirm the exact path. Also make sure no other add-on (like ZHA) is using the dongle simultaneously — you can only have one coordinator per USB stick.

Device pairs but doesn't appear in HA

Ensure homeassistant: true is in your config and that the MQTT integration in HA is connected. Go to Developer Tools → MQTT and subscribe to zigbee2mqtt/# — you should see messages when your device reports. If not, check the Mosquitto broker logs.

Device drops off the network

Range and interference are the most common causes. Zigbee uses 2.4GHz — the same band as Wi-Fi. Try moving the dongle away from your router using a USB extension cable (30cm or more). Mains-powered Zigbee devices act as routers and extend the mesh — adding a few plugs or bulbs near battery sensors improves stability.

Pairing mode times out before device pairs

Some devices need to be very close to the coordinator for initial pairing. Try pairing within 1 meter, then move the device to its final location after it joins.

9. FAQ

SmartWired participates in the Amazon Associates Programme. We may earn a commission from qualifying purchases at no extra cost to you.