Simple EnOcean MQTT Client

einleitung das export modul "simple enocean mqtt client" stellt die verbindung zu einem mqtt broker her und veröffentlicht nachrichten unter verschiedenen topics es können mehrere export instanzen angelegt werden, jedoch immer nur eine instanz pro broker url nachrichten werden grundsätzlich als string übertragen und sind im regelfall als json objekte formatiert konfiguration im bereich iot export der web konfiguration oder der bsc remote können die export verbindung angelegt, sowie die parameter konfiguriert werden es werden tcp/ssl sowie web socket (http/https) verbindungen unterstützt die authentifizierung ist per nutzername und passwort oder client zertifikat möglich die entsprechenden zertifikate oder zugangsdaten können während der konfiguration hinterlegt werden es besteht die möglichkeit die basis topics zum veröffentlichen von nachrichten anzupassen parameter parameter standardwert mögliche werte beschreibung user verfügbare benutzer accounts der zu verwendende nutzeraccount beim zugriff auf die daten es ist so möglich den export von geräten oder den zugriff auf kommandos einzuschränken connection mode socket socket websocket auswahl ob eine tcp oder web socket verbindung genutzt wird broker ip oder dns name des brokers ohne protokoll oder port beispiel test mosquitto org der broker zu welchem die verbindung aufgebaut werden soll port 1883 1 65535 der beim verbindungsaufbau zu verwendende port auth user nutzername zur anmeldung am broker auth password passwort zur anmeldung am broker ssl off on trust all off option ob eine verschlüsselte verbindung aufgebaut werden soll mit der option "trust all" ist es möglich allen zertifikaten zu vertrauen ssl server crt im ssl modus wird das server zertifikat verwendet um die verbindung zum broker zu validieren ssl client crt im ssl modus wird das client zertifikat zur validierung des client genutzt ssl client key im ssl modus wird der private client schlüssel zur authentifizierung am broker genutzt ssl client key password im ssl modus wird dieses passwort benutzt um den client schlüssel zu entsperren https hostname verification on on off im ssl modus wird der verwendete hostname im zertifikat des broker explizit überprüft qos 0 0 1 2 der qos wert bestimmt wie nachrichten ausgeliefert werden je höher der qos wert ist, umso größer wird die latenz der nachrichtenauslieferung qos 0 bedeutet, das die nachrichten ohne empfangsbestätigung verschickt werden ein klassisches "fire & forget" qos 1 hingegen versendet die nachricht so lange bis eine bestätigung des empfangs durch den broker erfolgt ist der client kann sicher sein, das der broker die nachricht empfangen hat es ist möglich das eine nachricht mehrfach gesendet oder auch ausgeliefert wird qos 2 verwendet eine doppelte bestätigung um sicherzustellen das eine nachricht nur einmalig ausgeliefert wird hierzu bestätigt der broker dem client den empfang, der client wiederum bestätigt dem broker den empfang der bestätigung somit wissen client und broker beide das die nachricht korrekt und einmalig ausgeliefert wurde durch die verwendung von event ids sowie zeitstempeln in den nachrichten containern, welche von dieser implementierung verwendet werden, ist es möglich mit doppelten nachrichten umzugehen und so die hohen latenzen durch qos 2 zu vermeiden und ähnliche sicherheit mit qos 1 umsetzen grundsätzlich kann auch qos 0 in umgebungen mit stabilen verbindungen genutzt werden retain messages on on off gibt an ob die letzte nachrichten für ein topic auf dem broker zwischengespeichert werden soll andere clients bekommen diese nachrichten dann direkt nach ihrer anmeldung ausgeliefert so kann effektiv der letzte bekannte zustand auf dem broker zwischengespeichert werden timeout (s) 90 0 10 15 30 60 90 120 150 180 300 600 1200 1800 3600 zeit in sekunden welche gewartet wird um eine erfolgreiche verbindung aufzubauen ansonsten wird dies als fehler interpretiert der wert 0 deaktiviert den timeout, es wird so lange gewartet bis die verbindung erfolgreich aufgebaut werden konnte keep alive interval (s) 60 0 10 15 30 60 90 120 150 180 300 600 1200 1800 3600 zeit in sekunden die maximal vergehen darf bis ein datenpaket gesendet werden muss ist kein regulärer datenverkehr innerhalb dieser zeit vorhanden, wird automatisch ein ping versendet der wert 0 deaktiviert diese überwachung max inflight 10000 1 65000 im qos modus 1 und 2 bestimmt dieser wert die maximale anzahl an nachrichten, welche gesendet werden können ohne das eine bestätigung des empfangs eingegangen ist ggf muss dieser wert in sehr großen betriebsumgebungen erhöht werden parameter standardwert mögliche werte beschreibung enocean topic prefix enocean alle thing updates werden in topics mit diesem prefix veröffentlicht gateway topic prefix gateway status nachrichten bezüglich des gateways werden unter diesem prefix veröffentlicht datenmodell basis daten von nachrichten alle nachrichten werden als json objekte übertragen grundlegende informationen für die zuordnung von nachrichten sind in allen objekten vorhanden basis felder feld datentype beschreibung nodeid string eine eindeutige id, welche das gateway identifiziert timestamp number unterschied, gemessen in sekunden, zwischen der aktuellen zeit und dem 01 01 1970 00 00 uhr basierend auf der utc zeitzone sensoren / aktoren neben den basis feldern sind die folgende felder im geräte objekt verfügbar feld datentype beschreibung name string der für das gerät hinterlegte name eurid string die eindeutige enocean eurid des gerätes refid string ein eindeutiger interner bezichner des geräte types channels array eine liste von verfügbaren kanälen und deren werte der key ist gleichzeitig die kanal id, der wert ist entweder eine nummer oder ein text beispiel daten fsb 14 { 	"nodeid" "acdbda5906ee", 	"timestamp" 1689865668, 	"name" "fsb 14", 	"eurid" "2a3df3d", 	"refid" "enocean eltako fsb14", 	"channels" { 	 "jalousieslat" "unknown", 	 "jalousie" 65 0, 	 "priority" "off", 	 "jalousiestate" "unknown" 	} } fsr 14 { 	"nodeid" "acdbda5906ee", 	"timestamp" 1689865842, 	"name" "fsr14", 	"eurid" "c23df34", 	"refid" "enocean eltako fsr14", 	"channels" { 	 "switch" "on", 	 "priority" "off" 	} } gateway status neben den basis feldern sind die folgende felder im gateway status objekt verfügbar feld datentype beschreibung version string die aktuell verwendete software version online boolean gibt an ob das gerät aktuell online ist beispiel daten gateway status objekt { 	"nodeid" "acdbda5906ee", 	"timestamp" 1689864643, 	"version" "3 5 1", 	"online" true } mqtt topics die genutzte topic struktur unterteilt sich in daten und kommando topics daten topics über die daten topics versendet das gateway seine und die status meldungen der verbundenen geräte sensoren / aktoren als basis dient das in der konfiguration unter "enocean topic prefix" hinterlegte topic dieser pfad wird um die eurid des gerätes erweitert und dort die geräte nachricht veröffentlicht beispiel topic enocean/513659d gateway als basis dient das in der konfiguration unter "gateway topic prefix" hinterlegte topic dieser pfad wird um die hardware id des gerätes erweitert und dort die status nachricht veröffentlicht beispiel topic gateway/acdbda4512e0 kommando topics über die kommando topics ist eine einfach möglichkeit der steuerung des gateways umgesetzt aktoren als basis dient das in der konfiguration unter "enocean topic prefix" hinterlegte topic und ermöglicht es aktoren zu schalten dieser pfad wird um die eurid des gerätes sowie die kanal id erweitert als nutzdaten wird der neue wert als string erwartet beispiel topic enocean/513659d/switch beispiel nutzdaten on off gateway als basis dient das in der konfiguration unter "gateway topic prefix" hinterlegte topic dieser pfad wird um die hardware id des gerätes sowie das auszuführende kommando erweitert als nutzdaten wird ein json objekt mit den entsprechenden parametern erwartet verfübare kommandos kommando payload beschreibung pairing on oder off zeitangabe in sekunden on=90 schalten den modus zum automatischen anlernen von neuen geräten ein oder aus optional kann eine zeitangabe in sekunden erfolgen nach welcher der modus automatisch wieder abgeschaltet wird delete eine geräte eurid es wird versucht das betreffende gerät zu löschen beispiel topic gateway/acdbda4512e0/pairing gateway/acdbda4512e0/delete beispiel nutzdaten on=90 off 513659d