Kort antwoord: Zigbee praat geen MQTT. Je hebt een vertaler nodig, en dat is Zigbee2MQTT. Die software leest via een USB-stick (de coördinator) wat je Zigbee-apparaten zenden, en publiceert dat als MQTT-berichten bij een broker — meestal Mosquitto. Andersom stuurt elk MQTT-bericht naar het juiste onderwerp een opdracht terug naar het apparaat.

Je hebt dus drie dingen nodig:

  1. Een Zigbee-coördinator — een USB-stick zoals de SONOFF ZBDongle-E of de Home Assistant Connect ZBT-1.
  2. Een MQTT-broker — Mosquitto, als Home Assistant-add-on of in Docker.
  3. Zigbee2MQTT — de brug tussen die twee.

Hieronder beide manieren om het op te zetten, en hoe je ziet dat het werkt.

Wat MQTT eigenlijk doet

MQTT is een berichtensysteem. Een broker ontvangt berichten op onderwerpen (topics) en geeft ze door aan iedereen die op dat onderwerp is geabonneerd. Zigbee2MQTT publiceert bijvoorbeeld:

zigbee2mqtt/Woonkamer sensor   {"temperature":21.4,"humidity":48,"battery":92}

En luistert op zigbee2mqtt/<apparaat>/set naar opdrachten:

zigbee2mqtt/Lamp keuken/set    {"state":"ON","brightness":180}

Het mooie daarvan: alles wat MQTT spreekt kan je Zigbee-apparaten lezen en bedienen — Home Assistant, Node-RED, een eigen script, een dashboard. Je zit niet vast aan één platform of merk.

Route 1: met Home Assistant (de makkelijkste)

Heb je Home Assistant OS, dan zijn het twee add-ons.

  1. Mosquitto installeren. Instellingen → Add-ons → Add-on store → Mosquitto broker → installeren en starten, met Start bij opstarten aan. Home Assistant vindt de broker daarna zelf onder Apparaten en diensten; bevestig de MQTT-integratie.
  2. Een gebruiker voor Zigbee2MQTT. Instellingen → Personen → Gebruikers → nieuwe gebruiker, bijvoorbeeld zigbee, met een eigen wachtwoord. Mosquitto accepteert Home Assistant-gebruikers als MQTT-login.
  3. Zigbee2MQTT installeren. Voeg in de Add-on store de repository https://github.com/zigbee2mqtt/hassio-zigbee2mqtt toe en installeer Zigbee2MQTT.
  4. De stick instellen. Zet in de configuratie van de add-on het serial-pad naar je stick. Gebruik het pad dat begint met /dev/serial/by-id/ — niet /dev/ttyUSB0, want dat nummer kan na een herstart verspringen.
  5. Starten. In het logboek zie je dat de coördinator wordt herkend en de verbinding met MQTT staat. Je apparaten verschijnen vanzelf in Home Assistant zodra je ze koppelt.

Ons volledige stappenplan, inclusief de keuze van de stick en het uitbouwen van het netwerk, staat in de handleiding Zigbee2MQTT.

Route 2: zonder Home Assistant, met Docker

Wil je MQTT gebruiken zonder Home Assistant — voor Node-RED, een eigen dashboard of een ander platform — dan draai je broker en Zigbee2MQTT zelf, bijvoorbeeld op een Raspberry Pi.

docker-compose.yml:

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-JOUW-STICK-if00:/dev/ttyACM0

mosquitto/config/mosquitto.conf — Mosquitto 2 accepteert zonder dit bestand alleen verbindingen van de eigen machine, en een container telt niet als de eigen machine:

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

Maak een gebruiker aan met docker compose run --rm mosquitto mosquitto_passwd -c /mosquitto/config/passwd zigbee.

zigbee2mqtt/data/configuration.yaml:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
  user: zigbee
  password: jouw-wachtwoord
serial:
  port: /dev/ttyACM0
  adapter: ember # SONOFF ZBDongle-E en ZBT-1; 'zstack' voor de ZBDongle-P
frontend:
  enabled: true
  port: 8080
advanced:
  channel: 20

Start alles met docker compose up -d. De webinterface van Zigbee2MQTT staat dan op poort 8080.

Controleren of het werkt

Abonneer je op alles onder zigbee2mqtt/ met de MQTT-client die bij Mosquitto zit:

mosquitto_sub -h localhost -u zigbee -P jouw-wachtwoord -t 'zigbee2mqtt/#' -v

Het eerste wat je moet zien is:

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

Zet in de webinterface Permit join aan (met een tijdslimiet), zet een apparaat in koppelmodus, en binnen een minuut verschijnen de berichten van dat apparaat. Probeer daarna een opdracht:

mosquitto_pub -h localhost -u zigbee -P jouw-wachtwoord -t 'zigbee2mqtt/Lamp keuken/set' -m '{"state":"TOGGLE"}'

Gaat de lamp aan, dan is je Zigbee aan MQTT gekoppeld.

Als het niet werkt

  • “Connection refused” naar de broker. Bij Docker: ontbreekt de listener 1883-regel in mosquitto.conf? Gebruik je in Zigbee2MQTT mqtt://mosquitto:1883 (de naam van de service), niet localhost?
  • “Not authorized”. De gebruiker of het wachtwoord klopt niet, of het passwd-bestand is niet gemaakt.
  • De stick wordt niet gevonden. Verkeerd serial-pad, of de verkeerde adapter. Een ZBDongle-E is ember, een ZBDongle-P is zstack — instructies online gaan vaak over de andere.
  • Apparaten vallen steeds weg. Bijna nooit MQTT, bijna altijd de radio: de stick zit direct naast een USB 3.0-poort of de router, of je Zigbee-kanaal ligt onder je wifi. Hang de stick aan een USB 2.0-verlengkabel en kies een kanaal met onze Zigbee-kanaalplanner — die vertelt ook naar welk wifi-kanaal je router moet als je Zigbee al draait en je niet alles opnieuw wilt koppelen.

Moet het per se via MQTT?

Nee. Home Assistant heeft ook ZHA, een ingebouwde Zigbee-integratie zonder broker. Die is sneller opgezet. Zigbee2MQTT ondersteunt meer apparaten, geeft meer instellingen per apparaat, en maakt je Zigbee-netwerk bruikbaar voor álles wat MQTT spreekt — niet alleen Home Assistant. Wil je later Node-RED, een eigen dashboard of een tweede systeem aansluiten, kies dan MQTT.

Liever dat het in één keer goed staat, met een netwerk dat het hele huis dekt? Dat doen we bij een smart home installatie.