De ingebouwde MQTT-broker
HyperVisu kan zelf een MQTT-broker draaien op de server. Apparaten verbinden dan direct met HyperVisu in plaats van met een aparte broker die u moet installeren, beveiligen en up-to-date houden. U koppelt hun topics exact zoals op elke andere broker (zie “MQTT-integratie”). Dezelfde broker kan ook de waarden van de installatie zelf naar buiten sturen, zodat een dashboard, een energiesysteem of een andere controller kan uitlezen wat het gebouw doet.
Gebruik dit wanneer u MQTT-apparaten hebt en nog geen broker. Draait u al een broker — die binnen een Zigbee2MQTT-installatie, een Mosquitto op een server, een EMQX — behoud deze dan: HyperVisu is een volwaardige client en de ingebouwde broker kan uitgeschakeld blijven.
Wat u nodig heeft: het MQTT-protocol ingeschakeld (zie “Services & protocollen”) zodat apparaten kunnen worden gekoppeld, en één account per apparaat dat verbinding maakt.
Inschakelen. De broker is een optionele service; er is een herstart nodig om deze te laten verschijnen, waarna de configuratie volgt:
- Ga naar Services en schakel MQTT Broker in bij de optionele services.
- Klik op Server herstarten en wacht tot de pagina opnieuw verbindt.
- Terug op Services, klik op Configureren op de rij van de MQTT Broker. De pagina MQTT Broker opent.
ℹ️ Opmerking: De schakelaar op de pagina Services start en stopt de broker; alles op de pagina MQTT Broker bepaalt het gedrag. Een wijziging op de pagina Services vereist een herstart van de server; een wijziging op de pagina MQTT Broker herstart enkel de broker zelf.
Wijzigingen opslaan. Aanpassingen worden verzameld tot u ze toepast: onderaan de pagina verschijnt een balk met Toepassen en Verwerpen. Toepassen schrijft de instellingen weg en herstart de broker — verbonden apparaten verbinden binnen enkele seconden automatisch opnieuw. Opnieuw toepassen, bovenaan het paneel Status, herschrijft en herstart zelfs wanneer er niets gewijzigd is; gebruik dit als de broker handmatig werd gestopt of als de pagina meldt dat de bestanden op de schijf afwijken van de opgeslagen instellingen.
Status — is deze actief en hoe bereiken apparaten hem
Het paneel Status is waar u als eerste naar kijkt.
- Eén kaart per listener — MQTT en WebSockets — die telkens het adres toont en aangeeft of deze Luistert, Geen antwoord geeft of Uit staat.
- Adres om in te voeren in een apparaat — het adres om in te vullen in de configuratie van een Shelly, Tasmota of Zigbee2MQTT, met een knop Kopiëren. Dit is het eigen adres van de server en de poort van de standaard listener.
- HyperVisu's eigen verbinding — het account en de verbinding die HyperVisu zelf gebruikt om de broker te bereiken. Dit wordt automatisch aangemaakt bij het eerste gebruik van de broker; Herstellen maakt het opnieuw aan als de verbinding bewerkt of verwijderd werd.
Als de broker nooit gestart is, meldt het paneel dat de service niet actief is en verwijst het terug naar de pagina Services.
Listeners — op welke poorten de broker antwoordt
Een listener is een poort waarop de broker verbindingen accepteert. Er zijn er twee beschikbaar, elk met een Poort en een Bind-adres:
| Listener | Standaard | Waarvoor het dient |
|---|---|---|
| MQTT | poort 1883, aan | De listener die apparaten doorgaans gebruiken. Authenticatie blijft gelden — deze listener is ongecodeerd, niet open. |
| WebSockets | poort 9001, uit | Voor MQTT-clients in een browser en voor dashboards die MQTT via websockets gebruiken. |
Bind-adres bepaalt wie de listener mag bereiken: 0.0.0.0 accepteert verbindingen vanaf het netwerk, 127.0.0.1 beperkt dit tot de server zelf.
Er moet minstens één listener ingeschakeld blijven — zonder listener kan niets verbinden en weigert de pagina op te slaan. Twee listeners kunnen niet dezelfde poort delen, en poorten die al op de server in gebruik zijn (de webinterface, de historiedatabase, dashboards, Node-RED, camerastreaming, Home Assistant, de HyperVisu API) worden met naam geweigerd.
⚠️ Waarschuwing: Geen van beide listeners versleutelt gegevens; houd de broker dus op het lokale netwerk. Koppel deze aan
127.0.0.1als alleen de server zelf er gebruik van maakt en stuur de poort nooit door vanaf het internet.
Accounts en toegang — wie mag verbinden
⚠️ Waarschuwing: Een broker zonder restricties is een toegangspoort tot de installatie. Geef elk apparaat een eigen account en laat anonieme toegang uitgeschakeld.
Accounts. Elk apparaat dat verbinding maakt heeft een gebruikersnaam en wachtwoord nodig. Klik op Account toevoegen, voer een Gebruikersnaam in (letters, cijfers en . _ @ -) en een Wachtwoord, en pas dit toe. Het wachtwoord wordt direct bij het opslaan gehasht en kan nooit meer worden uitgelezen — enkel vervangen via de knop Wachtwoord op de accountrij. HyperVisu heeft een eigen account, als zodanig gemarkeerd; dit wordt automatisch beheerd en kan niet worden verwijderd.
De pagina weigert een configuratie op te slaan waarin anonieme toegang uit staat en er geen accounts bestaan — niets zou dan kunnen verbinden, zelfs HyperVisu niet.
Anonieme verbindingen. Anonieme verbindingen toestaan laat elke client verbinden zonder gebruikersnaam. Dit staat standaard uit. Schakelt u dit in terwijl een listener bereikbaar is vanaf het netwerk, dan toont de pagina een waarschuwing — Deze broker zou openstaan voor het hele netwerk — en weigert op te slaan totdat u Ik begrijp het en wil dit toestaan aanvinkt. Iedereen op het netwerk zou anders de gegevens van de installatie kunnen lezen en bedienen.
Topicrestricties. Zonder regels mag elk geauthenticeerd account publiceren en abonneren op alles. Schakel Topics per account beperken in en klik op Regel toevoegen. Elke regel bestaat uit een Account (vul de gebruikersnaam in; leeg laten geldt voor anonieme clients), een Bevoegdheid (read, write, readwrite of deny) en een Topicfilter, waarbij + één niveau matcht en # de rest.
Een typische configuratie: de Zigbee-gateway krijgt readwrite op zigbee2mqtt/#, een dashboard krijgt read op hypervisu/#, en nergens anders is iets toegestaan.
ℹ️ Opmerking: De regels vormen de volledige lijst — een account zonder overeenkomende regel voor een topic wordt daarop geweigerd. Het eigen account van HyperVisu is de uitzondering: dit behoudt altijd volledige toegang, zodat het inschakelen van restricties de server nooit kan afsluiten van de topics waaraan zijn apparaten zijn gekoppeld. Een regel die dat account noemt, wordt genegeerd.
Opslag en limieten
Deze instellingen beschermen de server tegen apparaten met afwijkend gedrag en bepalen wat er bewaard blijft na een herstart.
| Instelling | Standaard | Wat het doet |
|---|---|---|
| Retained berichten bewaren na herstart | aan | Schrijft de toestand van de broker naar de schijf, zodat retained topics na een herstart behouden blijven. Zonder dit gaat elke retained waarde verloren bij een stop en wachten widgets op het apparaat. |
| Opslaginterval (s) | 1800 | Hoe vaak die toestand wordt weggeschreven. Een langere interval betekent minder schrijfacties naar de geheugenkaart van de server. |
| Maximaal aantal verbindingen | 200 | Hoeveel clients tegelijk verbonden mogen zijn. -1 voor onbeperkt. |
| Maximale pakketgrootte (bytes) | 0 | Het grootste bericht dat de broker accepteert. 0 betekent onbeperkt. |
| Retained berichten toestaan | aan | Of apparaten de broker mogen vragen hun laatste waarde te onthouden voor nieuwe abonnees. Uitschakelen zorgt dat elke widget moet wachten op een nieuw bericht na herverbinden. |
💡 Tip: Laat retained berichten ingeschakeld. Dit zorgt ervoor dat de app direct actuele waarden toont zodra de server herstart, in plaats van lege widgets.
Widgetstatussen publiceren naar MQTT
HyperVisu kan de waarden van zijn eigen apparaten publiceren op de broker, zodat andere systemen de installatie kunnen uitlezen zonder HyperVisu zelf te belasten: een Grafana-dashboard, een energiemanager, een externe controller of een ander gebouwsysteem.
Dit staat standaard uit, en zolang het uit staat wordt er niets gepubliceerd. Schakel Widgetstatussen publiceren naar MQTT in om de instellingen te tonen:
| Instelling | Standaard | Wat het doet |
|---|---|---|
| Topic-voorvoegsel | hypervisu | Het eerste segment van elk topic. Alleen reguliere topicsegmenten — geen + of #. |
| Serienummer van het apparaat opnemen in topic | aan | Voegt het serienummer van de server toe na het voorvoegsel, zodat twee installaties dezelfde broker kunnen delen zonder conflicten. |
| Topicstijl | Identifiers | Identifiers (stabiel) gebruikt de interne apparaatnummers; Namen (leesbaar) gebruikt kamer- en apparaatnamen. Namen lezen makkelijker, maar het hernoemen van een kamer verplaatst elk onderliggend topic en verbreekt abonnementen. |
| Payload | Enkel waarde | Enkel waarde publiceert alleen de losse waarde; JSON met context publiceert de waarde samen met de naam en ruimte van het apparaat, de eenheid, identiteit en een tijdstempel — zodat een abonnee weet wat widget/42/1 is. |
| Minimuminterval (ms) | 1000 | Snelheidslimiet per object. De meest recente waarde komt altijd door; 0 publiceert elke individuele wijziging. |
| Laatste waarde bewaren (retain) | aan | Een client die later verbindt, ziet direct de actuele toestand in plaats van te moeten wachten op de volgende wijziging. |
| Beschikbaarheidstopic publiceren | aan | Publiceert online / offline, retained, op <prefix>/<serial>/status, zodat abonnees weten of gegevens actueel zijn of dateren van voor een onderbreking. Uitschakelen trekt dit in. |
| Alleen deze widgets | uit | Uit publiceert elk apparaat. Aan laat u exact kiezen welke. |
| Opdrachten accepteren via MQTT | uit | Laat een abonnee waarden terugschrijven. Zie de onderstaande waarschuwing. |
De pagina toont Een topic ziet er als volgt uit met een live voorbeeld terwijl u de instellingen wijzigt. Met de standaardinstellingen komt de waarde van een apparaat binnen op:
hypervisu/<serial>/widget/42/1/state
en met Namen (leesbaar):
hypervisu/<serial>/living-room/ceiling-lamp/1/state
Het laatste segment voor state is het objectnummer van het apparaat — één topic per communicatieobject, niet één per apparaat.
Met JSON met context beschrijft het bericht zichzelf:
{"value":21.5,"unit":"°C","name":"Hall thermostat","room":"Bathroom","widget":46,"object":2,"type":"FLOAT","ts":"2026-09-09T07:51:22.436Z"}
De naam en de ruimte worden uitgelezen op het moment van publiceren, dus het hernoemen van een apparaat past het volgende bericht aan zonder topics te verplaatsen. Dat is het verschil met Namen (leesbaar): leesbare topics verplaatsen bij hernoemen, een leesbare payload niet.
Opdrachten accepteren. Met Opdrachten accepteren via MQTT ingeschakeld, wijzigt het publiceren van een waarde naar het bijhorende …/set-topic het apparaat, precies alsof dit via de app gebeurde.
⚠️ Waarschuwing: Hiermee kan iedereen die naar de broker kan publiceren het gebouw bedienen. Schakel dit alleen in met anonieme toegang uitgeschakeld en actieve topicrestricties — de pagina weigert de combinatie van opdrachten en anonieme toegang pertinent.
Opdrachten worden geweigerd (en geteld als geweigerd) wanneer het topic toebehoort aan een alleen-lezen object of als de payload niet gelezen kan worden als het type van het object. Het paneel toont hoeveel berichten gepubliceerd en genegeerd zijn, samen met een badge met het aantal momenteel gepubliceerde objecten.
ℹ️ Opmerking: Publiceren vereist dat het MQTT-protocol is ingeschakeld en er verbinding is met een broker. Zonder actieve verbinding meldt het paneel dit in plaats van te doen alsof er gepubliceerd wordt.
Topics op de broker doorbladeren
Topics op de broker, onderaan de pagina, toont wat er op dit moment werkelijk gebeurt op de broker — de snelste manier om te controleren of een zojuist geconfigureerd apparaat daadwerkelijk communiceert.
- Vul optioneel Beperken tot een substructuur in om de scan te verfijnen (
zigbee2mqttscant enkelzigbee2mqtt/#). - Kies de duur bij Luisteren gedurende — 3, 4, 10 of 30 seconden.
- Klik op Scannen.
Het resultaat is een structuurboom volgens de /-niveaus van de topics, waardoor een broker met honderden topics overzichtelijk blijft. Klik op een tak om deze te openen — de rij toont hoeveel onderliggende topics er zijn — en klik op een topic om de laatste payload te bekijken. Bij een JSON-payload worden de velden eronder weergegeven met het herkende type; bij een eenvoudige payload het type waarin deze geïnterpreteerd is. De kopieerknop op de geopende rij kopieert het volledige topic. Knoppen voor Alles uitvouwen en Alles inklappen staan boven de boomstructuur; een kleine scan opent automatisch uitgevouwen.
Een niveau met slechts één onderliggend element wordt samengevoegd met het hoofdelement (118/1/state op één rij in plaats van drie), zodat een diep voorvoegsel geen extra klikken kost. Retained topics staan op elk niveau bovenaan.
HyperVisu's eigen gepubliceerde topics worden waar mogelijk benoemd: een topic zoals hypervisu/<serial>/widget/42/1/state wordt getoond met het bijbehorende apparaat ernaast, zodat u het nummer niet hoeft op te zoeken.
Retained topics worden direct opnieuw verzonden door de broker zodra de scan zich abonneert, waardoor zelfs een korte scan de volledige retained structuur toont. Levert een scan niets op, dan is er nog geen apparaat verbonden of publiceren de apparaten enkel bij wijzigingen — kies dan een langere tijdsduur.
ℹ️ Opmerking: De scan leest de actuele status van de broker uit; niet-opgeslagen wijzigingen elders op de pagina worden hierin niet meegenomen. Het paneel geeft dit aan zolang er niet-opgeslagen wijzigingen zijn.
De scan is alleen-lezen: deze toont wat er aanwezig is en publiceert nooit. Om een van deze topics aan een apparaat te koppelen, opent u het groepsobject van het apparaat en selecteert u het topic in de objecteditor (zie “MQTT-integratie”) — dezelfde scan is daar beschikbaar en vult automatisch het type, het JSON-pad en de ON/OFF-statussen voor u in.
Praktijkvoorbeeld — een Shelly-tussenstekker op de ingebouwde broker
Een Shelly Plus-stekker moet worden aangestuurd door HyperVisu, zonder dat er al een broker aanwezig is op het netwerk.
- Services → schakel MQTT Broker in → Server herstarten. Zorg dat het MQTT-protocol eveneens actief is.
- Services → Configureren op de rij van de MQTT Broker. Klik bij Accounts en toegang op Account toevoegen: gebruikersnaam
shelly, een zelfgekozen wachtwoord. Klik op Toepassen. - Noteer het Adres om in te voeren in een apparaat uit het paneel Status — bijvoorbeeld
192.168.1.60:1883. - Schakel in de webinterface van de Shelly MQTT in, vul dat adres, de gebruikersnaam
shellyen het wachtwoord in en sla op. De tussenstekker herstart en verbindt. - Ga naar Verbindingen. Een melding toont De lokale broker gebruiken; klik hierop en HyperVisu maakt automatisch zijn eigen verbinding met de broker aan. Als u dit al eerder gedaan heeft, staat de verbinding er al — de topicbrowser vereist deze verbinding, dus doe dit vóór het scannen.
- Ga terug naar de pagina MQTT Broker, open Topics op de broker en klik op Scannen. De topics van de tussenstekker verschijnen —
shellyplus1pm-a8032ab1/status/switch:0en andere — met hun laatste payloads. - Voeg onder Apparaten een Lichtschakelaar-widget "Keukenstekker" toe met protocol MQTT op die verbinding, en koppel de objecten aan de topics van de tussenstekker via Broker scannen in de objecteditor.
- Schakel de tussenstekker in de app. De opdracht wordt verstuurd via de ingebouwde broker en het statustopic van de tussenstekker bevestigt de actie.