Zum Ende der Metadaten springen
Zum Anfang der Metadaten
Autor
Logo

icon_64.png

Status

PRERELEASE

Version0.4.1
Kompatibilität

LB 0.2.3LB 1.2.5

Downloadhttps://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway/archive/0.4.1.zip
ZweckInstalliert den MQTT-Broker Mosquitto und stellt ein MQTT-Gateway für den Miniserver bereit.
LanguagesEN
 Version History...

Version 0.1.1

  • DEVELOPER PREVIEW - Nur einsetzen mit MQTT und Linux-Kenntnissen - Fehler ausschließlich per Issue bei GitHub
  • Stellt ein MQTT→Loxone Gateway bereit

Version 0.1.2

  • DEVELOPER PREVIEW - Nur einsetzen mit MQTT und Linux-Kenntnissen - Fehler ausschließlich per Issue bei GitHub
  • Implementiert ein UDP-Interface für Loxone→MQTT

Version 0.1.3

  • DEVELOPER PREVIEW - Nur einsetzen mit MQTT und Linux-Kenntnissen - Fehler ausschließlich per Issue bei GitHub
  • Eigene UI-Sektion für MQTT Broker
  • Authentifizierung für MQTT Broker
  • Lokaler Mosquitto abschaltbar
  • Retry für den Mosquitto Service, wenn er beim Systemstart nicht automatisch gestartet wurde
  • MQTT Gateway wird direkt nach der Installation gestartet
  • Parameter-Update-Routine zum Hinzufügen von neuen Default-Parametern während der Installation

Version 0.1.4

  • DEVELOPER PREVIEW - Nur einsetzen mit MQTT und Linux-Kenntnissen - Fehler ausschließlich per Issue bei GitHub
  • UI: Expand JSON Option hinzugefügt
  • Gateway: JSON wird bei HTTP expandiert (nur erster Level) und beim HTTP-Namen angehängt - EXPERIMENTELL
  • Gateway: Alle übermittelten Topics werden im Speicher behalten (max. 24 Stunden)
  • UI: Funktion zum Abfragen der gespeicherten Gateway-Topics (wird aber noch nicht dargestellt)

Version 0.1.5

  • DEVELOPER PREVIEW - Nur einsetzen mit MQTT und Linux-Kenntnissen - Fehler ausschließlich per Issue bei GitHub
  • UI: Größerer Umbau des UI (Settings, Subscriptions, Conversions, Incoming Overview, Logfiles) als Navbar
  • UI: Subscriptions jetzt als eigene Seite (leichter anzupassen, man muss nicht immer auf- und abscrollen für Apply)
  • UI: Conversions: Angabe von Strings, die zu Werten konvertiert werden sollen (Loxone kann mit Strings nichts anfangen)
  • UI: Incoming Overview: Anzeige der an den Miniserver übermittelten Werte
  • UI: Logs: Inline-Anzeige der Logfile-Übersicht
  • Gateway: Benutzerdefinierte Conversion (eingehende Nachrichten können in Werte konvertiert werden)
  • Gateway: Logfile: Parsing der Conversion wird geloggt, inklusive "komischer" Werte und Duplikate
  • Gateway: Logfile wird beim Beenden des Gateways sauber abgeschlossen

Version 0.2.0 PRE-RELEASE

  • Erster Pre-Release
  • Allgemein: Neues Logo (MQTT-Logo statt Mosquitto-Logo)
  • Gateway: Besseres Fehlerhandling beim Restart des Gateways
  • UI: Filter bei den übermittelten Nachrichten (erleichtert die Suche)
  • Donation: Erster Versuch, per Spende einen eigenen Test-Miniserver zusammen zu bekommen

Version 0.3 PRE-RELEASE

  • Lokale Mosquitto-Authentifizierung als Standard (Benutzer: loxberry, Passwort: wird generiert)
  • Broker-Anmeldedaten werden nur dann geladen, wenn der SecurePIN angegeben wird
  • Ermöglicht direkt, die lokalen Mosquitto-Anmeldedaten zu ändern oder zu deaktivieren
  • Änderung der Anmeldedaten eines nicht lokalen Brokers ändert nur die Anmeldung des Gateways
  • Änderung der Konfiguration übernimmt diese sofort für das MQTT Gateway und/oder Mosquitto

Version 0.3.1 PRE-RELEASE

  • Fix: Bei anonymer Verwendung von Mosquitto startet der Mosquitto-Dienst nach Reboot nicht mehr
  • Aktivierung von Plugin AutoUpdate (ab dieser Version können Versions-Notifications oder automatisches Update aktiviert werden)

