Der integrierte MQTT-Broker
HyperVisu kann einen eigenen MQTT-Broker direkt auf dem Server betreiben. Geräte verbinden sich dadurch direkt mit HyperVisu, anstatt mit einem separaten Broker-Rechner, der eingerichtet, abgesichert und gewartet werden müsste. Die Zuordnung der Topics erfolgt wie gewohnt (siehe „MQTT-Integration“). Derselbe Broker kann zudem Zustände aus dem Gebäude nach außen weiterleiten, sodass ein Dashboard, ein Energiesystem oder ein externer Controller die Daten der Installation einsehen kann.
Sinnvoll ist dies, wenn MQTT-Geräte vorhanden sind, aber noch kein Broker läuft. Existiert bereits ein Broker – beispielsweise innerhalb einer Zigbee2MQTT-Installation, ein Mosquitto auf einem Server oder ein EMQX –, sollte dieser beibehalten werden: HyperVisu arbeitet zuverlässig als Client, und der integrierte Broker kann deaktiviert bleiben.
Voraussetzungen: Das MQTT-Protokoll muss aktiviert sein (siehe „Dienste & Protokolle“), damit Geräte zugeordnet werden können, sowie ein separates Konto für jedes angebundene Gerät.
Aktivierung. Der Broker ist ein optionaler Dienst. Nach der Aktivierung ist ein Neustart erforderlich:
- Unter Dienste in der Liste der optionalen Dienste den MQTT-Broker einschalten.
- Auf Server neustarten klicken und warten, bis die Seite wieder erreichbar ist.
- Zurück unter Dienste in der Zeile des MQTT-Brokers auf Konfigurieren klicken. Die Seite MQTT-Broker öffnet sich.
ℹ️ Hinweis: Der Schalter auf der Dienste-Seite startet und stoppt den Broker; alle Einstellungen auf der MQTT-Broker-Seite bestimmen dessen Verhalten. Eine Änderung auf der Dienste-Seite erfordert einen Server-Neustart; Änderungen auf der MQTT-Broker-Seite starten lediglich den Broker selbst neu.
Änderungen speichern. Änderungen werden gesammelt, bis sie übernommen werden. Am unteren Bildschirmrand erscheint eine Leiste mit Übernehmen und Verwerfen. Übernehmen speichert die Konfiguration und startet den Broker neu – verbundene Geräte stellen die Verbindung innerhalb weniger Sekunden automatisch wieder her. Erneut anwenden oben im Status-Bereich schreibt die Konfiguration neu und führt einen Neustart durch, auch wenn keine Änderungen vorliegen; dies ist hilfreich, wenn der Broker manuell gestoppt wurde oder gemeldet wird, dass die Dateien auf dem Datenträger von den gespeicherten Einstellungen abweichen.
Status – Betriebszustand und Erreichbarkeit für Geräte
Der Bereich Status bietet den ersten Überblick.
- Eine Karte pro Listener – MQTT und WebSockets –, die jeweils die Adresse sowie den Zustand anzeigt: Aktiv (Listening), Keine Antwort oder Aus.
- Im Gerät einzutragende Adresse – die Adresse zur Konfiguration in Shelly, Tasmota oder Zigbee2MQTT, inklusive einer Schaltfläche zum Kopieren. Sie besteht aus der Serveradresse und dem Port des unverschlüsselten Listeners.
- HyperVisus eigene Verbindung – das Konto und die Verbindung, die HyperVisu selbst für den Zugriff auf den Broker nutzt. Diese wird bei der ersten Nutzung des Brokers automatisch angelegt; Reparieren stellt sie wieder her, falls sie bearbeitet oder gelöscht wurde.
War der Broker noch nie aktiv, weist der Bereich darauf hin, dass der Dienst nicht läuft, und verlinkt auf die Dienste-Seite.
Listener – Port-Konfiguration des Brokers
Ein Listener ist ein Port, über den der Broker Verbindungen annimmt. Es stehen zwei Varianten zur Verfügung, jeweils mit Port und Bind-Adresse:
| Listener | Standard | Verwendungszweck |
|---|---|---|
| MQTT | Port 1883, an | Standard-Port für Endgeräte. Die Authentifizierung bleibt aktiv – dieser Listener ist unverschlüsselt, nicht offen. |
| WebSockets | Port 9001, aus | Für browserbasierte MQTT-Clients und Dashboards, die MQTT über WebSockets nutzen. |
Die Bind-Adresse bestimmt den Zugriff: 0.0.0.0 erlaubt Verbindungen aus dem Netzwerk, 127.0.0.1 beschränkt den Zugriff auf den Server selbst.
Mindestens ein Listener muss aktiv bleiben – ohne aktiven Listener sind keine Verbindungen möglich, und das Speichern wird verweigert. Zwei Listener können nicht denselben Port belegen. Bereits anderweitig auf dem Server belegte Ports (Weboberfläche, Verlaufsdatenbank, Dashboards, Node-RED, Kamera-Streaming, Home Assistant, HyperVisu-API) werden mit entsprechendem Hinweis abgewiesen.
⚠️ Warnung: Keiner der Listener verschlüsselt die Übertragung. Der Broker gehört ausschließlich ins lokale Netzwerk. Wählen Sie
127.0.0.1, wenn nur der Server selbst Zugriff benötigt, und leiten Sie diese Ports niemals ins Internet weiter.
Konten und Zugriffsberechtigungen
⚠️ Warnung: Ein ungesicherter Broker stellt ein Sicherheitsrisiko für die gesamte Installation dar. Richten Sie für jedes Gerät ein eigenes Konto ein und lassen Sie anonyme Zugriffe deaktiviert.
Konten. Jedes angebundene Gerät benötigt Benutzername und Passwort. Klicken Sie auf Konto hinzufügen, vergeben Sie einen Benutzernamen (Buchstaben, Ziffern sowie . _ @ -) und ein Passwort, danach speichern. Das Passwort wird direkt beim Speichern gehasht und kann nicht im Klartext eingesehen werden – eine Änderung ist jederzeit über die Schaltfläche Passwort in der Kontozeile möglich. HyperVisu verfügt über ein eigenes, entsprechend gekennzeichnetes Systemkonto, das automatisch verwaltet wird und nicht gelöscht werden kann.
Eine Konfiguration ohne aktiven anonymen Zugriff und ohne angelegte Konten lässt sich nicht speichern, da sonst keine Verbindung – auch nicht durch HyperVisu – möglich wäre.
Anonyme Verbindungen. Die Option Anonyme Verbindungen erlauben gestattet Verbindungen ohne Benutzerkonto. Diese Option ist standardmäßig deaktiviert. Wird sie aktiviert, während ein Listener über das Netzwerk erreichbar ist, erscheint ein Warnhinweis (Dieser Broker wäre für das gesamte Netzwerk offen). Das Speichern erfordert dann die Bestätigung über Ich habe dies verstanden und möchte es erlauben. Andernfalls könnte jeder Netzwerkteilnehmer Daten einsehen und Befehle senden.
Topic-Beschränkungen. Ohne explizite Regeln darf jedes authentifizierte Konto alle Topics lesen und beschreiben. Aktivieren Sie Topics pro Konto beschränken und klicken Sie auf Regel hinzufügen. Jede Regel besteht aus einem Konto (Benutzername eintragen; bleibt das Feld leer, gilt die Regel für anonyme Clients), einer Berechtigung (Lesen, Schreiben, Lesen/Schreiben oder Verweigern) und einem Topic-Filter, wobei + eine Ebene und # alle folgenden Ebenen abdeckt.
Typisches Beispiel: Das Zigbee-Gateway erhält Lesen/Schreiben auf zigbee2mqtt/#, ein Dashboard Lesen auf hypervisu/#, alle anderen Pfade bleiben gesperrt.
ℹ️ Hinweis: Es gilt das Whitelist-Prinzip – existiert für ein Topic keine passende Regel, wird der Zugriff verweigert. HyperVisus eigenes Konto ist davon ausgenommen und behält stets Vollzugriff. Eine Regel für dieses Systemkonto wird ignoriert.
Speicher und Grenzwerte
Diese Parameter schützen den Server vor fehlerhaften Geräten und definieren das Verhalten bei einem Neustart.
| Einstellung | Standard | Funktion |
|---|---|---|
| Retained-Nachrichten über Neustarts hinweg speichern | an | Schreibt den Zustand des Brokers auf den Datenträger, sodass Retained-Topics nach einem Neustart erhalten bleiben. Ohne diese Option gehen Werte verloren und Widgets bleiben leer bis zum nächsten Sendezyklus. |
| Speicherintervall (s) | 1800 | Intervall zur Zustandssicherung. Höhere Werte reduzieren die Schreibzugriffe auf die Speicherkarte des Servers. |
| Maximale Verbindungen | 200 | Maximale Anzahl gleichzeitiger Clients. -1 steht für unbegrenzt. |
| Maximale Paketgröße (Bytes) | 0 | Maximale Nachrichtengröße, die der Broker akzeptiert. 0 bedeutet unbegrenzt. |
| Retained-Nachrichten erlauben | an | Bestimmt, ob Geräte Werte als Retained markieren dürfen. Bei Deaktivierung müssen Abonnenten nach einer Neuverbindung stets auf ein neues Telegramm warten. |
💡 Tipp: Retained-Nachrichten sollten aktiviert bleiben. Nur so zeigt die App nach einem Server-Neustart sofort die aktuellen Werte statt leerer Widgets an.
Widget-Zustände über MQTT bereitstellen
HyperVisu kann Zustände eigener Geräte auf dem Broker publizieren, damit externe Systeme (Grafana-Dashboard, Energiemanagement, Drittanbieter-Steuerungen) diese mitlesen können, ohne direkt mit HyperVisu zu kommunizieren.
Diese Funktion ist standardmäßig deaktiviert. Nach dem Aktivieren von Widget-Zustände über MQTT bereitstellen stehen folgende Optionen bereit:
| Einstellung | Standard | Funktion |
|---|---|---|
| Topic-Präfix | hypervisu | Erstes Segment jedes Topics. Nur einfache Segmente ohne + oder #. |
| Seriennummer des Geräts im Topic einschließen | an | Ergänzt die Seriennummer des Servers hinter dem Präfix, damit mehrere Server denselben Broker kollisionsfrei nutzen können. |
| Topic-Struktur | Bezeichner | Bezeichner (stabil) nutzt interne Gerätenummern; Namen (lesbar) verwendet Raum- und Gerätenamen. Lesbare Namen sind verständlicher, aber eine Umbenennung ändert den gesamten Topic-Pfad und unterbricht bestehende Abonnements. |
| Nutzdaten (Payload) | Nur Wert | Nur Wert sendet ausschließlich den Zustand; JSON mit Kontext überträgt zusätzlich Name, Raum, Einheit, Kennung und Zeitstempel – Abonnenten können die Nachricht interpretieren, ohne die Zuordnung von widget/42/1 zu kennen. |
| Mindestintervall (ms) | 1000 | Ratenbegrenzung pro Objekt. Der neueste Wert wird immer übertragen; 0 sendet jede einzelne Änderung sofort. |
| Letzten Wert beibehalten (Retain) | an | Neu verbundene Clients erhalten sofort den aktuellen Wert, ohne auf die nächste Wertänderung zu warten. |
| Verfügbarkeits-Topic senden | an | Sendet online / offline als Retained-Nachricht auf <Präfix>/<Seriennummer>/status. Zeigt Abonnenten, ob Daten live sind. Beim Deaktivieren der Funktion wird das Topic gelöscht. |
| Nur ausgewählte Widgets | aus | Bei „aus“ werden alle Geräte publiziert. Bei „an“ lässt sich die Auswahl manuell eingrenzen. |
| Befehle über MQTT annehmen | aus | Erlaubt externen Systemen das Setzen von Werten. Siehe nachfolgenden Warnhinweis. |
Unter So sieht ein Topic aus wird eine dynamische Vorschau der Pfadstruktur angezeigt. In der Standardkonfiguration lautet das Topic eines Geräts:
hypervisu/<Seriennummer>/widget/42/1/state
und bei Auswahl von Namen (lesbar):
hypervisu/<Seriennummer>/wohnzimmer/deckenlampe/1/state
Das Segment vor state bezeichnet die Objektnummer – es wird ein Topic pro Kommunikationsobjekt erzeugt, nicht nur eines pro Gerät.
Bei Auswahl von JSON mit Kontext enthält die Nachricht alle relevanten Metadaten:
{"value":21.5,"unit":"°C","name":"Flurthermostat","room":"Badezimmer","widget":46,"object":2,"type":"FLOAT","ts":"2026-09-09T07:51:22.436Z"}
Name und Raum werden zum Sendezeitpunkt ermittelt. Eine Umbenennung des Geräts aktualisiert die nächsten Nutzdaten, ohne den Topic-Pfad zu ändern. Dies ist der wesentliche Unterschied zu Namen (lesbar).
Befehlsempfang. Ist Befehle über MQTT annehmen aktiv, steuert das Senden eines Wertes auf das entsprechende …/set-Topic das Gerät direkt an – identisch zu einer Bedienung über die App.
⚠️ Warnung: Jeder Client mit Schreibrechten auf dem Broker kann dadurch Funktionen im Gebäude ausführen. Aktivieren Sie diese Option nur bei deaktiviertem anonymem Zugriff und mit hinterlegten Topic-Regeln. Die Kombination aus Befehlsempfang und anonymem Zugriff wird von der Oberfläche blockiert.
Befehle werden abgewiesen (und als verworfen gezählt), wenn das Topic zu einem schreibgeschützten Objekt gehört oder der Datentyp der Nutzdaten nicht zum Objekt passt. Der Bereich zeigt die Anzahl gesendeter und verworfener Telegramme sowie die Anzahl aktuell veröffentlichter Objekte an.
ℹ️ Hinweis: Die Bereitstellung erfordert ein aktives MQTT-Protokoll sowie eine bestehende Verbindung zu einem Broker. Fehlt die Verbindung, weist die Oberfläche explizit darauf hin.
Topics auf dem Broker analysieren
Der Bereich Topics auf dem Broker unten auf der Seite zeigt die aktuelle Kommunikation auf dem Broker in Echtzeit – ideal zur Funktionsprüfung frisch konfigurierter Geräte.
- Optional Auf Teilbaum begrenzen ausfüllen (
zigbee2mqttscannt nurzigbee2mqtt/#). - Abhördauer wählen – 3, 4, 10 oder 30 Sekunden.
- Auf Scannen klicken.
Das Ergebnis wird als Baumstruktur entlang der /-Hierarchien dargestellt. Ein Klick auf einen Zweig klappt diesen auf (die Zeile nennt die Anzahl untergeordneter Topics), ein Klick auf ein Topic zeigt die letzten Nutzdaten. Bei JSON-Daten werden die enthaltenen Felder samt Datentyp aufgeführt, bei einfachen Werten der erkannte Typ. Über das Kopiersymbol lässt sich das vollständige Topic kopieren. Oberhalb des Baums stehen Alle aufklappen und Alle zuklappen zur Verfügung.
Hierarchiestufen mit nur einem Unterelement werden zusammengefasst (118/1/state in einer Zeile), was tiefe Pfade übersichtlich hält. Retained-Topics stehen auf jeder Ebene oben.
Von HyperVisu selbst publizierte Topics werden automatisch beschriftet: Neben hypervisu/<Seriennummer>/widget/42/1/state wird direkt der Name des zugehörigen Geräts angezeigt.
Da Retained-Topics beim Start des Scans sofort vom Broker übermittelt werden, liefert auch ein kurzer Scan den vollständigen Bestand an gespeicherten Werten. Werden keine Topics gefunden, ist entweder kein Gerät verbunden oder die Geräte senden ausschließlich bei Wertänderungen – wählen Sie in diesem Fall ein längeres Zeitfenster.
ℹ️ Hinweis: Der Scan analysiert den aktuellen Live-Zustand des Brokers. Nicht gespeicherte Änderungen auf der Konfigurationsseite sind im Scan noch nicht wirksam.
Der Scan arbeitet rein lesend. Um ein gefundenes Topic einem Gerät zuzuweisen, öffnen Sie das Objekt im Geräte-Editor (siehe „MQTT-Integration“) – dieselbe Scan-Funktion steht dort bereit und übernimmt Typ, JSON-Pfad sowie ON/OFF-Werte automatisch.
Praxisbeispiel – Shelly-Zwischenstecker am integrierten Broker
Ein Shelly Plus Zwischenstecker soll ohne externen Broker über HyperVisu gesteuert werden.
- Dienste → MQTT-Broker einschalten → Server neustarten. Sicherstellen, dass auch das MQTT-Protokoll aktiv ist.
- Dienste → in der Zeile MQTT-Broker auf Konfigurieren klicken. Unter Konten und Zugriff auf Konto hinzufügen klicken: Benutzername
shelly, gewünschtes Passwort vergeben. Auf Übernehmen klicken. - Die Im Gerät einzutragende Adresse aus dem Status-Bereich notieren (z. B.
192.168.1.60:1883). - In der Weboberfläche des Shelly MQTT aktivieren, die notierte Adresse, den Benutzernamen
shellysowie das Passwort eintragen und speichern. Der Zwischenstecker startet neu und verbindet sich. - Zu Verbindungen wechseln. Das Banner Lokalen Broker verwenden anklicken; HyperVisu legt die interne Verbindung zum Broker an. Falls dieser Schritt früher bereits erfolgt ist, existiert die Verbindung bereits (sie wird für den Topic-Browser benötigt).
- Zurück auf der MQTT-Broker-Seite den Bereich Topics auf dem Broker öffnen und Scannen anklicken. Die Topics des Zwischensteckers erscheinen (z. B.
shellyplus1pm-a8032ab1/status/switch:0) samt Nutzdaten. - Unter Geräte ein Widget Lichtschalter namens „Zwischenstecker Küche“ mit Protokoll MQTT auf dieser Verbindung anlegen. Die Gruppenobjekte über Broker scannen im Objekt-Editor mit den Shelly-Topics verknüpfen.
- Den Zwischenstecker in der App schalten. Der Befehl wird über den integrierten Broker gesendet und über das Status-Topic des Geräts quittiert.