Generic MQTT Client

einleitung das export modul "generic mqtt client" stellt die verbindung zu einem mqtt broker her und veröffentlicht status nachrichten unter verschiedenen topics diese topics sind von der struktur her ähnlich aufgebaut wie die url struktur des "generic rest server" export moduls die versendeten nachrichten verwenden das generic iot datenmodell docid 1gmhrwxfum029mcblknnu innerhalb eines container objektes, welches informationen zur nachrichten identifikation bereitstellt es können mehrere export instanzen angelegt werden, jedoch immer nur eine instanz pro broker url nachdem die verbindung zu einem broker aufgebaut wurde, werden alle verfügbaren geräte als update übertragen somit ist sichergestellt das der aktuelle gerätestatus übermittelt wurde 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 thing topic prefix gateway id/things alle thing updates werden in topics mit diesem prefix veröffentlicht command topic gateway id/cmd unter diesem topic können kommandos an das gateway gesendet werden status topic gateway id/status unter diesem topic veröffentlich das gateway seine status informationen der verbindungsstatus verbunden/getrennt kann hier ausgelesen werden notification topic gateway id/msg push benachrichtigungen für den ausgewählten benutzer werden unter diesem topic veröffentlicht basisdaten von nachrichten alle nachrichten, ausgenommen raw 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 eventid string eine eindeutige id, welche das auslösende event identifiziert es ist möglich das mehrere nachrichten durch das gleiche event erzeugt werden und somit die gleiche event id erhalten ein beispiel dafür wären geräte updates dort werden sub topics verwendet, somit erhalten die einzelnen kanal sub topics nachrichten mit der gleichen event id es ist garantiert das eine event id innerhalb von 24 stunden nur einmalig vorkommt timestamp number unterschied, gemessen in millisekunden, zwischen der aktuellen zeit und dem 01 01 1970 00 00 uhr basierend auf der utc zeitzone dieser zeitstempel kann, zusammen mit der event id, auch dazu genutzt werden nachrichten eindeutig zu identifizieren geräte topics das in der konfiguration hinterlegte "thing topic prefix" dient als basis für alle geräteaktualisierungen ein beispiel dafür wäre "acdbda59e9cf/things" die eigentlichen geräteaktualisierungen werden über verschachtelte "sub topics" veröffentlicht sub topics die sub topics werden nur bei einer änderung von werten benachrichtigt so kann bei der "subscription" gezielt entschieden werden, über welche daten man benachrichtigt wird sub topic beschreibung /\<thing id> das komplette thing objekt /\<thing id>/state den online/offline status des gerätes /\<thing id>/metainfos die meta informationen des gerätes /\<thing id>/\<channel id>/value der wert eines einzelnen kanals /\<thing id>/\<channel id>/value/raw der wert als plaintext string ohne nachrichtencontainer /\<thing id>/parameter/\<channel id>/value der wert eines einzelnen parameterkanals /\<thing id>/parameter/\<channel id>/value/raw der wert eines parametekanals als plaintext string ohne nachrichtencontainer ändern von werten die änderung eines wertes kann über extra dafür vorgesehenene "sub topics" angestoßen werden es wird zwischen kanal und parameterwerten unterschieden kanalwerte /\<thing id>/\<channel id>/value/set parameterwerte /\<thing id>/parameter/\<channel id>/value/set der neue wert wird einfach als nachricht an dieses topic gesendet sobald der wert (real) geändert wurde, werden entsprechende aktualisierungen an die vorher schon beschriebenen "sub topics" gesendet alternativ gibt es auch ein kommando objekt zum ändern von werten, näheres dazu ist im abschnitt zum kommando topic nachzulesen beispiel daten repräsentation eines gerätes acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183 { &#x9;"nodeid" "acdbda59e9cf", &#x9;"eventid" "igu16ksjlsu6m80v", &#x9;"timestamp" 1636543467229, &#x9;"thing" { &#x9; "id" "b9f09ef8 3c3f 459e 841f 66bdaedff183", &#x9; "name" "fsb14", &#x9; "channelgroups" \[{ &#x9; "channelgroupid" "sensor group", &#x9; "channeldescriptiondata" null, &#x9; "channels" \[{ &#x9; "channelid" "jalousie", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "shading", &#x9; "label" { &#x9; "de de" "jalousie", &#x9; "en us" "shutters" &#x9; } &#x9; }, &#x9; "value" "29 0", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "number double", &#x9; "unit" "%", &#x9; "min" 0 0, &#x9; "max" 100 0, &#x9; "stepping" 1 0, &#x9; "decimalpartdigits" 1, &#x9; "possiblevalues" null &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#jalousie", &#x9; "message >count" "0", &#x9; "eoap >changeable" "true", &#x9; "message >enabled" "false", &#x9; "sensor name" "jalousie", &#x9; "tsystems >type" "value" &#x9; } &#x9; }, { &#x9; "channelid" "jalousiestate", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "shading", &#x9; "label" { &#x9; "de de" "jalousie", &#x9; "en us" "shutters" &#x9; } &#x9; }, &#x9; "value" "unknown", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "state", &#x9; "unit" null, &#x9; "min" null, &#x9; "max" null, &#x9; "stepping" null, &#x9; "decimalpartdigits" null, &#x9; "possiblevalues" { &#x9; "unknown" { &#x9; "de de" "unbekannt", &#x9; "en us" "unknown" &#x9; }, &#x9; "up" { &#x9; "de de" "herauf", &#x9; "en us" "up" &#x9; }, &#x9; "down" { &#x9; "de de" "herunter", &#x9; "en us" "down" &#x9; } &#x9; } &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#jalousiestate", &#x9; "message >count" "0", &#x9; "eoap >changeable" "false", &#x9; "message >enabled" "false", &#x9; "sensor name" "direction", &#x9; "tsystems >type" "state" &#x9; } &#x9; }, { &#x9; "channelid" "priority", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "switch", &#x9; "label" { &#x9; "de de" "priorität", &#x9; "en us" "priority" &#x9; } &#x9; }, &#x9; "value" "off", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "state", &#x9; "unit" null, &#x9; "min" null, &#x9; "max" null, &#x9; "stepping" null, &#x9; "decimalpartdigits" null, &#x9; "possiblevalues" { &#x9; "unknown" { &#x9; "de de" "unbekannt", &#x9; "en us" "unknown" &#x9; }, &#x9; "on" { &#x9; "de de" "an", &#x9; "en us" "on" &#x9; }, &#x9; "off" { &#x9; "de de" "aus", &#x9; "en us" "off" &#x9; } &#x9; } &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#priority", &#x9; "message >count" "0", &#x9; "eoap >changeable" "true", &#x9; "message >enabled" "false", &#x9; "sensor name" "priority", &#x9; "tsystems >type" "state" &#x9; } &#x9; }, { &#x9; "channelid" "jalousieslat", &#x9; "channeldescriptiondata" { &#x9; "channeltypeenum" "shading", &#x9; "label" { &#x9; "de de" "jalousie (lamellen)", &#x9; "en us" "shutters (slats)" &#x9; } &#x9; }, &#x9; "value" "unknown", &#x9; "valuedescriptiondata" { &#x9; "valuetype" "state", &#x9; "unit" null, &#x9; "min" null, &#x9; "max" null, &#x9; "stepping" null, &#x9; "decimalpartdigits" null, &#x9; "possiblevalues" { &#x9; "unknown" { &#x9; "de de" "unbekannt", &#x9; "en us" "unknown" &#x9; }, &#x9; "up" { &#x9; "de de" "herauf", &#x9; "en us" "up" &#x9; }, &#x9; "down" { &#x9; "de de" "herunter", &#x9; "en us" "down" &#x9; } &#x9; } &#x9; }, &#x9; "writeable" false, &#x9; "metainfos" { &#x9; "metainfo >id" "asensor#b9f09ef8 3c3f 459e 841f 66bdaedff183#jalousieslat", &#x9; "message >count" "0", &#x9; "eoap >changeable" "true", &#x9; "message >enabled" "false", &#x9; "sensor name" "jalousieslat", &#x9; "tsystems >type" "state" &#x9; } &#x9; }] &#x9; }], &#x9; "state" "online", &#x9; "parametergroups" null, &#x9; "metainfos" { &#x9; "alexa >alexa live updates" "false", &#x9; "monitoring >monitorable" "true", &#x9; "teachin >group displayname" "test", &#x9; "bsc >short info" "fsb14", &#x9; "metainfo >id" "adevice#b9f09ef8 3c3f 459e 841f 66bdaedff183", &#x9; "teachin >reference id" "enocean eltako fsb14", &#x9; "eoap >activated" "true", &#x9; "teachin >transmission id" "default=4291820288", &#x9; "lastmodified" "1636543466499", &#x9; "eoap >alarm" "false" &#x9; } &#x9;} } einzelner kanalwert acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183/jalousie/value { "nodeid" "acdbda59e9cf", "eventid" "igu16ksjlsu6m80v", "timestamp" 1636543467229, "value" "29 0" } raw kanalwert acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183/jalousie/value/raw 29 0 meta informationen acdbda59e9cf/things/b9f09ef8 3c3f 459e 841f 66bdaedff183/metainfos { "nodeid" "acdbda59e9cf", "eventid" "igu16ksjlsu6m80v", "timestamp" 1636543467229, "metainfos" { "alexa >alexa live updates" "false", "monitoring >monitorable" "true", "teachin >group displayname" "test", "bsc >short info" "fsb14", "metainfo >id" "adevice#b9f09ef8 3c3f 459e 841f 66bdaedff183", "teachin >reference id" "enocean eltako fsb14", "eoap >activated" "true", "teachin >transmission id" "default=4291820288", "lastmodified" "1636543466499", "eoap >alarm" "false" } } kommando topic über das kommando topic, welches in der konfiguration als "command topic" hinterlegt ist, können verschiedene befehle an das gateway gesendet werden ein kommando besteht immer aus dem kommando type sowie einigen parametern die parameter sind immer strings kommando type parameter mögliche werte erforderlich beschreibung change value thingid x eindeutige thing id des gerätes channelid x die eindeutige channel id es kanals welcher geschaltet werden soll newvalue x der neue wert welcher gesetzt werden soll auto pairing pairingenabled true false x gibt an ob das automatische anlenen aktiviert werden soll ist es bereits aktiviert passiert nicht weiter targetgrpid positiver wert x die id der gruppe, zu welcher neue geräte hinzugefügt werden sollen sind keine gruppen vorhanden, muss 0 angegeben werden die geräte werden dadurch ohne gruppenzuordnung angelegt enabledforsec positiver wert x zeit in sekunden bis der anlernmodus automatisch wieder ausgeschaltet wird ein wert von 0 deaktiviert die automatische abschaltung delete thing thingid x eindeutige id des thing change parametervalue thingid x eindeutige id des thing channelid x die eindeutige channel id es parameterkanals welcher geschaltet werden soll newvalue x der neue wert welcher gesetzt werden soll beispiel kommandos change value { "type" "change value", "parameters" { "thingid" "e173aac8 820d 4eaf b862 fb6f415b34d0", "channelid" "dimmer", "newvalue" "73" } } auto pairing { "type" "auto pairing", "parameters" { "pairingenabled" "true", "targetgrpid" "0", "enabledforsec" "90" } } delete thing { "type" "delete thing", "parameters" { "thingid" "e173aac8 820d 4eaf b862 fb6f415b34d0" } } change parametervalue { "type" "change parametervalue", "parameters" { "thingid" "e173aac8 820d 4eaf b862 fb6f415b34d0", "channelid" "2718db30 21c5 4d63 879b c6392ae04c6d", "newvalue" "false" } } status topic über das status topic, welches in der konfiguration als "status topic" hinterlegt ist, werden statusinformationen zum gateway übertragen insbesondere der onlinestatus hat hier besondere bedeutung dieser gibt an ob das gateway mit dem mqtt broker verbunden ist falls das gateway nicht mit dem broker verbunden ist, wird die event id der statusnachricht auf "disconnect" gesetzt und der timestamp auf 1 dies kann innerhalb von 24 stunden mehrfach auftreten! status objekt feld datentype beschreibung version string die aktuelle software version des gateways connected boolean status ob das gateway aktuell verbunden ist metainfos objekt ein objekt mit zusätzlichen informationen jedes feld ist vom datentype string, der feldname fungiert als "key" um eine map abzubilden status objekt beispiele verbunden { &#x9;"nodeid" "acdbda59eb17", &#x9;"eventid" "oi2advu5fmptvmk6", &#x9;"timestamp" 1649843546682, &#x9;"version" "3 3 1", &#x9;"connected" true, &#x9;"metainfos" {} } getrennt { &#x9;"nodeid" "acdbda59eb17", &#x9;"eventid" "disconnect", &#x9;"timestamp" 1, &#x9;"version" "3 3 1", &#x9;"connected" false, &#x9;"metainfos" {} } benachrichtigungs topic über das benachrichtigungs topic, welches in der konfiguration als "notification topic" hinterlegt ist, werden push benachrichtigungen übertragen die push benachrichtigungen müssen für den unter "user" ausgewählten benutzer bestimmte sein benachrichtigungs objekt feld datentype beschreibung msg string der text der push benachrichtigung es können \n für zeilenumbrüche enthalten sein beispiel benachrichtigungs objekt benachrichtigungs objekt { &#x9;"nodeid" "acdbda59eb17", &#x9;"eventid" "ce40i927ri52lcm7", &#x9;"timestamp" 1649843666187, &#x9;"msg" "admin\@smartnode dies ist eine testnachricht\n\nder test wurde erfolgreich durchgeführt\nzeilenumbrüche sind erlaubt" }