+ This module is an MQTT bridge, which simultaneously collects data from several FHEM devices
+ and passes their readings via MQTT or set rreadings from the incoming MQTT messages or executes them
+ as a 'set' command on the configured FHEM device.
+
An MQTT device is needed as IODev.
+
The (minimal) configuration of the bridge itself is basically very simple.
+ +Definition:
+In the simplest case, two lines are enough:
+defmod mqttGeneric MQTT_GENERIC_BRIDGE [prefix] [devspec]
+ attr mqttGeneric IODev
All parameters in the define are optional.
+The first parameter is a prefix for the control attributes on which the devices to be + monitored (see above) are configured. Default value is 'mqtt'. + If this is e.g. redefined as 'hugo', the control attributes are named hugoPublish etc. +
+The second parameter ('devspec') allows to minimize the number of devices to be monitored + (otherwise all devices will be monitored, which may cost performance). + see devspec
+get:
+version
+ Displays module version.
devlist [<name (regex)>]
+ Returns list of names of devices monitored by this bridge whose names correspond to the optional regular expression.
+ If no expression provided, all devices are listed.
+
devinfo [<name (regex)>]
+ Returns a list of monitored devices whose names correspond to the optional regular expression.
+ If no expression provided, all devices are listed.
+ In addition, the topics used in 'publish' and 'subscribe' are displayed including the corresponding read-in names.
+
readings:
+device-count
+ Number of monitored devices
incoming-count
+ Number of incoming messages
outgoing-count
+ Number of outgoing messages
updated-reading-count
+ Number of updated readings
updated-set-count
+ Number of executed 'set' commands
transmission-state
+ last transmission state
Attributes:
+the following attributes are supported:
+IODev
+ This attribute is mandatory and must contain the name of a functioning MQTT module instance. MQTT2_SERVER module is not supported.
disable
+ Value '1' deactivates the bridge
Example:
+ attr <dev> disable 1
+
globalDefaults
+ Defines defaults. These are used in the case where suitable values are not defined in the respective device.
+ see mqttDefaults.
+
globalAlias
+ Defines aliases. These are used in the case where suitable values are not defined in the respective device.
+ see mqttAlias.
+
globalPublish
+ Defines topics / flags for MQTT transmission. These are used if there are no suitable values in the respective device.
+ see mqttPublish.
+
For the monitored devices, a list of the possible attributes is automatically extended by several further entries.
+ They all begin with a prefix previously defined in the bridge. These attributes are used to configure the actual MQTT mapping.
+ By default, the following attribute names are used: mqttDefaults, mqttAlias, mqttPublish, mqttSubscribe.
+
The meaning of these attributes is explained below.
+
mqttDefaults
+ Here is a list of "key = value" pairs defined. The following keys are possible:
+
Example:
+ attr <dev> mqttDefaults base={"/TEST/$device"} pub:qos=0 sub:qos=2 retain=0
mqttAlias
+ This attribute allows readings to be mapped to MQTT topic under a different name.
+ Usually only useful if topic definitions are Perl expressions with corresponding variables.
+ Again, 'pub:' and 'sub:' prefixes are supported
+ (For 'subscribe', the mapping will be reversed).
+
Alias for 'subscribe' is currently not implemented!
Example:
+ attr <dev> mqttAlias pub:temperature=temp
mqttPublish
+ Specific topics can be defined and assigned to the Readings(Format: <reading>:topic=<topic>).
+ Furthermore, these can be individually provided with 'qos' and 'retain' flags.
+ Topics can also be defined as Perl expression with variables($reading, $device, $name, $base).
+ Values for several readings can also be defined together, separated with '|'.
+ If a '*' is used instead of a read name, this definition applies to all readings for which no explicit information was provided.
+ It is also possible to define expressions (reading: expression = ...).
+ The expressions could usefully change variables ($value, $topic, $qos, $retain, $message), or return a value of != undef.
+ The return value is used as a new message value, the changed variables have priority.
+ If the return value is undef, setting / execution is suppressed.
+ If the return is a hash (topic and stopic only), its key values are used as the topic, and the contents of the messages are the values from the hash.
Examples:
+ attr <dev> mqttPublish temperature:topic={"$base/$name"} temperature:qos=1 temperature:retain=0 *:topic={"$base/$name"} humidity:topic=/TEST/Feuchte
+ attr <dev> mqttPublish temperature|humidity:topic={"$base/$name"} temperature|humidity:qos=1 temperature|humidity:retain=0
+ attr <dev> mqttPublish *:topic={"$base/$name"} *:qos=2 *:retain=0
+ attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={"message: $value"}
+ attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={$value="message: $value"}
+ attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={"/TEST/Topic1"=>"$message", "/TEST/Topic2"=>"message: $message"}
mqttSubscribe
+ This attribute configured receiving the MQTT messages and the corresponding reactions.
+ The configuration is similar to that for the 'mqttPublish' attribute.
+ Topics can be defined for setting readings ('topic') and calls to the 'set' command on the device ('stopic').
+ The result can be modified before setting the reading or executing of 'set' on the device with additional Perl expressions ('expression').
+ The following variables are available in the expression: $device, $reading, $message (initially equal to $value).
+ The expression can either change variable $value, or return a value != undef.
+ Redefinition of the variable has priority. If the return value is undef, then the set / execute is suppressed (unless $value has a new value).
+ If the return is a hash (only for 'topic' and 'stopic'),
+ then its key values are used as readings or 'set' parameters,
+ the values to be set are the values from the hash.
+ Furthermore the attribute 'qos' can be specified ('retain' does not make sense here).
+ Topic definition can include MQTT wildcards (+ and #).
+ If the reading name is defined with a '*' at the beginning, it will act as a wildcard.
+ The actual name of the reading (and possibly of the device) is defined by variables from the topic
+ ($device (only for global definition in the bridge), $reading, $name).
+ In the topic these variables act as wildcards, of course only makes sense, if reading-name is not defined (so start with '*').
+ The variable $name, unlike $reading, may be affected by the aliases defined in 'mqttAlias'. Also use of $base is allowed.
+ When using 'stopic', the 'set' command is executed as 'set <dev> <reading> <value>'.
+ For something like 'set <dev> <value>' 'state' should be used as reading-name.
Examples:
+ attr <dev> mqttSubscribe temperature:topic=/TEST/temperature test:qos=0 *:topic={"/TEST/$reading/value"}
+ attr <dev> mqttSubscribe desired-temperature:stopic={"/TEST/temperature/set"}
+ attr <dev> mqttSubscribe state:stopic={"/TEST/light/set"} state:expression={...}
+ attr <dev> mqttSubscribe state:stopic={"/TEST/light/set"} state:expression={$value="x"}
+ attr <dev> mqttSubscribe state:stopic={"/TEST/light/set"} state:expression={"R1"=>$value, "R2"=>"Val: $value", "R3"=>"x"}
+
mqttDisable
+ If this attribute is set in a device, this device is excluded from sending or receiving the readings.
Examples
+ +Bridge for any devices with the standard prefix:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE
+
+ attr mqttGeneric IODev mqtt
Bridge with the prefix 'mqtt' for three specific devices:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE mqtt sensor1,sensor2,sensor3
+ attr mqttGeneric IODev mqtt
Bridge for all devices in a certain room:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE mqtt room=Wohnzimmer
+ attr mqttGeneric IODev mqtt
Simple configuration of a temperature sensor:
+ defmod sensor XXX
+ attr sensor mqttPublish temperature:topic=/haus/sensor/temperature
Send all readings of a sensor (with their names as they are) via MQTT:
+ defmod sensor XXX
+ attr sensor mqttPublish *:topic={"/sensor/$reading"}
Topic definition with shared part in 'base' variable:
+ defmod sensor XXX
+ attr sensor mqttDefaults base={"/$device/$reading"}
+ attr sensor mqttPublish *:topic={$base}
Topic definition only for certain readings with renaming (alias):
+ defmod sensor XXX
+ attr sensor mqttAlias temperature=temp humidity=hum
+ attr sensor mqttDefaults base={"/$device/$name"}
+ attr sensor mqttPublish temperature:topic={$base} humidity:topic={$base}
Example of a central configuration in the bridge for all devices that have Reading named 'temperature':
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE
+ attr mqttGeneric IODev mqtt
+ attr mqttGeneric defaults sub:qos=2 pub:qos=0 retain=0
+ attr mqttGeneric publish temperature:topic={"/haus/$device/$reading"}
+
Example of a central configuration in the bridge for all devices:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE
+ attr mqttGeneric IODev mqtt
+ attr mqttGeneric defaults sub:qos=2 pub:qos=0 retain=0
+ attr mqttGeneric publish *:topic={"/haus/$device/$reading"}
Limitations:
+ +
+ Dieses Modul ist eine MQTT-Bridge, die gleichzeitig mehrere FHEM-Devices erfasst und deren Readings
+ per MQTT weiter gibt bzw. aus den eintreffenden MQTT-Nachrichten befuellt oder diese als 'set'-Befehl
+ an dem konfigurierten FHEM-Geraet ausfuert.
+
Es wird ein MQTT-Geraet als IODev benoetigt.
+
Die (minimale) Konfiguration der Bridge selbst ist grundsaetzlich sehr einfach.
+ +Definition:
+Im einfachsten Fall reichen schon zwei Zeilen:
+defmod mqttGeneric MQTT_GENERIC_BRIDGE [prefix] [devspec]
+ attr mqttGeneric IODev
Alle Parameter im Define sind optional.
+Der erste ist ein Prefix fuer die Steuerattribute, worueber die zu ueberwachende Geraete (s.u.) + konfiguriert werden. Defaultwert ist 'mqtt'. + Wird dieser z.B. als 'hugo' redefiniert, heissen die Steuerungsattribute entsprechend hugoPublish etc.
+Der zweite Parameter ('devspec') erlaubt die Menge der zu ueberwachenden Geraeten + zu begrenzen (sonst werden einfach alle ueberwacht, was jedoch Performance kosten kann). + s.a. devspec
+get:
+version
+ Zeigt Modulversion an.
devlist [<name (regex)>]
+ Liefert Liste der Namen der von dieser Bridge ueberwachten Geraete deren Namen zu dem optionalen regulaerem Ausdruck entsprechen.
+ Fehlt der Ausdruck, werden alle Geraete aufgelistet.
+
devinfo [<name (regex)>]
+ Gibt eine Liste der ueberwachten Geraete aus, deren Namen zu dem optionalen regulaerem Ausdruck entsprechen.
+ Fehlt der Ausdruck, werden alle Geraete aufgelistet. Zusätzlich werden bei 'publish' und 'subscribe'
+ verwendete Topics angezeigt incl. der entsprechenden Readinsnamen.
readings:
+device-count
+ Anzahl der ueberwachten Geraete
incoming-count
+ Anzahl eingehenden Nachrichten
outgoing-count
+ Anzahl ausgehende Nachrichten
updated-reading-count
+ Anzahl der gesetzten Readings
updated-set-count
+ Anzahl der abgesetzten 'set' Befehle
transmission-state
+ letze Uebertragunsart
Attribute:
+folgende Attribute werden unterstuetzt:
+IODev
+ Dieses Attribut ist obligatorisch und muss den Namen einer funktionierenden MQTT-Modulinstanz enthalten.
+ Modul MQTT2_SERVER wird nicht unterstuetzt.
disable
+ Wert 1 deaktiviert die Bridge
Beispiel:
+ attr <dev> disable 1
+
globalDefaults
+ Definiert Defaults. Diese greifen in dem Fall, wenn in dem jeweiligen Geraet definierte Werte nicht zutreffen.
+ s.a. mqttDefaults.
+
globalAlias
+ Definiert Alias. Diese greifen in dem Fall, wenn in dem jeweiligen Geraet definierte Werte nicht zutreffen.
+ s.a. mqttAlias.
+
globalPublish
+ Definiert Topics/Flags fuer die Uebertragung per MQTT. Diese werden angewendet, falls in dem jeweiligen Geraet
+ definierte Werte nicht greifen oder nicht vorhanden sind.
+ s.a. mqttPublish.
+
Fuer die ueberwachten Geraete wird eine Liste der moeglichen Attribute automatisch um mehrere weitere Eintraege ergaenzt.
+ Sie fangen alle mit vorher in der Bridge definiertem Prefix an. Ueber diese Attribute wird die eigentliche MQTT-Anbindung konfiguriert.
+ Defaultmaessig werden folgende Attributnamen verwendet: mqttDefaults, mqttAlias, mqttPublish, mqttSubscribe.
+
Die Bedeutung dieser Attribute wird im Folgenden erklaert.
+
mqttDefaults
+ Hier wird eine Liste der "key=value"-Paare erwartet. Folgende Keys sind dabei moeglich:
+
Beispiel:
+ attr <dev> mqttDefaults base={"/TEST/$device"} pub:qos=0 sub:qos=2 retain=0
mqttAlias
+ Dieses Attribut ermoeglicht Readings unter einem anderen Namen auf MQTT-Topic zu mappen.
+ Eigentlich nur sinnvoll, wenn Topicdefinitionen Perl-Expressions mit entsprechenden Variablen sind.
+ Auch hier werden 'pub:' und 'sub:' Prefixe unterstuetzt (fuer 'subscribe' gilt das Mapping quasi umgekehrt).
+
Alias fuer subscribe ist derzeit nicht implementiert!
Beispiel:
+ attr <dev> mqttAlias pub:temperature=temp
mqttPublish
+ Hier werden konkrette Topics definiet und den Readings zugeordnet (Format: <reading>:topic=<topic>).
+ Weiterhin koennen diese einzeln mit 'qos'- und 'retain'-Flags versehen werden.
+ Topics koennen auch als Perl-Expression mit Variablen definiert werden ($reading, $device, $name, $base).
+ Werte fuer mehrere Readings koennen auch gemeinsam gleichzeitig definiert werden,
+ indem sie, mittels '|' getrennt, zusammen angegeben werden.
+ Wird anstatt eines Readingsnamen ein '*' verwendet, gilt diese Definition fuer alle Readings,
+ fuer die keine explizite Angaben gemacht wurden.
+ Es koennen auch Expressions (reading:expression=...) definiert werden.
+ Die Expressions koenne sinnvollerweise entweder Variablen ($value, $topic, $qos, $retain, $message) veraendern, oder einen Wert != undef zurrueckgeben.
+ Der Rueckhgabe wert wird als neue Nachricht-Value verwendet, die Aenderung der Variablen hat dabei jedoch Vorrang.
+ Ist der Rueckgabewert undef, dann wird das Setzen/Ausfuehren unterbunden.
+ Ist die Rueckgabe ein Hash (nur 'topic' und 'stopic'), werden seine Schluesselwerte als Topic verwendet,
+ die Inhalte der Nachrichten sind entsprechend die Werte aus dem Hash.
Beispiele:
+ attr <dev> mqttPublish temperature:topic={"$base/$name"} temperature:qos=1 temperature:retain=0 *:topic={"$base/$name"} humidity:topic=/TEST/Feuchte
+ attr <dev> mqttPublish temperature|humidity:topic={"$base/$name"} temperature|humidity:qos=1 temperature|humidity:retain=0
+ attr <dev> mqttPublish *:topic={"$base/$name"} *:qos=2 *:retain=0
+ attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={"message: $value"}
+ attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={$value="message: $value"}
+ attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={"/TEST/Topic1"=>"$message", "/TEST/Topic2"=>"message: $message"}
mqttSubscribe
+ Dieses Attribut konfiguriert das Empfangen der MQTT-Nachrichten und die entsprechenden Reaktionen darauf.
+ Die Konfiguration ist aehnlich der fuer das 'mqttPublish'-Attribut. Es koennen Topics fuer das Setzen von Readings ('topic') und
+ Aufrufe von 'set'-Befehl an dem Geraet ('stopic') definiert werden.
+ Mit Hilfe von zusaetzlichen auszufuehrenden Perl-Expressions ('expression') kann das Ergebnis vor dem Setzen/Ausfueren noch beeinflusst werden.
+ In der Expression sind folgende Variablen verfügbar: $device, $reading, $message (initial gleich $value).
+ Die Expression kann dabei entweder Variable $value veraendern, oder einen Wert != undef zurueckgeben. Redefinition der Variable hat Vorrang.
+ Ist der Rueckgabewert undef, dann wird das Setzen/Ausfuehren unterbunden (es sei denn, $value hat einen neuen Wert).
+ Ist die Rueckgabe ein Hash (nur fuer 'topic' und 'stopic'), dann werden seine Schluesselwerte als Readingsnamen bzw. 'set'-Parameter verwendet,
+ die zu setzenden Werte sind entsprechend die Werte aus dem Hash.
+ Weiterhin kann das Attribut 'qos' angegeben werden ('retain' macht dagegen keinen Sinn).
+ In der Topic-Definition koennen MQTT-Wildcards (+ und #) verwendet werden.
+ Falls der Reading-Name mit einem '*'-Zeichen am Anfang definiert wird, gilt dieser als 'Platzhalter'.
+ Der tatsaechliche Name der Reading (und ggf. des Geraetes) wird dabei durch Variablen aus dem Topic
+ definiert ($device (nur fuer globale Definition in der Bridge), $reading, $name).
+ Im Topic wirken diese Variablen als Wildcards, macht natuerlich nur Sinn, wenn Reading-Name auch nicht fest definiert ist (also faengt mit '*' an).
+ Die Variable $name wird im Unterschied zu $reading ggf. ueber die in 'mqttAlias' definierten Aliases beeinflusst.
+ Auch Verwendung von $base ist erlaubt.
+ Bei Verwendung von 'stopic' wird das 'set'-Befehl als 'set <dev> <reading> <value>' ausgefuert.
+ Fuer ein 'set <dev> <value>' soll als Reading-Name 'state' verwendet werden.
Beispiele:
+ attr <dev> mqttSubscribe temperature:topic=/TEST/temperature test:qos=0 *:topic={"/TEST/$reading/value"}
+ attr <dev> mqttSubscribe desired-temperature:stopic={"/TEST/temperature/set"}
+ attr <dev> mqttSubscribe state:stopic={"/TEST/light/set"} state:expression={...}
+ attr <dev> mqttSubscribe state:stopic={"/TEST/light/set"} state:expression={$value="x"}
+ attr <dev> mqttSubscribe state:stopic={"/TEST/light/set"} state:expression={"R1"=>$value, "R2"=>"Val: $value", "R3"=>"x"}
+
mqttDisable
+ Wird dieses Attribut in einem Geraet gesetzt, wird dieses Geraet vom Versand bzw. Empfang der Readingswerten ausgeschlossen.
Beispiele
+ +Bridge fuer alle moeglichen Geraete mit dem Standardprefix:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE
+
+ attr mqttGeneric IODev mqtt
Bridge mit dem Prefix 'mqtt' fuer drei bestimmte Geraete:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE mqtt sensor1,sensor2,sensor3
+ attr mqttGeneric IODev mqtt
Bridge fuer alle Geraete in einem bestimmten Raum:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE mqtt room=Wohnzimmer
+ attr mqttGeneric IODev mqtt
Einfachste Konfiguration eines Temperatursensors:
+ defmod sensor XXX
+ attr sensor mqttPublish temperature:topic=/haus/sensor/temperature
Alle Readings eines Sensors (mit ihren Namen wie sie sind) per MQTT versenden:
+ defmod sensor XXX
+ attr sensor mqttPublish *:topic={"/sensor/$reading"}
Topicsdefinition mit Auslagerung von dem gemeinsamen Teilnamen in 'base'-Variable:
+ defmod sensor XXX
+ attr sensor mqttDefaults base={"/$device/$reading"}
+ attr sensor mqttPublish *:topic={$base}
Topicsdefinition nur fuer bestimmte Readings mit deren gleichzeitigen Umbennenung (Alias):
+ defmod sensor XXX
+ attr sensor mqttAlias temperature=temp humidity=hum
+ attr sensor mqttDefaults base={"/$device/$name"}
+ attr sensor mqttPublish temperature:topic={$base} humidity:topic={$base}
Beispiel fuer eine zentralle Konfiguration in der Bridge fuer alle Devices, die Reading 'temperature' besitzen:
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE
+ attr mqttGeneric IODev mqtt
+ attr mqttGeneric defaults sub:qos=2 pub:qos=0 retain=0
+ attr mqttGeneric publish temperature:topic={"/haus/$device/$reading"}
+
Beispiel fuer eine zentralle Konfiguration in der Bridge fuer alle Devices
+ (wegen einer schlechte uebersicht und einer unnoetig grossen Menge eher nicht zu empfehlen):
+ defmod mqttGeneric MQTT_GENERIC_BRIDGE
+ attr mqttGeneric IODev mqtt
+ attr mqttGeneric defaults sub:qos=2 pub:qos=0 retain=0
+ attr mqttGeneric publish *:topic={"/haus/$device/$reading"}
Einschraenkungen:
+ +