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: