← Alle gidsen

MQTT voor beginners: wat het is, hoe het werkt en wanneer je het nodig hebt

Je komt MQTT tegen zodra je een slim apparaat hebt dat niet van een grote fabrikant komt: een zelfgebouwde sensor, een Tasmota-plug, een Zigbee-brug. Het is geen merk en geen app, maar een afspraak over hoe apparaten berichten uitwisselen.

Het idee in drie zinnen

Alle apparaten sturen hun berichten naar één centraal programma: de broker. Elk bericht heeft een onderwerp, het topic, en de broker geeft het door aan iedereen die op dat onderwerp geabonneerd is. Zender en ontvanger hoeven elkaar dus niet te kennen – dat is precies het verschil met een directe verbinding.

MQTT-broker (Mosquitto) in Docker met Home Assistant dat verbinding maakt
Mosquitto als broker in een container, met Home Assistant als abonnee.

Wat je nodig hebt

  • Een broker. Mosquitto is de standaard, en draait prima in Docker.
  • Home Assistant met de MQTT-integratie.
  • Een apparaat of sensor die MQTT praat: Tasmota, ESPHome (dat kan het ook), of je eigen code.
  • Een gebruikersnaam en wachtwoord – geen open broker op je netwerk.

Stap 1: Mosquitto opzetten

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

Zet in config/mosquitto.conf in elk geval allow_anonymous false en een wachtwoordbestand. Een broker zonder wachtwoord in je netwerk is een open deur.

Stap 2: Home Assistant verbinden

Instellingen → Apparaten & diensten → Integratie toevoegen → MQTT. Vul het IP-adres van je broker in, de poort 1883 en de inloggegevens. Daarna zie je onder MQTT alle topics voorbijkomen.

Stap 3: een topic begrijpen

Topics zijn paden met een schuine streep, bijvoorbeeld:

home/woonkamer/temperatuur      -> 21.4
home/woonkamer/luchtvochtigheid -> 48
huis/sensor1/status             -> online

Je abonneert je op home/woonkamer/# en krijgt alles binnen wat onder die map valt. Het #-teken is de jokerteken voor "alles hieronder".

QoS bepaalt de leveringszekerheid: 0 is "verstuur en hoop", 1 is "minstens één keer", 2 is "precies één keer". Voor sensordata is 0 prima; voor schakelcommando's is 1 verstandiger.

MQTT Explorer met topics en waarden van sensoren
Met MQTT Explorer zie je live wat er over de broker gaat. Handig bij het debuggen.

Wat niet werkt (en waarom)

  • Een broker zonder authenticatie. Iedereen op je netwerk kan dan je lampen bedienen of je data meelezen. Altijd een gebruiker en wachtwoord.
  • Retained berichten vergeten. Zonder retain is een topic leeg tot het apparaat opnieuw stuurt. Voor statusberichten wil je retain aan.
  • Alles op QoS 2 zetten. Dat kost meer verkeer en vertraging zonder dat je er bij sensordata iets mee opschiet.
  • Topics met hoofdletters en spaties. MQTT is hoofdlettergevoelig. Woonkamer/Temp en woonkamer/temp zijn twee verschillende dingen.

Snel oplossen: symptoom, oorzaak, oplossing

SymptoomMeestal de oorzaakOplossing
HA ziet het apparaat nietVerkeerd topic of geen retainMet MQTT Explorer kijken wat er echt binnenkomt
Verbinding geweigerdAnoniem uit, verkeerde inloggegevensWachtwoordbestand en gebruiker controleren
Waarden blijven oudApparaat stuurt niet meerexpire_after instellen zodat HA het als onbekend markeert
Werkt na herstart nietData-volume niet gemountVolume voor /mosquitto/data toevoegen
Alles dubbel in HAOntdekkingsberichten twee keerOude entiteiten verwijderen en opnieuw laten ontdekken

Veelgestelde vragen

Heb ik MQTT nodig voor ESPHome?

Nee. ESPHome praat native met Home Assistant via de eigen API. MQTT is nuttig als je apparaten van verschillende merken mengt, of als je iets buiten Home Assistant om wilt uitlezen.

Wat is het verschil met Zigbee of Z-Wave?

Dat zijn radiostandaarden voor de verbinding tussen apparaat en hub. MQTT is een berichtenprotocol over je netwerk. Vaak zie je ze samen: een Zigbee-brug zet de berichten om naar MQTT.

Moet de broker op een aparte machine?

Nee, een container naast Home Assistant is prima. Zet hem wel op een vast IP en zorg voor een back-up van je configuratie.

Retain, Last Will en beschikbaarheid

Een retained bericht is de laatst bekende waarde die de broker bewaart voor een topic. Een nieuw apparaat dat zich abonneert, ontvangt die waarde meteen. Dat is handig voor een actuele temperatuur of de ingestelde status van een apparaat. Gebruik retain niet blind voor een eenmalig commando: een oud commando kan anders na opnieuw verbinden opnieuw worden ontvangen.

Met een Last Will and Testament (LWT) kan een MQTT-client vooraf een statusbericht instellen dat de broker publiceert wanneer de verbinding onverwacht wegvalt. Een veelgebruikte indeling is online en offline. Laat de client bij het verbinden zelf online publiceren en stel offline als Last Will in. Zo kan Home Assistant zien dat een sensor niet meer bereikbaar is.

Een nette topicstructuur kiezen

Kies een vaste naamgeving voordat je tientallen apparaten toevoegt. Bijvoorbeeld huis/kamer/apparaat/meetwaarde. Gebruik kleine letters, geen spaties en houd namen consequent. Maak topics niet onnodig lang, maar zorg wel dat een topic zonder extra documentatie begrijpelijk is.

Beveiliging en netwerk

  • Gebruik unieke brokeraccounts en een sterk wachtwoord.
  • Stel anonieme toegang uitgeschakeld in.
  • Expose poort 1883 niet rechtstreeks naar het internet.
  • Gebruik TLS als MQTT-verkeer over een netwerk gaat dat je niet vertrouwt.
  • Maak een back-up van brokerconfiguratie en persistent data.

MQTT stap voor stap debuggen

  1. Controleer of de broker actief is en op het verwachte IP-adres luistert.
  2. Test met een MQTT-client of je kunt aanmelden.
  3. Abonneer op één exact topic en daarna eventueel op een wildcard.
  4. Publiceer een testbericht zonder retain en controleer of het aankomt.
  5. Controleer daarna pas Home Assistant-discovery en entiteiten.

Door eerst de broker los van Home Assistant te testen, weet je of het probleem in het netwerk, de authenticatie, het topic of de integratie zit. Dat scheelt veel zoekwerk.

Verder lezen

Home Assistant back-ups: wat erin zit en zo herstel je ze echt →