MQTT-integratie

MQTT-integratie

MQTT verbindt HyperVisu met de publish/subscribe-wereld: Zigbee2MQTT, Tasmota, Shelly (MQTT-modus), ESPHome, energie-gateways en alle aangepaste firmware die communiceert met een MQTT-broker. HyperVisu is een MQTT-client — het abonneert op de topics waarop apparaten hun status publiceren en publiceert commando's op de topics waarnaar apparaten luisteren. Er is geen polling: een apparaat waarvan de status verandert, publiceert direct, en de widget wordt meteen bijgewerkt.

Een broker bevindt zich in het midden. Dit kan een broker zijn die u al gebruikt (Mosquitto, EMQX, de broker die wordt meegeleverd met een Zigbee2MQTT-installatie, …) of de in HyperVisu ingebouwde broker, die de server zelf kan uitvoeren zodat apparaten er rechtstreeks verbinding mee maken (zie "De ingebouwde MQTT-broker"). Alles in dit artikel is op beide manieren van toepassing — de ingebouwde broker is een gewone broker, bereikbaar via een reguliere verbinding.

Wat u nodig heeft: het brokeradres en de poort, de inloggegevens indien vereist, en de topics en het payload-formaat van het apparaat — uit de documentatie van het apparaat, of direct uitgelezen van de broker met de topic-browser (hieronder).

Verbindingen. Schakel eerst MQTT Protocol in op de pagina Diensten (zie "Diensten & protocollen"); dit staat standaard uit op een nieuwe server. MQTT ondersteunt meerdere verbindingen: één verbinding per broker (zie "Verbindingen"). Selecteer bij Verbinding toevoegen de kaart MQTT: het dialoogvenster vraagt om een Instantienaam, het Brokeradres, de Poort, de Client-ID en de inloggegevens, en bevat een knop Testen. CA-certificaat en de Broker-opties (Keepalive, Standaard QoS, Beschikbaarheidstopic, Clean session) staan niet in het dialoogvenster: stel deze in op de opgeslagen verbinding, die direct in de editor opent zodra u op Verbinding aanmaken klikt. De verbindingseditor bevat:

Testen op een MQTT-verbinding is een echte test: de server maakt verbinding met de broker en wacht op de bevestiging (binnen 10 s). Een goed resultaat toont Verbinding geslaagd. In het dialoogvenster Verbinding toevoegen test Testen de ingevoerde waarden voordat u de verbinding aanmaakt. Bij een opgeslagen verbinding controleert Testen de opgeslagen configuratie, niet de nog niet opgeslagen velden: klik eerst op Verbinding opslaan en daarna op Testen. Een geslaagde test bewijst dat het adres, de poort, de inloggegevens en de TLS-instellingen door de broker worden geaccepteerd; het bewijst niet dat een topic gegevens bevat.

De status van de verbinding geeft Verbonden weer zolang de brokerverbinding actief is. Een broker die wegvalt, wordt elke paar seconden opnieuw geprobeerd, zonder limiet — er is nooit een herstart van de server nodig.

📘 Opmerking: Nadat u een verbinding heeft aangemaakt of opgeslagen, verschijnt Wijzigingen toepassen met een teller in de zijbalk. De verbinding werkt al zonder dit; toepassen herlaadt de serverconfiguratie en wist de teller.

Een object koppelen (zie "MQTT koppelen" hieronder). Per object voert u een Topic in; de beheerinterface slaat dit op als <verbinding>:<topic> zodat twee brokers dezelfde topicnaam kunnen gebruiken. De richting van het object bepaalt wat er gebeurt:

De payload-codec — hoe de payload wordt omgezet in een waarde en omgekeerd — is de gegevenstypereeks van het object, samengesteld door de editor uit deze velden:

De tekenreeks heeft de vorm TYPE:param:param… — bijvoorbeeld BOOL:PATH=state:ON=ON:OFF=OFF of FLOAT:SCALE=0.3937:PUB={"brightness":{{value}}}. Een lege reeks betekent "gebruik de ruwe payload als het type van het object". De objecteditor heeft geen veld voor het gegevenstype: het type is het type dat wordt weergegeven op het veld waarop u klikt in de topic-browser (hieronder), en het aanklikken van een veld past het type van het object hierop aan. Kleurobjecten (RGB) accepteren inkomend {"r","g","b"}, {"red","green","blue"}, [r,g,b], #RRGGBB en 255,128,0, en publiceren {"r":…,"g":…,"b":…} tenzij een sjabloon anders aangeeft.

⚠️ Waarschuwing: Een retained commando wordt opnieuw uitgevoerd telkens wanneer het apparaat opnieuw verbinding maakt met de broker. Behoud statussen, geen commando's — de editor waarschuwt wanneer u retain inschakelt voor een uitgaand object.

Topic-browser. MQTT is het enige protocol waarvan de adressen rechtstreeks van het netwerk kunnen worden uitgelezen. Klik in de objecteditor onder MQTT-topicconfiguratie op Broker scannen: de server luistert vier seconden naar de volledige broker en meldt hoeveel topics er zijn gedetecteerd (retained topics komen direct binnen, dus een korte scan toont al snel de meeste relevante topics; activeer voor een apparaat dat niet retaint een nieuwe meting en scan opnieuw). De lijst is beperkt tot 500 topics. De objecteditor kan niet een deel van de broker scannen: open Topic en typ in Topics zoeken… om de resultaten te filteren, of typ zelf het volledige topic. Elke rij toont het topic en de laatste payload, met een retained-label. Kies een topic en:

• voor een JSON-payload wordt elk veld vermeld onder Kies de waarde die dit object moet volgen — één klik stelt het JSON-pad, het objecttype en, voor booleans, de AAN/UIT-tekens in volgens de notatie van het apparaat;
• voor een eenvoudige payload stelt Gebruik de ruwe payload als het type in.

Kies het topic voordat u op een veld klikt: het selecteren van een ander topic reset het payload-formaat, het JSON-pad en de tekens. De klik vult Schaal en Offset niet in.

U kunt nog steeds een topic invoeren dat de scan niet heeft opgevangen — een commandotopic is mogelijk nog nooit gepubliceerd en een inkomend object vereist mogelijk een wildcard. Typ het in Topic en klik op Gebruik "…" in de lijst.

Gedrag dat handig is om te weten

• Directe status na een herstart. Retained berichten worden door de broker bij elke (her)verbinding opnieuw verzonden, zodat widgets waarden weergeven zonder te hoeven wachten op de volgende publicatie van het apparaat.
• Geen verzonnen feedback. Een commando wordt pas bevestigd wanneer het apparaat zijn statustopic publiceert (of de broker dit opnieuw verzendt) — exact zoals bij KNX-statusobjecten. Als het apparaat offline is, doet de widget niet alsof het werkt.
• Commando's tijdens een onderbreking. Commando's met QoS 1 of 2 worden in de wachtrij geplaatst zolang de broker onbereikbaar is en afgeleverd bij het herstellen van de verbinding; QoS 0-commando's naar een onbereikbare broker mislukken en worden gelogd.
• Beveiliging. Payloads groter dan 64 KB worden genegeerd met een waarschuwing; er wordt één abonnement per uniek topicfilter geopend, ongeacht hoeveel objecten dit delen.

Praktijkvoorbeeld — een dimbare Zigbee2MQTT-lamp

Zigbee2MQTT publiceert de status van de lamp als JSON op zigbee2mqtt/lamp ({"state":"ON","brightness":178}) en accepteert commando's op zigbee2mqtt/lamp/set. De helderheid loopt van 0–254.

1. Maak een MQTT-verbinding aan voor de broker (zie "Verbindingen"): brokeradres 192.168.1.10, poort 1883, de inloggegevens van de Zigbee2MQTT-broker indien van toepassing. Klik op Testen — dit moet succes melden.
2. Voeg onder Apparaten een Dimmer-widget toe met de naam "Kantoorlamp". Selecteer onder Protocol uw brokerverbinding, aangeduid met de naam die u eraan heeft gegeven. Het apparaat verschijnt met vier objecten: Schakelen AAN/UIT, Schakelfeedback, Dimwaarde en Dimfeedback.
3. Op Schakelen AAN/UIT (het aan/uit-commando): typ zigbee2mqtt/lamp/set in Topic en klik op Gebruik "…" in de lijst. Stel AAN-teken in op ON, UIT-teken op OFF en Payload-sjabloon op {"state":"{{value}}"}. Typ de tekens daadwerkelijk in: de grijze ON en OFF zijn slechts voorbeelden, en zonder tekens publiceert de schakelaar true of false.
4. Op Schakelfeedback (de aan/uit-status): klik op Broker scannen, kies zigbee2mqtt/lamp en klik vervolgens op het veld state — de editor stelt het JSON-pad in op state en de tekens op ON/OFF.
5. Op Dimwaarde (het helderheidscommando): topic zigbee2mqtt/lamp/set, Payload-sjabloon {"brightness":{{value}}}, Schaal 0.3937, Offset 0.
6. Op Dimfeedback (de helderheidsstatus): topic zigbee2mqtt/lamp, klik op het veld brightness en stel dezelfde Schaal in op 0.3937. Dit is ongeveer 100/254: inkomende waarden worden hiermee vermenigvuldigd (Zigbee 0–254 wordt 0–100 %), uitgaande waarden worden hierdoor gedeeld (0–100 % wordt 0–254).
7. Klik op Object opslaan bij elk object, klik vervolgens op Wijzigingen toepassen in de zijbalk en bevestig.
8. Stel de helderheid in op 50 % in de app. De lamp ontvangt ongeveer 127 en de feedback retourneert ongeveer 50 %. De schuifregelaar bevestigt dit aan de hand van het statustopic, en het bedienen van de lamp met de fysieke afstandsbediening werkt de app eveneens bij.

📘 Opmerking: De verzonden waarde wordt niet afgerond: 50 % wordt gepubliceerd als 127.000254. De objecteditor heeft geen veld voor het gegevenstype, dus u kunt een commando-object geen geheel getal laten verzenden. Controleer of uw lamp een decimale helderheidswaarde accepteert.

MQTT koppelen

MQTT-objecten worden geconfigureerd in het dialoogvenster voor objectinstellingen (open het object met Bewerken, zie "Objectinstellingen, logboekregistratie & meldingen"). Het protocolspecifieke gedeelte bevindt zich in drie kaarten:

MQTT-topicconfiguratie

Publiceren (uitgaande objecten)

Abonneren (inkomende objecten)

De velden worden opgeslagen als de gegevenstypereeks van het object (bijv. BOOL:PATH=state:ON=ON:OFF=OFF) — de structuur, de topic-browser en een uitgewerkt praktijkvoorbeeld vindt u in het MQTT-hoofdstuk hierboven.