Version 0.4.1 PRE-RELEASE

  • Fix: Nach Konfigurationsänderungen und "Apply" wurden diese nicht übernommen
  • Neu: Per UDP eingehende Nachrichten werden vollständig weitergegeben (so können beispielsweise auch json Nachrichten gesendet werden)
  • Neu: Das Gateway published seinen Connection-Status selbst unter dem Topic <hostname>/mqttgateway/status
  • Neu: Das Gateway published im Minutentakt den aktuellen Epoch-Timestamp.
  • Neu: Das Gateway subscribed sich selbst automatisch - so kann der Timestamp als Prüfung verwendet werden, ob das Gateway noch funktioniert
  • Neu: Unterstützt Last Will and Testament (d.h. Broker setzt den Status auf Disconnected, wenn das Gateway stirbt)
  • Neu: UDP-Nachrichten können mit publish oder retain gesendet werden
  • Neu: UDP-Nachricht "reconnect" forciert das Neu-Verbinden und Übertragen an den Miniserver
  • Neu: Default-UDP-In-Port am Gateway: 11884 (bisher 11883)

Inhalt



Download

Der direkte Download befindet sich in der Tabelle oben.

Repository: https://github.com/christianTF/LoxBerry-Plugin-MQTT-Gateway

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 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

EinstellungStandardBeschreibung
MiniserverErster MiniserverDie abonnierten Daten werden an diesen Miniserver gesendet.
Miniserver-UDP-Port11883Ist 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 shellies_shelly-12345_relay_1

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: MQTT: shellies/shelly-12345/relay/1=\v

Booleans konvertierenEinIn 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 das erste Level der JSON-Struktur (also keine Arrays oder Objekte!) expandiert und an den http-Namen angehängt.

Topic/abcde={"action":"on","linkquality":39} wird zu
Topic_abcde_action = on (oder 1)
Topic_abcde_linkquality = 39

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:

button-up=1
button-down=2

Sendet ein Device Topic_abcde_status=button-down, wird dies als Topic_abcde_status=2 an den Miniserver übertragen.

Beispielsweise in einem Status-Baustein kann der Wert weiter verarbeitet 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

EinstellungStandardBeschreibung
Gateway UDP IN-Port11884

Eingangsport am LoxBerry für UDP-Nachrichten, die an MQTT-Geräte weitergeleitet werden.

Folgende Befehle werden unterstützt:

  • <topic> <value> → löst eine Publish-Nachricht aus
  • publish <topic> <value>löst eine Publish-Nachricht aus
  • retain <topic> <value>löst eine Retain-Nachricht aus (wird am Broker gespeichert)
  • reconnect → Löst eine Neuverbindung und ein forciertes Übermitteln der Daten an den Miniserver aus

Beispiel 1: shellies/shellyswitch-32BA7F/relay/1/command on
Beispiel 2: retain wohnzimmer/temperature 12.5
Beispiel 3: reconnect

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

EinstellungStandardBeschreibung
Lokalen Mosquitto-Broker verwendenJa

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)
Inaktiv: Du kümmserst dich selbst um den Broker

MQTT Broker Adresselocalhost

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 Benutzernameloxberry

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>

Bekannte MQTT-Geräte und Subscription-Topics

Liebe Plugin-Benutzer! Bitte pflegt diese Tabelle mit euren eingesetzten Geräten, MQTT-Infos und Links! Bitte direkt hier eintragen.

AnbieterMQTT-Topic SubscriptionBemerkungenMQTT-Doku-Link
ALLTERCO ROBOTICS Shellyshellies/#

Derzeit Bug in der Shelly-Implementierung beim Power-Monitoring (Link)

Link
Bluetooth-based passive presence detectionmonitor/# (konfigurierbar)

UDP Befehlserkennung für die Confidence:

MQTT: monitor/first_floor/12:34:56:78:9a:bc=\i"confidence"\i:"\v

Link
Kodi MQTT Addonkodi/# (konfigurierbar)Unterstützt auch das Senden von On-Screen-Messages und Play-BefehlenLink
FHEM(konfigurierbar)Senden des Status und von BefehlenLink
WinThingwinthing/system/onlineJava-Applikation. Unterstützt Befehle wie shutdown, reboot, hibernate, sowie Ausführung beliebiger Commands.Link
Sonoff Tasmota

tele/sonoff/# (zyklischer Status)

stat/sonoff/# (Status beim Schalten)

(Gerätebezeichnung sonoff konfigurierbar)

Custom Firmware für Sonoff Wifi Geräte

Status via stat/sonoff/POWER liefert ON oder OFF als Wert, dies muss im Conversions Tab mit ON=1 und OFF=0 definiert werden

Link








 

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
  • Mosquitto: Standardmäßig mit Authentifizierung einrichten
  • Gateway: Eigenes Topic zur Steuerung des MS
  • Gateway: Connection-Status publishen
  • Gateway: Last Will And Testament
  • Healthstatus aller Verbindungen
  • Notifications bei Verbindungsfehlern

Fragen stellen und Fehler melden

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


Siehe auch