MQTT-Integration
MQTT verbindet HyperVisu mit der Publish/Subscribe-Welt: Zigbee2MQTT, Tasmota, Shelly (MQTT-Modus), ESPHome, Energie-Gateways und jede benutzerdefinierte Firmware, die mit einem MQTT-Broker kommuniziert. HyperVisu ist ein MQTT-Client – es abonniert (Subscribe) die Topics, auf denen Geräte ihren Status veröffentlichen, und veröffentlicht (Publish) Befehle auf den Topics, auf die Geräte hören. Es gibt kein Polling: Ändert ein Gerät seinen Status, veröffentlicht es diesen, und das Widget wird sofort aktualisiert.
Ein Broker sitzt in der Mitte. Dies kann ein bereits vorhandener Broker sein (Mosquitto, EMQX, der Broker einer Zigbee2MQTT-Installation, …) oder der in HyperVisu integrierte Broker, den der Server selbst ausführen kann, sodass sich Geräte direkt mit ihm verbinden (siehe „Der integrierte MQTT-Broker“). Alles in diesem Artikel gilt für beide Varianten – der integrierte Broker ist ein gewöhnlicher Broker, der über eine Standardverbindung erreicht wird.
Was Sie benötigen: die Broker-Adresse und den Port, die Zugangsdaten (falls erforderlich) sowie die Topics und das Payload-Format des Geräts – aus der Gerätedokumentation oder direkt über den Topic-Browser (unten) aus dem Broker ausgelesen.
Verbindungen. Aktivieren Sie zuerst das MQTT-Protokoll auf der Seite Dienste (siehe „Dienste & Protokolle“); auf einem neuen Server ist es standardmäßig deaktiviert. MQTT unterstützt mehrere Verbindungen: eine Verbindung pro Broker (siehe „Verbindungen“). Wählen Sie unter Verbindung hinzufügen die Kachel MQTT: Der Dialog fragt nach einem Instanznamen, der Broker-Adresse, dem Port, der Client-ID und den Zugangsdaten und verfügt über eine Schaltfläche Testen. Das CA-Zertifikat und die Broker-Optionen (Keepalive, Standard-QoS, Verfügbarkeits-Topic, Clean Session) befinden sich nicht in diesem Dialog: Diese werden in der gespeicherten Verbindung konfiguriert, die sich im Editor öffnet, sobald Sie auf Verbindung erstellen klicken. Der Verbindungseditor umfasst:
| Feld | Beschreibung |
|---|---|
| Broker-Adresse | Host oder vollständige URL: mqtt://, mqtts://, ws://, wss:// (ein einfacher Host bedeutet mqtt://). Ein Pfad in der Adresse bleibt erhalten, z. B. ws://192.168.1.30/mqtt. |
| Port | Der Port des Listeners – üblicherweise 1883 für Standard-MQTT und 8883 für MQTT über TLS. Geben Sie ihn stets explizit an: Im Dialog Verbindung hinzufügen wird ein leeres Feld unabhängig vom Schema als 1883 gespeichert, und das Feld Port überschreibt einen in der Adresse angegebenen Port. |
| Benutzername / Passwort | Für einen anonymen Broker leer lassen. |
| Client-ID | Leer lassen, um automatisch eine ID aus der MAC-Adresse des Servers abzuleiten. |
| Selbstsignierte Zertifikate akzeptieren | Wird nur bei mqtts:// / wss:// angezeigt. Standardmäßig deaktiviert: Das Broker-Zertifikat muss von einer vertrauenswürdigen Zertifizierungsstelle signiert sein. Bei Aktivierung wird das Zertifikat nicht überprüft. |
| CA-Zertifikat | Wird nur bei TLS angezeigt: Das PEM-Zertifikat der Zertifizierungsstelle, die das Broker-Zertifikat signiert hat, falls es sich nicht um eine öffentliche CA handelt. |
| Keepalive | Zeitraum, den eine inaktive Verbindung vor dem Senden eines Pings offen bleiben darf (Standard: 60 s). |
| Standard-QoS | 0 · höchstens einmal, 1 · mindestens einmal oder 2 · genau einmal – wird von allen Objekten verwendet, die keine eigene QoS definieren. |
| Verfügbarkeits-Topic / HyperVisu-Verfügbarkeit melden | Topic, auf dem HyperVisu den eigenen Status online / offline veröffentlicht (Standard: hypervisu/status, Retained). Der Broker veröffentlicht stellvertretend offline, falls die Verbindung unterbrochen wird. |
| Clean Session | Aktiviert (Standard): Der Broker verwirft die Abonnements bei einem Verbindungsabbruch, und HyperVisu abonniert die Topics bei der Wiederverbindung erneut. Deaktivieren Sie dies nur bei Brokern, die Nachrichten während eines HyperVisu-Ausfalls zwischenspeichern sollen. |
Die Schaltfläche Testen führt einen echten Verbindungstest durch: Der Server verbindet sich mit dem Broker und wartet auf dessen Rückmeldung (innerhalb von 10 s). Ein erfolgreiches Ergebnis lautet Verbindung erfolgreich. Im Dialog Verbindung hinzufügen testet Testen die eingegebenen Werte vor dem Erstellen der Verbindung. Bei einer gespeicherten Verbindung prüft Testen den gespeicherten Zustand, nicht ungespeicherte Änderungen: Klicken Sie zuerst auf Verbindung speichern und dann auf Testen. Ein erfolgreicher Test bestätigt, dass Adresse, Port, Zugangsdaten und TLS-Einstellungen vom Broker akzeptiert werden; er besagt nicht, ob auf einem bestimmten Topic Daten übertragen werden.
Der Status der Verbindung zeigt Verbunden, solange die Verbindung zum Broker besteht. Bei einem Verbindungsausfall versucht der Server alle paar Sekunden unbegrenzt eine Wiederverbindung – ein Neustart des Servers ist nicht erforderlich.
📘 Hinweis: Nach dem Erstellen oder Speichern einer Verbindung erscheint Änderungen übernehmen mit einem Zähler in der Seitenleiste. Die Verbindung funktioniert bereits ohne diesen Schritt; das Übernehmen lädt die Serverkonfiguration neu und setzt den Zähler zurück.
Objekt verknüpfen (siehe „MQTT-Verknüpfung“ unten). Pro Objekt geben Sie ein Topic ein; die Administration speichert dieses als <Verbindung>:<Topic>, sodass zwei Broker denselben Topic-Namen nutzen können. Die Richtung des Objekts bestimmt das Verhalten:
| Richtung | Verhalten |
|---|---|
| In | Abonniert das Topic (Status-Topic). Wildcards sind zulässig: + für eine Ebene, # für alle untergeordneten Ebenen. |
| Out | Veröffentlicht auf dem Topic (Befehls-Topic). Muss ein konkretes Topic sein – keine Wildcards erlaubt. |
| In/Out | Abonniert und veröffentlicht auf demselben Topic. Nur für Geräte geeignet, die einen Retained-Status auf einem einzigen Topic halten; empfohlen werden zwei Objekte (ein In, ein Out). |
Der Payload-Codec – wie die Payload in einen Wert und zurück gewandelt wird – entspricht der Datentypspezifikation des Objekts, die der Editor aus folgenden Feldern generiert:
| Feld | Gespeichert als | Bedeutung |
|---|---|---|
| Payload-Format | — / PATH= | Rohwert: Die gesamte Payload ist der Wert. JSON: Der Wert wird über den JSON-Pfad ausgelesen (state, sensor.temperature, values[0]). |
| EIN-Token / AUS-Token | ON= / OFF= | Für boolesche Objekte: Was das Gerät für true/false sendet und erwartet (z. B. ON / OFF). Ohne Token werden true/false, 1/0, on/off beim Empfang verarbeitet und true/false gesendet. |
| Skalierung / Offset | SCALE= / OFFSET= | Empfang: Wert = Rohwert × Skalierung + Offset; Senden verwendet die Umkehrfunktion: Rohwert = (Wert − Offset) ÷ Skalierung. Ein Befehlsobjekt und sein Rückmeldeobjekt verwenden daher dieselbe Skalierung. |
| Payload-Vorlage | PUB= | Optionale Vorlage für das Senden; {{value}} wird durch den Wert ersetzt, z. B. {"state":"{{value}}"}. Leer lassen, um den reinen Wert zu senden. |
| QoS | QOS= | Broker-Standard, 0, 1 oder 2 für diesen Befehl. |
| Gesendete Nachrichten halten | RETAIN=1 | Standardmäßig deaktiviert. |
| Mindestintervall (ms) | THROTTLE= | Häufig sendende Sensoren werden auf diese Rate begrenzt (Standard: 100 ms); der letzte Wert wird immer verarbeitet. 0 deaktiviert die Begrenzung. |
Die Zeichenkette hat das Format TYP:Parameter:Parameter… – zum Beispiel BOOL:PATH=state:ON=ON:OFF=OFF oder FLOAT:SCALE=0.3937:PUB={"brightness":{{value}}}. Ein leerer Eintrag bedeutet: „Rohwert unverändert als Datentyp des Objekts übernehmen“. Der Objekteditor enthält kein direktes Datentyp-Feld: Der Typ ergibt sich aus dem ausgewählten Datenfeld im Topic-Browser (unten); das Anklicken eines Feldes passt den Objekttyp automatisch an. Farbobjekte (RGB) akzeptieren {"r","g","b"}, {"red","green","blue"}, [r,g,b], #RRGGBB und 255,128,0 beim Empfang und senden {"r":…,"g":…,"b":…}, sofern keine Vorlage definiert ist.
⚠️ Warnung: Ein als Retained gesendeter Befehl wird bei jeder Wiederverbindung des Geräts mit dem Broker erneut ausgeführt. Halten Sie Status-Nachrichten, keine Befehle – der Editor warnt, wenn Sie Retain für ein ausgehendes Objekt aktivieren.
Topic-Browser. MQTT ist das einzige Protokoll, dessen Adressen direkt über das Netzwerk ausgelesen werden können. Klicken Sie im Objekteditor unter MQTT-Topic-Konfiguration auf Broker scannen: Der Server lauscht vier Sekunden lang auf dem gesamten Broker und meldet, wie viele Topics empfangen wurden (Retained-Topics werden sofort geliefert, sodass ein kurzer Scan bereits die meisten relevanten Einträge anzeigt; bei Geräten ohne Retain lösen Sie eine Wertänderung aus und scannen erneut). Die Liste ist auf 500 Topics begrenzt. Ein partieller Scan ist nicht möglich: Öffnen Sie Topic und tippen Sie in Topics suchen…, um die Ergebnisse zu filtern, oder geben Sie das Topic manuell ein. Jede Zeile zeigt das Topic und dessen letzte Payload mit einem Retained-Hinweis. Wählen Sie ein Topic:
- Bei einer JSON-Payload werden alle Felder unter Wählen Sie den Wert, dem dieses Objekt folgen soll aufgelistet – ein Klick setzt den JSON-Pfad, den Objekttyp und bei booleschen Werten die EIN/AUS-Token in der geräteeigenen Syntax;
- Bei einer einfachen Payload übernimmt Rohwert als
verwenden den Typ direkt.
Wählen Sie das Topic aus, bevor Sie ein Feld anklicken: Die Auswahl eines anderen Topics setzt das Payload-Format, den JSON-Pfad und die Token zurück. Der Klick setzt Skalierung und Offset nicht automatisch.
Sie können Topics auch manuell eintragen, falls sie während des Scans nicht aktiv waren – ein Befehls-Topic wurde möglicherweise noch nie gesendet, oder ein eingehendes Objekt benötigt ein Wildcard. Tragen Sie es unter Topic ein und klicken Sie in der Liste auf „…“ verwenden.
Wichtige Verhaltensweisen
- Sofortiger Status nach Neustart: Retained-Nachrichten werden vom Broker bei jeder (Wieder-)Verbindung erneut bereitgestellt, sodass Widgets Werte anzeigen, ohne auf das nächste Sendeintervall des Geräts warten zu müssen.
- Keine Rückmelde-Simulation: Ein Befehl gilt erst dann als bestätigt, wenn das Gerät sein Status-Topic aktualisiert (oder der Broker dieses sendet) – exakt wie bei KNX-Statusobjekten. Reagiert das Gerät nicht, zeigt das Widget keine Zustandsänderung an.
- Befehle bei Verbindungsunterbrechung: Befehle mit QoS 1 oder 2 werden zwischengespeichert, während der Broker nicht erreichbar ist, und bei Wiederverbindung zugestellt; QoS-0-Befehle an einen nicht erreichbaren Broker verfallen und werden protokolliert.
- Schutzmechanismen: Payloads über 64 KB werden mit einer Warnung verworfen; pro eindeutigem Topic-Filter wird genau ein Abonnement geöffnet, unabhängig davon, wie viele Objekte dieses nutzen.
Praxisbeispiel – Dimmbare Leuchte über Zigbee2MQTT
Zigbee2MQTT veröffentlicht den Status der Leuchte als JSON auf zigbee2mqtt/lampe ({"state":"ON","brightness":178}) und empfängt Steuerbefehle auf zigbee2mqtt/lampe/set. Der Helligkeitsbereich liegt zwischen 0 und 254.
- Erstellen Sie eine MQTT-Verbindung für den Broker (siehe „Verbindungen“): Broker-Adresse
192.168.1.10, Port1883, gegebenenfalls die Zugangsdaten des Zigbee2MQTT-Brokers. Klicken Sie auf Testen – die Rückmeldung muss erfolgreich sein. - Fügen Sie unter Geräte ein Dimmer-Widget mit dem Namen „Büroleuchte“ hinzu. Wählen Sie unter Protokoll Ihre Broker-Verbindung über den vergebenen Namen aus. Das Gerät wird mit vier Objekten angelegt: Schalten EIN/AUS, Schalt-Rückmeldung, Dimmwert-Sollwert und Dimmwert-Rückmeldung.
- Bei Schalten EIN/AUS (Befehl Schalten): Geben Sie
zigbee2mqtt/lampe/setunter Topic ein und klicken Sie auf „…“ verwenden. Setzen Sie das EIN-Token aufON, das AUS-Token aufOFFund die Payload-Vorlage auf{"state":"{{value}}"}. Geben Sie die Token explizit ein: Die ausgegrauten AnzeigenONundOFFdienen nur als Platzhalter; ohne Token sendet der Schaltertrueoderfalse. - Bei Schalt-Rückmeldung (Status Schalten): Klicken Sie auf Broker scannen, wählen Sie
zigbee2mqtt/lampeund klicken Sie auf das Feldstate– der Editor setzt den JSON-Pfad aufstateund die Token aufON/OFF. - Bei Dimmwert-Sollwert (Befehl Helligkeit): Topic
zigbee2mqtt/lampe/set, Payload-Vorlage{"brightness":{{value}}}, Skalierung0.3937, Offset0. - Bei Dimmwert-Rückmeldung (Status Helligkeit): Topic
zigbee2mqtt/lampe, wählen Sie das Feldbrightnessund hinterlegen Sie dieselbe Skalierung0.3937. Dieser Wert entspricht ca.100/254: Eingehende Werte werden damit multipliziert (Zigbee 0–254 wird zu 0–100 %), ausgehende Werte werden dividiert (0–100 % wird zu 0–254). - Klicken Sie bei jedem Objekt auf Objekt speichern, danach in der Seitenleiste auf Änderungen übernehmen und bestätigen Sie den Vorgang.
- Stellen Sie die Helligkeit in der App auf
50 %. Die Leuchte empfängt ca.127, und ihre Rückmeldung liefert ca.50 %zurück. Der Schieberegler bestätigt den Zustand über das Status-Topic; wird die Leuchte über eine physische Fernbedienung gedimmt, aktualisiert sich die Anzeige in der App synchron.
📘 Hinweis: Der gesendete Wert wird nicht gerundet:
50 %wird als127.000254übertragen. Da der Objekteditor kein direktes Datentyp-Feld besitzt, kann ein Befehlsobjekt nicht auf Ganzzahlen begrenzt werden. Prüfen Sie, ob das Endgerät dezimale Helligkeitswerte akzeptiert.
MQTT-Verknüpfung
MQTT-Objekte werden in den Objekteinstellungen konfiguriert (öffnen Sie das Objekt über Bearbeiten, siehe „Objekteinstellungen, Protokollierung & Benachrichtigungen“). Der protokollspezifische Bereich gliedert sich in drei Abschnitte:
MQTT-Topic-Konfiguration
| Feld | Beschreibung |
|---|---|
| Topic | Das Topic, welches dieses Objekt abonniert (In: Status-Topic – Wildcards + und # zulässig) oder auf dem es veröffentlicht (Out: Befehls-Topic – keine Wildcards). Nach dem Klick auf Broker scannen aus der Liste auswählen oder manuell eingeben. Die gespeicherte Adresse lautet <Verbindung>:<Topic>. |
| Broker scannen | Lauscht einige Sekunden auf dem Broker und listet empfangene Topics mit der letzten Payload und dem Status Retained auf. Bei Auswahl eines Topics mit JSON-Payload werden die Felder unter Wählen Sie den Wert, dem dieses Objekt folgen soll angezeigt – ein Klick übernimmt JSON-Pfad, Datentyp und EIN/AUS-Token; bei einfachen Payloads über Rohwert als |
| Payload-Format | Rohwert (die gesamte Payload entspricht dem Wert) oder JSON mit einem JSON-Pfad (state, sensor.temperature, values[0]). |
| EIN-Token / AUS-Token | Boolesche Objekte: Zeichenfolgen, die das Gerät für true/false sendet und erwartet (z. B. ON / OFF). |
Veröffentlichen (ausgehende Objekte)
| Feld | Beschreibung |
|---|---|
| Payload-Vorlage | Optional. {{value}} wird durch den Wert ersetzt; leer lassen, um den reinen Wert zu senden. |
| QoS | Broker-Standard, 0, 1 oder 2 – die Zustellgarantie für diesen Befehl. |
| Gesendete Nachrichten halten | Standardmäßig deaktiviert. Ein gehaltener Befehl wird bei jedem Neuverbinden des Geräts erneut gesendet – halten Sie Statuswerte, keine Befehle. |
Abonnieren (eingehende Objekte)
| Feld | Beschreibung |
|---|---|
| Mindestintervall (ms) | Häufig sendende Sensoren werden auf diese Rate begrenzt (Standard: 100 ms); der letzte Wert wird immer verarbeitet. 0 deaktiviert die Begrenzung. |
| Skalierung / Offset | Numerische Objekte: Wert = Rohwert × Skalierung + Offset beim Empfang, die Umkehrfunktion beim Senden. |
Die Parameter werden als Datentypspezifikation des Objekts gespeichert (z. B. BOOL:PATH=state:ON=ON:OFF=OFF) – Aufbau, Topic-Browser und ein Anwendungsbeispiel sind im obigen Abschnitt beschrieben.
