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. + If this is e.g. redefined as mqttGB1_, the control attributes are named mqttGB1_Publish 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). - Example for devspec: 'TYPE=dummy' or 'dummy1,dummy2'. With comma separated list no spaces must be used! - see devspec
+ Example for devspec: 'TYPE=dummy' or 'dummy1,dummy2'. Following the general rules for devspec, a comma separated list must not contain any whitespaces! @@ -3044,7 +3046,8 @@ sub onmessage($$$) {Attributes:
the following attributes are supported:
+The MQTT_GENERIC_BRIDGE device itself supports the following attributes:
+IODev
This attribute is mandatory and must contain the name of a functioning MQTT-IO module instance. MQTT, MQTT2_CLIENT and MQTT2_SERVER are supported.
globalDefaults
Defines defaults. These are used in the case where suitable values are not defined in the respective device.
see mqttDefaults.
+
Example:
+ attr <dev> sub:base=FHEM/set pub:base=FHEM
Remark:
+ Setting this attribute will publish any reading value from any device matching the devspec. In most cases this may not be the intented behaviour, setting accurate attributes to the subordinated devices should be preferred.
+
forceNEXT
Only relevant for MQTT2_CLIENT or MQTT2_SERVER as IODev. If set to 1, MQTT_GENERIC_BRIDGE will forward incoming messages also to further client modules like MQTT2_DEVICE, even if the topic matches to one of the subscriptions of the controlled devices. By default, these messages will not be forwarded for better compability with autocreate feature on MQTT2_DEVICE. See also clientOrder attribute in MQTT2 IO-type commandrefs; setting this in one instance of MQTT_GENERIC _BRIDGE might affect others, too.
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.
+
For the monitored devices, a list of the possible attributes is automatically extended by several further entries.
+ Their names all start with the 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:
@@ -3135,17 +3144,17 @@ sub onmessage($$$) {
to only send or receive only (as far asappropriate).
Values for 'qos' and 'retain' are only used if no explicit information has been given about it for a specific topic.
Example:
- attr <dev> mqttDefaults base={"/TEST/$device"} pub:qos=0 sub:qos=2 retain=0
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.
+ Usually only useful if topic definitions are Perl expressions with corresponding variables or to achieve somehow standardized topic structures.
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).
+ Topics can also be defined as Perl expression with variables ($reading, $device, $name, $base or additional variables as provided in mqttDefaults).
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.
+ If a '*' is used instead of a reading name, this definition applies to all readings for which no explicit information was provided.
Topic can also be written as a 'readings-topic'.
Attributes can also be sent ("atopic" or "attr-topic").
- If you wont to send several messages (meaningfully to different topics) for an event, the respective definitions must be defined by appending
+ If you want to send several messages (e.g. to different topics) for an event, the respective definitions must be defined by appending
unique suffixes (separated from the reading name by a !-sign): reading!1:topic=... reading!2:topic=....
It is possible to define expressions (reading: expression = ...).
- The expressions could usefully change variables ($value, $topic, $qos, $retain, $message, $uid), or return a value of != undef.
+ The expressions could be used to change variables ($value, $topic, $qos, $retain, $message, $uid), 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 value is undef, setting / execution is suppressed.
If the return is a hash (topic only), its key values are used as the topic, and the contents of the messages are the values from the hash.
Option 'resendOnConnect' allows to save the messages, if the bridge is not connected to the MQTT server. @@ -3194,7 +3203,7 @@ sub onmessage($$$) {
mqttSubscribe
- This attribute configured receiving the MQTT messages and the corresponding reactions.
+ This attribute configures the device to receive MQTT messages and execute corresponding actions.
The configuration is similar to that for the 'mqttPublish' attribute.
Topics can be defined for setting readings ('topic' or 'readings-topic') and calls to the 'set' command on the device ('stopic' or 'set-topic').
Also attributes can be set ('atopic' or 'attr-topic').
@@ -3211,21 +3220,20 @@ sub onmessage($$$) {
Several definitions with '*' should also be used as: *1:topic = ... *2:topic = ...
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
+ In the topic these variables act as wildcards, of course only makes sense, if reading name is not defined
(so start with '*', or multiple names separated 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.
The often requested JSON support can be easily realized with the help of 'expression'. - An already existing method in fhem.pl (json2nameValue) works well. The parameter should be '$message'.
+ For something like 'set <dev> <value>' 'state' should be used as reading name. +If JSON support is needed: Use the json2nameValue() method provided by fhem.pl in 'expression' with '$message' as parameter.
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"}
- attr <dev> mqttSubscribe verbose:atopic={"/TEST/light/verbose"}
- attr <dev> mqttSubscribe json:topic=/XTEST/json json:expression={json2nameValue($message)}
+ 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"}
+ attr <dev> mqttSubscribe verbose:atopic={"TEST/light/verbose"}
+ attr <dev> mqttSubscribe json:topic=XTEST/json json:expression={json2nameValue($message)}
Examples
@@ -3280,21 +3288,21 @@ sub onmessage($$$) {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 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 mqttDefaults base={"$device/$name"}
attr sensor mqttPublish temperature:topic={"$base"} humidity:topic={"$base"}
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"}
+ attr mqttGeneric publish temperature:topic={"haus/$device/$reading"}
@@ -3323,7 +3331,7 @@ sub onmessage($$$) {
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"}
+ attr mqttGeneric publish *:topic={"haus/$device/$reading"} defmod mqttGeneric MQTT_GENERIC_BRIDGE [prefix] [devspec,[devspec]]
attr mqttGeneric IODev
Alle Parameter im Define sind optional.
-Der erste ist ein Prefix für die Steuerattribute, worüber die zu ueberwachende Geraete (s.u.) +
Der erste ist ein Prefix für die Steuerattribute, worüber die zu überwachende Geräte (s.u.) konfiguriert werden. Defaultwert ist 'mqtt'. Wird dieser z.B. als 'mqttGB1_' festgelegt, heißen die Steuerungsattribute entsprechend mqttGB1_Publish etc.
-Der zweite Parameter ('devspec') erlaubt die Menge der zu überwachenden Geraeten +
Der zweite Parameter ('devspec') erlaubt die Menge der zu überwachenden Geräten zu begrenzen (sonst werden einfach alle überwacht, was jedoch Performance kosten kann). - Beispiel fuer devspec: 'TYPE=dummy' oder 'dummy1,dummy2'. Bei kommaseparierten Liste dürfen keine Leerzeichen verwendet werden! - s.a. devspec
+ Beispiel für devspec: 'TYPE=dummy' oder 'dummy1,dummy2'. Es gelten die allgemeinen Regeln für devspec, bei kommaseparierter Liste sind also keine Leerzeichen erlaubt! + + @@ -3392,8 +3401,8 @@ sub onmessage($$$) {devlist [<name (regex)>]
- Liefert Liste der Namen der von dieser Bridge überwachten Geräte deren Namen zu dem optionalen regulaerem Ausdruck entsprechen.
- Fehlt der Ausdruck, werden alle Geraete aufgelistet.
+ Liefert Liste der Namen der von dieser Bridge überwachten Geräte deren Namen zu dem optionalen regulärem Ausdruck entsprechen.
+ Fehlt der Ausdruck, werden alle Geräte aufgelistet.
globalPublish
- Definiert Topics/Flags fuer die Uebertragung per MQTT. Diese werden angewendet, falls in dem jeweiligen Geraet
+ Definiert Topics/Flags für die Übertragung per MQTT. Diese werden angewendet, falls in dem jeweiligen Gerät
definierte Werte nicht greifen oder nicht vorhanden sind.
s.a. mqttPublish.
Beispiel:
attr <dev> globalTypeExclude MQTT MQTT_GENERIC_BRIDGE:* MQTT_BRIDGE:transmission-state *:baseID
globalDeviceExclude
- Definiert Geraetenamen und Readings, die nicht uebertragen werden.
- Werte können getrennt fuer jede Richtung (publish oder subscribe) vorangestellte Prefixe 'pub:' und 'sub:' angegeben werden.
- Ein einzelner Wert bedeutet, dass ein Geraet mit diesem Namen komplett ignoriert wird (also fuer alle seine Readings und beide Richtungen).
+ Definiert Gerätenamen und Readings, die nicht übertragen werden.
+ Werte können getrennt für jede Richtung (publish oder subscribe) vorangestellte Prefixe 'pub:' und 'sub:' angegeben werden.
+ Ein einzelner Wert bedeutet, dass ein Gerät mit diesem Namen komplett ignoriert wird (also für alle seine Readings und beide Richtungen).
Durch ein Doppelpunkt getrennte Paare werden als [sub:|pub:]Device:Reading interptretiert.
- Das bedeutet, dass an dem gegebenen Geraet die genannte Readings nicht uebertragen wird.
Beispiel:
attr <dev> globalDeviceExclude Test Bridge:transmission-state
mqttDefaults
Hier wird eine Liste der "key=value"-Paare erwartet. Folgende Keys sind dabei möglich:
Beispiel:
attr <dev> mqttDefaults base={"TEST/$device"} pub:qos=0 sub:qos=2 retain=0
mqttAlias
Dieses Attribut ermöglicht Readings unter einem anderen Namen auf MQTT-Topic zu mappen.
- Eigentlich nur sinnvoll, wenn Topicdefinitionen Perl-Expressions mit entsprechenden Variablen sind.
+ Dies ist dann sinnvoll, wenn entweder Topicdefinitionen Perl-Expressions mit entsprechenden Variablen sind oder der Alias dazu dient, aus MQTT-Sicht standardisierte Readingnamen zu ermöglichen.
Auch hier werden 'pub:' und 'sub:' Prefixe unterstützt (für 'subscribe' gilt das Mapping quasi umgekehrt).
-
Alias fuer subscribe ist derzeit nicht implementiert!
Beispiel:
- attr <dev> mqttAlias pub:temperature=temp
attr <dev> mqttAlias pub:temperature=temp
temperature ist dabei der Name des Readings in FHEM.
Option 'resendOnConnect' erlaubt eine Speicherung der Nachrichten, @@ -3587,7 +3595,7 @@ sub onmessage($$$) {
Beispiele:
@@ -3614,22 +3622,21 @@ sub onmessage($$$) {
In der Expression sind die folgenden Variablen verfügbar: $device, $reading, $message (initial gleich $value).
Die Expression kann dabei entweder die Variable $value verändern, oder einen Wert != undef zurückgeben. Redefinition der Variable hat Vorrang.
Ist der Rückgabewert undef, dann wird das Setzen/Ausführen unterbunden (es sei denn, $value hat einen neuen Wert).
- Ist die Rückgabe ein Hash (nur fuer 'topic' und 'stopic'), dann werden seine Schlüsselwerte als Readingsnamen bzw. 'set'-Parameter verwendet,
+ Ist die Rückgabe ein Hash (nur für 'topic' und 'stopic'), dann werden seine Schlüsselwerte als Readingsnamen bzw. 'set'-Parameter verwendet,
die zu setzenden Werte sind entsprechend den Werten aus dem Hash.
Weiterhin kann das Attribut 'qos' angegeben werden ('retain' macht dagegen keinen Sinn).
In der Topic-Definition können MQTT-Wildcards (+ und #) verwendet werden.
Falls der Reading-Name mit einem '*'-Zeichen am Anfang definiert wird, gilt dieser als 'Platzhalter'.
Mehrere Definitionen mit '*' sollten somit z.B. in folgender Form verwendet werden: *1:topic=... *2:topic=...
- Der tatsaechliche Name des Readings (und ggf. des Geraetes) wird dabei durch Variablen aus dem Topic
+ Der tatsächliche Name des Readings (und ggf. des Gerätes) wird dabei durch Variablen aus dem Topic
definiert ($device (nur für globale Definition in der Bridge), $reading, $name).
Im Topic wirken diese Variablen als Wildcards, was evtl. dann sinnvoll ist, wenn der Reading-Name nicht fest definiert ist
(also mit '*' anfängt, oder mehrere Namen durch '|' getrennt definiert werden).
Die Variable $name wird im Unterschied zu $reading ggf. über die in 'mqttAlias' definierten Aliase beeinflusst.
Auch Verwendung von $base ist erlaubt.
- Bei Verwendung von 'stopic' wird der 'set'-Befehl als 'set <dev> <reading> <value>' ausgefuehrt.
+ Bei Verwendung von 'stopic' wird der 'set'-Befehl als 'set <dev> <reading> <value>' ausgeführt.
Um den set-Befehl direkt am Device ohne Angabe eines Readingnamens auszuführen (also 'set <dev> <value>') muss als Reading-Name 'state' verwendet werden.
Um Nachrichten im JSON-Format zu empfangen, kann mit Hilfe von 'expression' direkt die in fhem.pl bereitgestellte Funktion json2nameValue aufgerufen werden, als Parameter ist $message anzugeben.
-Um Nachrichten im JSON-Format zu empfangen, kann mit Hilfe von 'expression' direkt die in fhem.pl bereitgestellte Funktion json2nameValue() aufgerufen werden, als Parameter ist $message anzugeben.
Einige Beispiele: Bridge mit dem Prefix 'mqttSensors' fuer drei bestimmte Geräte: Bridge mit dem Prefix 'mqttSensors' für drei bestimmte Geräte:
attr <dev> mqttSubscribe temperature:topic=TEST/temperature test:qos=0 *:topic={"TEST/$reading/value"}
attr <dev> mqttSubscribe desired-temperature:stopic={"TEST/temperature/set"}
@@ -3678,7 +3685,7 @@ sub onmessage($$$) {
+
defmod mqttGeneric MQTT_GENERIC_BRIDGE mqttSensors sensor1,sensor2,sensor3
attr mqttGeneric IODev mqtt