Zigbee2MQTT installeren is een populaire manier om Zigbee-apparaten lokaal met Home Assistant te verbinden. Met Zigbee2MQTT kun je lampen, sensoren, slimme stekkers, schakelaars en veel andere Zigbee-apparaten van verschillende fabrikanten binnen één Zigbee-netwerk gebruiken.
Het grote voordeel is dat je niet afhankelijk bent van de afzonderlijke hubs van iedere fabrikant. Zigbee2MQTT communiceert met je Zigbee-coördinator en stuurt informatie via MQTT door naar Home Assistant.
De installatie bevat wel meer onderdelen dan bijvoorbeeld ZHA. Daarom lopen we in deze handleiding het volledige proces stap voor stap door: van Mosquitto en de Zigbee-dongle tot je eerste gekoppelde apparaat.
Let op: maak vooraf een Home Assistant-back-up en controleer altijd de actuele Zigbee2MQTT-documentatie voor jouw specifieke adapter. Firmware, adaptertypen en configuratieopties kunnen veranderen.
Wat is Zigbee2MQTT?
Zigbee2MQTT is open-source software die Zigbee-apparaten via MQTT laat communiceren met andere systemen, waaronder Home Assistant.
Je installatie bestaat grofweg uit:
Zigbee-apparaat → Zigbee-coördinator → Zigbee2MQTT → MQTT → Home Assistant
Hierdoor kun je apparaten van allerlei merken binnen hetzelfde Zigbee-netwerk gebruiken zonder voor ieder merk een aparte bridge te hoeven behouden.
Zigbee2MQTT heeft daarnaast een eigen webinterface waarin je apparaten kunt beheren, verbindingen kunt bekijken en instellingen kunt aanpassen.
Zigbee2MQTT versus ZHA
Home Assistant heeft met ZHA ook een ingebouwde oplossing voor Zigbee.
Welke moet je kiezen?
ZHA
ZHA is rechtstreeks geïntegreerd in Home Assistant.
Voordelen:
- Eenvoudige installatie
- Geen aparte MQTT-broker nodig
- Volledig geïntegreerd in Home Assistant
- Goede keuze voor beginners
Zigbee2MQTT
Zigbee2MQTT draait als afzonderlijke software en communiceert via MQTT.
Voordelen:
- Zeer uitgebreide apparaatondersteuning
- Eigen beheerinterface
- Veel configuratiemogelijkheden
- Uitgebreide informatie over apparaten
- Populair onder gevorderde Home Assistant-gebruikers
Wil je vooral zo eenvoudig mogelijk beginnen? Dan is ZHA aantrekkelijk.
Wil je veel controle over je Zigbee-netwerk en apparaten? Dan is Zigbee2MQTT installeren het overwegen waard.
Wat heb je nodig?
Voor deze handleiding gaan we uit van Home Assistant OS of een geschikte Supervised-installatie waarop je add-ons/apps kunt gebruiken. De Zigbee2MQTT-documentatie noemt de Home Assistant add-on hiervoor de eenvoudigste installatiemethode.
Je hebt nodig:
- Werkende Home Assistant-installatie
- Compatibele Zigbee-coördinator
- MQTT-broker
- Zigbee2MQTT add-on
- Minimaal één Zigbee-apparaat
- Bij een USB-adapter bij voorkeur een USB-verlengkabel
Gebruik je Home Assistant Container of een andere installatievorm? Dan verschilt de installatie. Zigbee2MQTT ondersteunt onder andere Docker en Linux, maar deze handleiding richt zich op Home Assistant OS.
Welke Zigbee-dongle heb je nodig?
De Zigbee-dongle is de coördinator van je netwerk. Deze vormt het centrale aanspreekpunt voor de Zigbee-apparaten.
Zigbee2MQTT ondersteunt verschillende adapters en chipsets. Controleer daarom vóór aanschaf altijd de actuele lijst met ondersteunde adapters.
Je kunt kiezen voor:
- USB-coördinator
- Ethernet/netwerkcoördinator
- Compatibele ingebouwde radio
Een netwerkcoördinator kan interessant zijn wanneer je Home Assistant-server op een ongunstige plek staat, bijvoorbeeld in een meterkast.
Gebruik je dongle niet tegelijkertijd met ZHA
Een Zigbee-coördinator kan niet zomaar gelijktijdig door ZHA en Zigbee2MQTT worden beheerd.
Gebruik je de adapter momenteel met ZHA? Verwijder of migreer die configuratie zorgvuldig voordat je dezelfde coördinator aan Zigbee2MQTT toewijst.
Bestaande Zigbee-apparaten kunnen bij een nieuwe netwerkconfiguratie opnieuw gekoppeld moeten worden.
Stap 1: maak een back-up
Maak voordat je begint een volledige Home Assistant-back-up.
Dat is vooral belangrijk wanneer je al Zigbee-apparaten gebruikt en wijzigingen aan bestaande integraties gaat uitvoeren.
Ga in Home Assistant naar de back-upinstellingen en maak een nieuwe back-up.
Bewaar belangrijke back-ups bij voorkeur ook buiten het Home Assistant-apparaat.
Stap 2: MQTT en Mosquitto installeren
Zigbee2MQTT heeft een MQTT-server/broker nodig om te functioneren. Voor Home Assistant is Mosquitto de eenvoudigste gebruikelijke oplossing. Home Assistant noemt de officiële Mosquitto Broker-app de eenvoudigste optie.
Open binnen Home Assistant de app/add-on store en zoek naar:
Mosquitto broker
Installeer Mosquitto en start de broker.
Controleer vervolgens onder:
Instellingen → Apparaten & diensten
of de MQTT-integratie aanwezig is.
Home Assistant kan bij gebruik van de officiële Mosquitto Broker de benodigde verbinding en inloggegevens grotendeels automatisch afhandelen.
Stap 3: Zigbee2MQTT installeren
Zigbee2MQTT wordt niet standaard met Home Assistant meegeleverd.
Voor Home Assistant OS kun je de officiële Zigbee2MQTT add-on repository toevoegen en vervolgens de Zigbee2MQTT add-on installeren.
Gebruik hiervoor de repository en installatie-instructies uit de officiële Zigbee2MQTT-documentatie, zodat je altijd het actuele adres en installatieproces gebruikt.
Na installatie start je Zigbee2MQTT en open je de webinterface.
Bij een nieuwe installatie beschikt Zigbee2MQTT over een onboardingproces waarmee je de belangrijkste instellingen kunt configureren.
Stap 4: Zigbee-dongle configureren
Nu moet Zigbee2MQTT weten welke coördinator het moet gebruiken.
Bij een USB-dongle is het verstandig om het stabiele apparaatpad te gebruiken, bijvoorbeeld een pad onder:
/dev/serial/by-id/in plaats van een generiek pad dat na een herstart kan veranderen.
Daarnaast moet het juiste adaptertype worden geselecteerd. Welk type je nodig hebt hangt af van de chipset van je coördinator.
De actuele Zigbee2MQTT-configuratie ondersteunt onder andere verschillende adapterfamilies. Gebruik de officiële adapterdocumentatie om het juiste type voor jouw hardware te bepalen.
Kopieer niet blind configuratiecode van een andere dongle. Een verkeerd adaptertype of serieel pad is een veelvoorkomende oorzaak van een Zigbee2MQTT-installatie die niet start.
Stap 5: verbinding met MQTT instellen
Zigbee2MQTT moet verbinding kunnen maken met je MQTT-broker.
Gebruik je Mosquitto binnen Home Assistant, dan kan Zigbee2MQTT daarvoor de interne brokerverbinding gebruiken. In de officiële Zigbee2MQTT-documentatie wordt core-mosquitto genoemd voor de Mosquitto Home Assistant add-on.
Controleer tijdens de onboarding:
- MQTT-server
- Gebruikersgegevens indien nodig
- Zigbee-adapter
- Seriële poort
- Adaptertype
- Home Assistant-integratie
Bewaar wachtwoorden niet onnodig in publiek toegankelijke configuratiebestanden.
Stap 6: Home Assistant-integratie activeren
Om apparaten automatisch in Home Assistant zichtbaar te maken gebruik je MQTT Discovery.
Zigbee2MQTT ondersteunt hiervoor:
homeassistant:
enabled: trueDaarnaast moet de MQTT-integratie in Home Assistant actief zijn. Zigbee2MQTT noemt MQTT Discovery de eenvoudigste manier om apparaten met Home Assistant te integreren.
Na correcte configuratie kunnen ondersteunde apparaten en hun entiteiten automatisch in Home Assistant verschijnen.
Stap 7: eerste Zigbee-apparaat koppelen
Nu kun je je eerste apparaat toevoegen.
Open de Zigbee2MQTT-interface en activeer tijdelijk Permit join.
Zet vervolgens het Zigbee-apparaat in koppelmodus. Hoe dat werkt verschilt per fabrikant.
Vaak moet je:
- Een resetknop enkele seconden ingedrukt houden.
- Wachten tot een LED begint te knipperen.
- Het apparaat dicht bij de coördinator plaatsen.
- Wachten totdat Zigbee2MQTT het apparaat ontdekt.
Geef het apparaat daarna een duidelijke naam, bijvoorbeeld:
bewegingssensor_halof:
temperatuursensor_slaapkamerSchakel koppelen na afloop weer uit. Zigbee2MQTT opent joining standaard slechts tijdelijk wanneer je dit activeert, wat veiliger is dan het netwerk permanent open laten staan.
Stap 8: apparaten zichtbaar maken in Home Assistant
Wanneer MQTT Discovery correct is ingesteld, verschijnen gekoppelde apparaten automatisch via de MQTT-integratie.
Ga naar:
Instellingen → Apparaten & diensten → MQTT
Daar kun je de nieuwe apparaten en bijbehorende entiteiten terugvinden.
Afhankelijk van het apparaat zie je bijvoorbeeld:
- Temperatuur
- Luchtvochtigheid
- Batterijniveau
- Beweging
- Verlichting
- Energieverbruik
- Knoppen en acties
Je kunt deze entiteiten vervolgens gebruiken in dashboards en automatiseringen.
Zigbee-netwerk verbeteren
Een stabiel Zigbee-netwerk draait niet alleen om een goede coördinator.
Gebruik een USB-verlengkabel
Bij een USB-coördinator raadt Zigbee2MQTT een USB-verlengkabel aan om interferentie te verminderen. Dit is zelfs een van de eerste aanbevolen stappen bij problemen zoals time-outs, apparaten die wegvallen of mislukte koppelingen.
Voeg Zigbee-routers toe
Veel apparaten op netspanning functioneren als Zigbee-router.
Denk aan geschikte:
- Slimme stekkers
- Lampen
- Inbouwmodules
Deze kunnen het mesh-netwerk uitbreiden.
Batterijgevoede sensoren zijn meestal eindapparaten en versterken het netwerk doorgaans niet.
Let op 2,4GHz-wifi
Zigbee en 2,4GHz-wifi gebruiken dezelfde frequentieband. Een slechte kanaalkeuze kan daardoor storing veroorzaken.
Plan je Zigbee- en wifi-kanalen zorgvuldig, vooral in woningen met veel accesspoints en draadloze apparaten.
Plaats de coördinator centraal
Een USB-dongle achter een metalen computerkast of diep in de meterkast is niet ideaal.
Plaats de coördinator waar mogelijk vrij en op enige afstand van storingsbronnen.
Updates en back-ups
Werk Zigbee2MQTT regelmatig bij, maar lees bij grote updates eerst de release notes.
Maak daarnaast back-ups van je Home Assistant-installatie en Zigbee2MQTT-gegevens.
De Zigbee2MQTT-datamap bevat belangrijke informatie over je configuratie en netwerk. Sommige adapterfamilies ondersteunen bovendien coordinatorback-ups. Volgens de actuele documentatie geldt dit voor zStack- en EmberZNet-gebaseerde adapters.
Bewaar belangrijke back-ups buiten het apparaat waarop Home Assistant draait.
Veelvoorkomende problemen
Zigbee2MQTT start niet
Controleer eerst:
- Seriële poort
- Adaptertype
- MQTT-verbinding
- Logboek van Zigbee2MQTT
Een verkeerd adaptertype of apparaatpad is vaak de oorzaak.
Adapter is al in gebruik
Controleer of ZHA of andere software dezelfde Zigbee-coördinator gebruikt.
Slechts één toepassing moet de coördinator beheren.
Apparaten willen niet koppelen
Controleer of Permit join actief is.
Reset het apparaat volgens de instructies van de fabrikant en probeer het tijdens de eerste koppeling dichter bij de coördinator.
Een USB-verlengkabel kan helpen wanneer interferentie het probleem veroorzaakt.
Apparaat verschijnt niet in Home Assistant
Controleer:
Werkt MQTT?
- Is de MQTT-integratie actief?
- Staat Home Assistant-integratie/MQTT Discovery aan in Zigbee2MQTT?
- Is het apparaat succesvol gekoppeld?
- Apparaten vallen regelmatig offline
Controleer de plaatsing van je coördinator en voeg voldoende Zigbee-routers toe.
Kijk daarnaast naar mogelijke interferentie met wifi en USB 3.0-apparatuur.
Is Zigbee2MQTT veilig?
Houd Zigbee2MQTT, Home Assistant en Mosquitto bijgewerkt en stel de webinterface of MQTT-broker niet onbeveiligd beschikbaar op internet.
Zigbee2MQTT waarschuwt expliciet dat zowel MQTT als de frontend toegang geven tot belangrijke onderdelen van het Zigbee-netwerk. Onbetrouwbare publieke toegang moet daarom worden voorkomen.
Gebruik sterke inloggegevens en beperk toegang tot je lokale netwerk of een goed beveiligde externe verbinding.
Veelgestelde vragen
Wat is Zigbee2MQTT?
Zigbee2MQTT is software waarmee Zigbee-apparaten via een Zigbee-coördinator en MQTT kunnen communiceren met systemen zoals Home Assistant.
Is Zigbee2MQTT gratis?
Ja. Zigbee2MQTT is open-source software en gratis te gebruiken. Je hebt wel geschikte hardware nodig, zoals een Zigbee-coördinator.
Heb ik MQTT nodig voor Zigbee2MQTT?
Ja. Zigbee2MQTT vereist een MQTT-broker. Binnen Home Assistant is Mosquitto een populaire en eenvoudige keuze.
Wat is beter: ZHA of Zigbee2MQTT?
Dat hangt af van je wensen. ZHA is eenvoudiger en direct geïntegreerd in Home Assistant. Zigbee2MQTT biedt veel configuratiemogelijkheden en uitgebreide ondersteuning. Voor beginners kan ZHA eenvoudiger zijn; enthousiaste gebruikers kiezen vaak Zigbee2MQTT vanwege de extra controle.
Kan ZHA en Zigbee2MQTT tegelijkertijd?
Je kunt beide binnen één Home Assistant-omgeving gebruiken wanneer ze ieder een eigen Zigbee-coördinator en Zigbee-netwerk hebben. Gebruik niet dezelfde adapter tegelijkertijd voor beide systemen.
Moet ik mijn Zigbee-apparaten opnieuw koppelen?
Wanneer je vanaf een ander Zigbee-netwerk naar een volledig nieuwe Zigbee2MQTT-configuratie overstapt, moet je er rekening mee houden dat apparaten opnieuw gekoppeld moeten worden. Een migratie kan afhankelijk van de bestaande coordinator en configuratie anders verlopen.
Welke Zigbee-dongle is het beste?
Er bestaat niet één beste dongle voor iedereen. Kies een adapter die officieel door Zigbee2MQTT wordt ondersteund en past bij je installatie. Controleer vóór aankoop altijd de actuele ondersteunde-adapterlijst.
Werkt Zigbee2MQTT zonder internet?
De normale communicatie tussen Zigbee2MQTT, een lokale MQTT-broker en Home Assistant kan lokaal plaatsvinden. Internet blijft wel nodig voor bijvoorbeeld updates en bepaalde externe diensten.
Hoe voeg ik een apparaat toe?
Activeer tijdelijk Permit join in Zigbee2MQTT en zet het apparaat in de koppelmodus. Zodra het succesvol is toegevoegd, schakel je joining weer uit.
Gerelateerde artikelen
Welke Home Assistant hardware heb je nodig? Complete koopgids (2026)
Home Assistant installeren: stap voor stap handleiding
Home Assistant op een oude laptop installeren: stap voor stap
De 10 beste Home Assistant integraties die iedereen zou moeten gebruiken
Home Assistant automatiseringen: 10 handige voorbeelden voor beginners
HACS installeren in Home Assistant: complete handleiding voor beginners
Conclusie
Zigbee2MQTT installeren vraagt iets meer configuratie dan simpelweg een Zigbee-integratie activeren, maar je krijgt er een krachtige en flexibele oplossing voor terug.
Voor een Home Assistant OS-installatie bestaat de basis uit drie onderdelen: een ondersteunde Zigbee-coördinator, een MQTT-broker zoals Mosquitto en de Zigbee2MQTT add-on. Zodra MQTT Discovery correct is ingesteld, kunnen gekoppelde apparaten automatisch in Home Assistant verschijnen.
Begin met één apparaat en controleer eerst of alles stabiel werkt. Bouw daarna je Zigbee-mesh geleidelijk uit met goed geplaatste routers en geef aandacht aan de positie van de coördinator.
Daarmee leg je een sterke basis voor een lokaal Zigbee-netwerk waarop je later verlichting, sensoren, slimme stekkers en automatiseringen kunt aansluite