# Connecting Zigbee to MQTT: how it works, step by step

> How do you connect Zigbee to MQTT? You need a Zigbee stick, an MQTT broker and Zigbee2MQTT. Here's how to set them up — with Home Assistant or standalone with Docker — and how to check it works.

- **Published:** 2026-10-14
- **Language:** English (en)
- **Canonical URL:** https://divsoftware.nl/en/blog/connect-zigbee-to-mqtt/
- **Keywords:** connect zigbee to mqtt, zigbee mqtt, install zigbee2mqtt, mosquitto mqtt broker, zigbee2mqtt docker, zigbee home assistant
- **Author:** Division Software — software studio in Eindhoven, the Netherlands
- **Translation:** https://divsoftware.nl/blog/zigbee-koppelen-aan-mqtt/

---

**Short answer:** Zigbee doesn't speak MQTT. You need a translator, and that's **Zigbee2MQTT**. It reads what your Zigbee devices transmit through a USB stick (the _coordinator_) and publishes it as MQTT messages to a **broker** — usually Mosquitto. The other way round, any MQTT message to the right topic sends a command back to the device.

So you need three things:

1. **A Zigbee coordinator** — a USB stick such as the SONOFF ZBDongle-E or the Home Assistant Connect ZBT-1.
2. **An MQTT broker** — Mosquitto, as a Home Assistant add-on or in Docker.
3. **Zigbee2MQTT** — the bridge between the two.

Below are both ways to set it up, and how to see that it works.

## What MQTT actually does

MQTT is a messaging system. A **broker** receives messages on _topics_ and passes them on to everyone subscribed to that topic. Zigbee2MQTT publishes, for example:

```
zigbee2mqtt/Living room sensor   {"temperature":21.4,"humidity":48,"battery":92}
```

And listens on `zigbee2mqtt/<device>/set` for commands:

```
zigbee2mqtt/Kitchen light/set    {"state":"ON","brightness":180}
```

The nice thing: anything that speaks MQTT can read and control your Zigbee devices — Home Assistant, Node-RED, your own script, a dashboard. You're not tied to one platform or brand.

## Route 1: with Home Assistant (the easiest)

On Home Assistant OS, it's two add-ons.

1. **Install Mosquitto.** Settings → Add-ons → Add-on store → _Mosquitto broker_ → install and start, with _Start on boot_ on. Home Assistant then finds the broker itself under Devices & services; confirm the MQTT integration.
2. **A user for Zigbee2MQTT.** Settings → People → Users → new user, say `zigbee`, with its own password. Mosquitto accepts Home Assistant users as MQTT logins.
3. **Install Zigbee2MQTT.** Add the repository `https://github.com/zigbee2mqtt/hassio-zigbee2mqtt` in the Add-on store and install _Zigbee2MQTT_.
4. **Point it at the stick.** In the add-on's configuration, set the serial path to your stick. Use the path starting with `/dev/serial/by-id/` — not `/dev/ttyUSB0`, which can change number after a reboot.
5. **Start it.** The log shows the coordinator being recognised and the MQTT connection up. Devices appear in Home Assistant by themselves as you pair them.

Our full walkthrough, including choosing the stick and building out the network, is in the [Zigbee2MQTT guide](/en/guides/zigbee2mqtt-network/).

## Route 2: without Home Assistant, with Docker

To use MQTT without Home Assistant — for Node-RED, your own dashboard or another platform — run the broker and Zigbee2MQTT yourself, for example on a Raspberry Pi.

**`docker-compose.yml`:**

```yaml
services:
  mosquitto:
    image: eclipse-mosquitto:2
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data

  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Amsterdam
    volumes:
      - ./zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/serial/by-id/usb-YOUR-STICK-if00:/dev/ttyACM0
```

**`mosquitto/config/mosquitto.conf`** — without this file Mosquitto 2 only accepts connections from its own machine, and a container doesn't count as its own machine:

```
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
```

Create a user with `docker compose run --rm mosquitto mosquitto_passwd -c /mosquitto/config/passwd zigbee`.

**`zigbee2mqtt/data/configuration.yaml`:**

```yaml
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
  user: zigbee
  password: your-password
serial:
  port: /dev/ttyACM0
  adapter: ember # SONOFF ZBDongle-E and ZBT-1; 'zstack' for the ZBDongle-P
frontend:
  enabled: true
  port: 8080
advanced:
  channel: 20
```

Start everything with `docker compose up -d`. Zigbee2MQTT's web interface is then on port 8080.

## Checking it works

Subscribe to everything under `zigbee2mqtt/` with the MQTT client that ships with Mosquitto:

```
mosquitto_sub -h localhost -u zigbee -P your-password -t 'zigbee2mqtt/#' -v
```

The first thing you should see is:

```
zigbee2mqtt/bridge/state {"state":"online"}
```

Turn on **Permit join** in the web interface (with a time limit), put a device in pairing mode, and within a minute its messages appear. Then try a command:

```
mosquitto_pub -h localhost -u zigbee -P your-password -t 'zigbee2mqtt/Kitchen light/set' -m '{"state":"TOGGLE"}'
```

If the light turns on, your Zigbee is connected to MQTT.

## If it doesn't work

- **"Connection refused" to the broker.** With Docker: is the `listener 1883` line missing from `mosquitto.conf`? Are you using `mqtt://mosquitto:1883` (the service name) in Zigbee2MQTT, not `localhost`?
- **"Not authorized".** Wrong user or password, or the `passwd` file was never created.
- **The stick isn't found.** Wrong serial path, or the wrong `adapter`. A ZBDongle-E is `ember`, a ZBDongle-P is `zstack` — instructions online are often for the other one.
- **Devices keep dropping off.** Almost never MQTT, almost always the radio: the stick is right next to a USB 3.0 port or the router, or your Zigbee channel sits under your Wi-Fi. Put the stick on a USB 2.0 extension cable and pick a channel with our [Zigbee channel planner](/en/tools/zigbee-wifi-channel/) — it also tells you which Wi-Fi channel to move your router to if your Zigbee is already running and you don't want to re-pair everything.

## Does it have to go through MQTT?

No. Home Assistant also has **ZHA**, a built-in Zigbee integration without a broker. It's quicker to set up. Zigbee2MQTT supports more devices, gives more settings per device, and makes your Zigbee network usable by _anything_ that speaks MQTT — not only Home Assistant. If you might later connect Node-RED, your own dashboard or a second system, go with MQTT.

Rather have it set up right in one go, with a network that covers the whole house? That's our [smart home installation](/en/smart-home-installation/).

---

*This is the Markdown (AI-readable) version of an article by [Division Software](https://divsoftware.nl/) — we build websites, web shops, apps and custom software for businesses in the Netherlands. Read the full article at https://divsoftware.nl/en/blog/connect-zigbee-to-mqtt/, or request a free, no-obligation quote at https://divsoftware.nl/en/quote/.*