| Autor | |
|---|---|
| Logo |
|
| Status | RELEASE |
| Version | 0.8.1 |
| Min. LB Version | LB 1.4.0 |
| Download | Release: https://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway/archive/0.8.1.zip Pre-Release: https://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway/archive/0.8.2.zip |
| Zweck | Installiert den MQTT-Broker Mosquitto und stellt ein MQTT-Gateway für den Miniserver bereit. |
| Languages | EN |
Inhalt
Download
Der direkte Download des Releases befindet sich in der Tabelle oben.
Pre-Release: https://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway/archive/0.8.2.zip
Repository: https://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway
Kommunikationsdiagramm
(Anklicken zum Vergrößern)
Sieh dir links im Navigationsbaum weiterführende Artikel zu MQTT an, um die Funktionsweise besser zu verstehen.
Begriffserklärung
Ein "Broker" ist ein Dienst, der als Vermittler von Nachrichten dient. Der Broker speichert auch den aktuellen Zustand aller angeschlossenen Geräte. Das Plugin installiert automatisch am LoxBerry den Mosquitto MQTT Broker als Vermittler. Über die Konfiguration kann auch ein Broker auf einem anderen Server angegeben werden. Das Plugin unterstützt Authentifizierung, jedoch keine Verschlüsselung zum Broker.
Ein "Server" ist in der Begrifflichkeit von MQTT jedes Gerät, das Daten einliefert. Beispielsweise sind die Shelly's MQTT-Server, die Daten an den Broker übermitteln.
Ein "Client" ist jede Software, die sich mit dem Broker verbindet und dort Stati abfragt, Befehle sendet bzw. auf Statusänderungen lauscht. Dieses Plugin ist so ein Client, der zum Broker verbindet und sich Statusaktualisierungen abonniert (subscribed). Ist vom Client ein MQTT-Topic abonniert, werden Daten dieses Topics vom Broker an diesen Client zur Verarbeitung weitergeleitet.
Funktion des Plugins
Das Plugin installiert zuerst automatisch den Mosquitto MQTT Broker (Hostname "localhost"). Erfahrene Benutzer können auch eine Verbindung zu einem anderen Broker einrichten. Das Plugin unterstützt kein TLS zum MQTT-Broker.
Das Plugin fungiert dann als Client an diesem MQTT-Broker, und leitet MQTT-Nachrichten an den Miniserver weiter, sowie empfängt Nachrichten vom Miniserver und leitet diese an den MQTT-Broker. Über das Webinterface können Topics abonniert werden. Die abonnierten Topics werden wahlweise per UDP, oder per HTTP Webservice an den eingestellten Miniserver übermittelt.
Das Senden von Nachrichten vom Miniserver an MQTT geht am besten per UDP.
MQTT an Loxone Miniserver
Einstellungen
| Einstellung | Standard | Beschreibung |
|---|---|---|
| Miniserver | Erster Miniserver | Die abonnierten Daten werden an diesen Miniserver gesendet. |
| Miniserver-UDP-Port | 11883 | Ist UDP aktiviert, werden Nachrichten an diesen UDP-Port des Miniservers übermittelt. |
| Per REST Webservice übermitteln | Ressourcenschonender als UDP! Die Nachricht wird direkt per HTTP-REST Webservice an den Miniserver übertragen. Dafür müssen selbst entsprechende Virtuelle Eingänge mit exakt dem hier dokumentierten Namen verwendet werden. Das Plugin verwendet die Nachricht als Bezeichnung für den Eingang, wobei / in _ konvertiert werden: shellies/shelly-12345/relay/1 wird zu Schau ins Logfile, dort werden die Bezeichnungen angezeigt. | |
| Per UDP übermitteln | Nachrichtenformat (für die Befehlserkennung): MQTT: shellies/shelly-12345/relay/1=off (oder =0) Befehlserkennung: | |
| Booleans konvertieren | Ein | In MQTT werden häufig Strings bei der Nachricht verwendet, beispielsweise "off" oder "on". Das Plugin konvertiert als Booleans identifizierte Strings in die Werte 0 oder 1. Strings, die erkannt werden, siehe LoxBerry::System::is_enabled bzw. LoxBerry::System::is_disabled |
| JSON expandieren | Werden JSON-Daten übertragen, wird die JSON-Struktur expandiert und an den http-Namen angehängt. Topic/abcde={"action":"on","linkquality":39} wird zu Auch Objekte und Arrays in beliebiger Hierarchie werden aufgelöst. Am besten in der Incoming Overview anschauen, wie die Daten nach der Expandierung aussehen. | |
TAB Subscriptions Abonnierte Topics | Die Angabe erfolgt mit einer Zeile pro Topic. Die Topics müssen vom MQTT-Device dokumentiert sein. Eine # definiert dabei einen "Joker" (wie man sonst den * verwendet), z.B. shellies/# abonniert alle Meldungen innerhalb des Topics shellies/. Siehe unten die Kurzübersicht bekannter MQTT-Geräte und Topics. | |
TAB Conversions Eigene Wert-Zu-Text Konvertierung | Da der Miniserver keine Texte weiterverarbeiten kann, können eingehende Nachrichten von einem String zu einem Wert konvertiert werden. Beispiel:
Sendet ein Device Beispielsweise in einem Status-Baustein kann der Wert weiter verarbeitet werden. | |
TAB Incoming Overview Anzeige der übermittelten Daten | Hier werden die per HTTP und UDP übermittelten Daten angezeigt. Die Aktualisierung erfolgt automatisch im Sekundentakt, ohne dass ein Browser-Refresh notwendig ist. In diesem Fenster können mit Copy&Paste virtuelle Eingänge/Texteingänge, oder für UDP die entsprechenden Befehlserkennungen kopiert werden. |
Den Button zum Speichern ganz unten nicht vergessen. Die neue Konfiguration wird beim Speichern automatisch übernommen.
Siehe auch: MQTT - Schritt für Schritt: MQTT -> Loxone
Miniserver an MQTT
| Einstellung | Standard | Beschreibung |
|---|---|---|
| Gateway UDP IN-Port | 11884 | Eingangsport am LoxBerry für UDP-Nachrichten, die an MQTT-Geräte weitergeleitet werden. Folgende Befehle werden unterstützt:
Beispiel 1: |
Wenn der Miniserver neu startet, empfiehlt es sich, mittels der Loxone-Zeit "Startimpuls" ein reconnect per UDP-Nachricht an das Gateway zu übermitteln. Beispiel im "Siehe auch"-Link.
Siehe auch: MQTT - Schritt für Schritt: Loxone -> MQTT
MQTT Broker-Einstellungen
| Einstellung | Standard | Beschreibung |
|---|---|---|
| Lokalen Mosquitto-Broker verwenden | Ja | Ist dies aktiviert, prüft das Plugin beim Reboot, ob Mosquitto läuft, und startet diesen gegebenenfalls. Aktiv: Lokale Mosquitto-Inszanz wird vom Plugin verwaltet (inkl. Änderung von Benutzername und Passwort) |
| MQTT Broker Adresse | localhost | Hier kann der Hostname angegeben werden, mit dem das Gateway verbinden soll. Wird beim Hostnamen kein Port angegeben, wird der Standardport 1883 verwendet. Eine Portangabe erfolgt per hostname:port |
| MQTT Broker Benutzername | loxberry | Der automatisch installierte Mosquitto-Broker wird mit dem Benutzer loxberry und einem generierten Passwort installiert. Diese Informationen kannst du bei der Einrichtung von Devices von hier kopieren. Wenn du Benutzername und Kennwort nachträglich änderst, musst du das auch bei allen bereits konfigurierten Geräten machen! Leerer Benutzer und leeres Kennwort deaktivieren die Authentifizierung am lokalen Broker. Bei externen Brokern wird hier deren Benutzername und Kennwort eingegeben. |
| MQTT Broker Passwort | <generiert> |
Incoming Overview
In der "Incoming Overview" werden alle eingehenden Daten der letzten 24 Stunden angezeigt. Diese wurden - sofern das Caching die Daten nicht unterdrückt hat - so an den Miniserver weitergeleitet.
Die Übersicht wird automatisch aktualisiert. Wenn du Text markierst, wird die Aktualisierung unterdrückt, damit du Bezeichnungen mit der Zwischenablage kopieren kannst.
Show advanced table information
Damit werden zusätzliche Schaltflächen und Optionen angezeigt.
- Topic: Zeigt bei HTTP die originale Topic-Bezeichnung an, auch bei JSON-extrahierten Daten.
- Disable Cache: Dieser Wert übergeht das Caching von LoxBerry, und sendet den Wert immer, auch wenn er gleich bleibt.
- Reset after send: Nachdem der Wert gesendet wurde, wird automatisch eine 0 nachgesendet. Das eignet sich für Geräte (z.B. Taster), die lediglich einen Wert (Impuls) senden und dann auf diesem Wert "stehen bleiben". Ein weiterer Impuls würde verursachen, dass wieder der gleiche Wert gesendet würde, und der Miniserver erkennt keine Änderung.
- Lösch-Symbol: Damit wird der Wert am Broker gelöscht. Bitte beachte, dass in der Übersicht die Zeile erhalten bleibt, weil der Broker durch das Löschen keine Information an die Subscriber aussendet. Die Tabelle wird aktualisiert, wenn du in den "Settings" den Button "Save and Apply" drückst (dieser Knopf löst eine Neuverbindung zum Broker aus).
Bekannte MQTT-Geräte und Subscription-Topics
Liebe Plugin-Benutzer! Bitte pflegt diese Tabelle mit euren eingesetzten Geräten, MQTT-Infos und Links!
Die Liste ist jetzt in diesem Unter-Artikel: MQTT-Gateway - Bekannte MQTT-Geräte und Subscription-Topics
Weitere Hinweise
- Die Deinstallation des MQTT-Gateway Plugins deinstalliert den Mosquitto-Broker nicht. Die Authentifizierungseinstellungen bleiben ebenfalls erhalten. MQTT kann somit - auch ohne Gateway - weiter verwendet werden. Uninstall von Mosquitto mit
apt-get purge mosquitto mosquitto-clients
Roadmap
- Fehlerkorrekturen
- Gateway: Eigenes Topic zur Steuerung des MS
- Healthstatus aller Verbindungen
- Notifications bei Verbindungsfehlern
Fragen stellen und Fehler melden
MQTT Gateway - Troubleshooting Guide
GitHub: https://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway/issues
Forum: https://www.loxforum.com/forum/projektforen/loxberry/plugins/176025-loxberry-mqtt
Fehlerbeschreibungen
Für jeglichen Kontakt bzw. Probleme immer mitliefern:
- das Logfile
- die MQTT-Spezifikation des angebundenen Devices (z.B. direkter Link zur MQTT-Dokumentation des Geräts)
- Screenshots bzw. Beschreibung der durchgeführten Einstellungen usw.
Known Issues
- LoxBerry-Problem, Nicht kritisch, in LoxBerry 1.4 behoben: https://github.com/mschlenstedt/Loxberry/issues/811
- Beim Update des Plugins und Verwendung eines externen Brokers wird das Passwort auf ein generiertes Passwort gesetzt
Siehe auch
- Einrichtung am MQTT-Device
- HTTP-Eingänge am Miniserver debuggen
- MQTT Gateway - Alle FHEM-Readings weitergeben
- MQTT-Gateway - Bekannte MQTT-Geräte und Subscription-Topics
- MQTT Gateway - HTTP- und UDP-Interface
- MQTT Gateway - Konfiguration sichern und auf anderem/neuen LoxBerry wiederherstellen
- MQTT Gateway - Subscriptions und Topics
- MQTT Gateway - Troubleshooting Guide
- MQTT - Schritt für Schritt: Loxone -> MQTT
- MQTT - Schritt für Schritt: MQTT -> Loxone
- Was ist MQTT? Warum MQTT?
- Informationen und Best Practices zu Topics und Subscrictions: https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices/
- Miele Home MQTT Gateway: https://www.loxforum.com/forum/projektforen/loxberry/plugins/176967-miele-mqtt-loxberry-mqtt
- Verschiedene MQTT-Interfaces von Devices und Diensten: https://github.com/hobbyquaker/awesome-mqtt#interfaces
- Fronius Hybrid und go-eCharger Bridge: https://github.com/akleber/mqtt-connectors