notify

notify
Zweck / Funktion
	Ausführung von Anweisung(en) als Reaktion auf Ereignisse
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	Automatisierung
Modulname	91_notify.pm
Ersteller	rudolfkoenig (Forum / Wiki)
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Einführung

Weitere grundlegende Informationen/Beispiele zu notify enthält Heimautomatisierung mit FHEM

Das Hilfsmodul notify dient dazu, Aktionen abhängig vom Eintritt bestimmter Bedingungen - in FHEM als [Event] bezeichnet - auszulösen bzw. zu prüfen, ob diese ausgelöst werden sollen. Mit notify und anderen sogenannten Event-Handlern^[1] ist es möglich, Logikfunktionen im FHEM abzubilden.

Beispiele:

Wird das Licht in der Küche eingeschaltet, soll FHEM dort auch das Radio einschalten.
Bei Druck auf einen Taster soll die Umwälzpumpe für das Warmwasser eingeschaltet werden.
Erweiterte Möglichkeiten: Aber nur, wenn das Radio aus ist bzw. die Temperatur im Rücklauf des Warmwassers unterhalb einer bestimmten Schwelle liegt^[2].

Syntax

define <name> notify <Suchmuster> <command>

Das Suchmuster (häufig als Regexp = regular expression = regulärer Ausdruck bezeichnet) ist sehr wichtig: Es ist entweder der Name des auslösenden ("triggernden") Gerätes oder die Kombination aus Gerät und auslösendem Ereignis (Event) Gerätename:Event. Die Events kann man dem Event-Monitor entnehmen. Wenn dort z.B. Rollo1 steht, dann reagiert notify auf Rollo1 on und Rollo1 off usw.

Wenn man mehrere Suchmuster kombinieren möchte, kann man diese in Klammer schreiben, als Trenner wird dann Pipe (|) genutzt: (Rollo1|Rollo2|Steckdose5).

Auch die Verwendung von Platzhaltern ist möglich:

Rollo. → das notify reagiert auf alles was mit Rollo und einem weiteren beliebigen Zeichen anfängt. Also auf Rollo1 wie auch auf RolloG, aber nicht auf Rollo_wischundweg
Rollo.* → notify reagiert auf alles das mit Rollo beginnt
.*isch → auf alles das mit isch aufhört (Tisch, Fisch)
Schalter(1|2|3) → hört auf Schalter1, Schalter2 und Schalter3
dimmer:pct:.(100|7[6-9]|[89][0-9]) → reagiert, wenn pct einen Wert über 75 annimmt.

Suchmuster/Regex kann man im Internet beispielsweise auf http://regexpal.com/ testen.

FHEMWEB-unterstützte Anlage eines notify

Die Erstellung eines notify und insbesondere die korrekte Angabe des Suchmusters (Regex) führt gerade bei Einsteigern immer wieder zu Schwierigkeiten. Zur Fehlerminimierung empfiehlt es sich zum einen, die Konfiguration nicht direkt zu bearbeiten, sondern die "Befehl-Eingabezeile", die "Objektdetails" oder den Import von RAW-Definitionen zur Bearbeitung zu nutzen.

Event Monitor

Die komfortabelste Möglichkeit, die häufigsten Event-Handler zu erstellen, bietet der Event-Monitor. Die Vorgehensweis ist in dem zugehörigen Artikel dargestellt.

Regexp wizard

Zudem enthält FHEM einen Regexp wizard mit dem Regex anhand der in FHEM vorhandenen Devices und deren Events aus einer Auswahlbox selektiert werden können. Voraussetzungen sind:

Aktivierung des Hilfsmoduls eventTypes (bei allen Neuinstallationen Standard)
das gesuchte Ereignis (Event) ist nach Aktivierung des Hilfsmoduls bereits mindestens einmal eingetreten

Schrittweise Darstellung der Nutzung des Regexp wizard zur Anlage eines "notify":

In das Befehls-Eingabefeld eingeben und mit Enter bestätigen:

define ntest notify a b

Als Beispiel wird ein notify mit <name> "ntest" angelegt. "a" und "b" sind beliebige Platzhalter für <Suchmuster> und <Command>, die bei der weiteren Bearbeitung mit dem endgültigen Werten ersetzt werden. Der Regexp wizard öffnet sich:

Nun in der Auswahlbox das auslösende Event (Ereignis) auswählen; zunächst das Device und dann das gewünschte Regex. Hier soll das notify bei jeder Veränderung der Temperatur (temperature.*) des Device BTHR918N reagieren. Abschließend mit einem Mausklick auf set bestätigen. Wählt man mehrere Regex in dieser Weise aus, so wird das "notify" bei Eintritt jedes dieser Events ausgeführt:

Anschließend den Platzhalter "a" mit Klick auf den Link "removeRegexpPart" löschen:

Den Link "DEF" anklicken, damit sich der DEF-Editor öffnet:

Jetzt den auszuführenden Befehl im "DEF"-Bereich durch Überschreiben des Platzhalters "b" eintragen und mit Klick auf modify ntest abschließen:

Das fertige und sofort aktive "notify" sieht abschließend folgendermaßen aus:

Am Schluss das Speichern über Save config nicht vergessen.

Mein notify geht nicht - wie kann ich mir selbst helfen: Debugging

Funktioniert ein notify nicht wie gewünscht, kann es nach dem oben gesagten nur zwei Ursachen haben:

Entweder die Regex (das Suchmuster) paßt nicht zum gewünschten Auslöser, und/oder
die auszuführende Aktion (das <command>) enthält einen Fehler bzw. der sonstige Übertragungsweg zum Zieldevice usw. funktioniert nicht richtig.

Beim Debuggen sollte man daher beide Elemente getrennt untersuchen:

Auslöser

Da ein notify zwingend ein Event voraussetzt, nimmt man am einfachsten den Event-Monitor, begrenzt ggf. die dort angezeigten Ereignisse und kopiert dann das passende Event. Dieses kann man entweder wie oben geschildert nutzen, um die eigene Regex z.B. mit http://regexpal.com/ auf Übereinstimmung zu testen, oder man nutzt wie beschrieben direkt den Event-Monitor oder den wizard zur Anlage des notify, um diese Fehlerquelle auszuschließen.

command

Um die durch notify ausgelösten Aktionen zu testen, kann entweder

das trigger-Kommando verwendet werden: Um define Testcode notify Schalter1:on <FHEM-Anweisung oder Perlcode> zu testen, geben Sie in der Kommandozeile trigger Schalter1 on ein.
Alternativ kann der Ausführungsteil <FHEM-Anweisung oder Perlcode> durch direkte Eingabe in die Kommandozeile getestet werden. {Perlcode} ist dabei in geschweiften Klammern einzugeben.

Man erhält dann entweder eine Fehlermeldung von FHEM, wenn z.B.

das Device nicht auf "on" geschaltet werden kann, oder
der Perl-Code einen Fehler enthält, z.B. bei der Klammersetzung.

Reagiert das Zieldevice Schalter1 in dem genannten Beispiel nicht auf ein korrektes Kommando, liegt der Fehler woanders und man sollte insbesondere den Übertragungsweg untersuchen^[3]

Beispiele

Für die nachfolgenden Beispiele wurden einige unterschiedliche Technologien verwendet. Sie können aber recht einfach auf alle anderen Systeme übertragen werden, dabei sollte ggf. darauf geachtet werden, dass sich Schaltbefehle und Events teilweise je nach konkret eingesetzter Technologie unterscheiden können. Dann ist ggf. eine Erweiterung, z.B. durch eine if-Abfrage erforderlich.

Etwas schalten, wenn ein anderes Gerät geschaltet wird

Vorbedingungen

Dieses Beispiel verwendet eine einfache InterTechno-kompatible Funksteckdose für das Radio und einen HM-Aktor für das Licht:

define RadioKueche IT 000000FFFF 0F F0
define LichtKueche CUL_HM 3A37D6

Beachte: beide kennen als Event bzw. Schaltbefehle on und off.

notify Befehl

define LichtamRadioan notify LichtKueche set RadioKueche $EVENT

oder alternativ:

define LichtamRadioan notify LichtKueche { fhem "set RadioKueche $EVENT" }

Erklärung

Der Name des notify "LichtamRadioan" kann frei gewählt werden, er dient nur dazu, das notify in FHEM eindeutig zu identifizieren.
"$EVENT" ist ein Platzhalter für den Zustand vom Pattern. $EVENT enthält ein "off" wenn das LichtKueche aus- und ein "on" wenn das Licht eingeschaltet wird.
"{ <perlcode> }" alles was zwischen {} steht ist Perl code. Perl kennt das Schlüsselwort fhem. Das Schlüsselwort FHEM dient dazu, FHEM Befehle auszuführen. Es wird also der FHEM Befehl "set RadioKueche on/off" ausgeführt. on oder off ist abhängig vom Pattern. Der eigentliche FHEM Befehl muss in " " stehen.
Wann ist ein Wechsel auf die Perl-Ebene erforderlich?
- einfache FHEM-Befehle sollten in der Regel direkt verwendet werden, dies ist ressourcenschonender.
- Immer dann, wenn dies nicht möglich ist, weil z.B. komplexerer Code ausgeführt werden soll, (blockierende) Prozesse ausgelagert werden sollten oder Systembefehle ausgeführt werden, ist es günstiger, auf die Perl-Ebene zu wechseln ^[4].

Einschalten von mehreren Geräten/Lampen, wenn das Licht eingeschaltet wird

Dieses Beispiel verwendet einen HM-Aktor für das Licht sowie zwei Milight-Birnen, die einzeln geschaltet werden sollen^[5] in den Stehlampem:

Vorbedingungen

FHEM:

define LichtWZ CUL_HM 3A37D8
define Stehlampe1 KNX MilightDevice RGBW Milight_Wohnzimmer 5
define Stehlampe2 MilightDevice RGBW Milight_Wohnzimmer 6

notify Befehl

define SteckdoseWZein notify LichtWZ set Steckdose1,Steckdose2 $EVENT

oder in Perl

define SteckdoseWZein notify LichtWZ { fhem "set Steckdose1 $EVENT;;set Steckdose2 $EVENT " }

Erklärung

Wenn das LichtWZ eingeschaltet wird, dann werden auch die Stehlampen (1 und 2) eingeschaltet.

Einfache ODER Funktion

Eine einfache ODER Funktion kann sehr einfach realisiert werden

Vorbereitung

KNX:

3x GAs der abzufragende Werte (0/0/40 0/0/41 0/0/42)

FHEM:

define Licht1 CUL_HM 3A37D8
define Licht2 CUL_HM 1B7EC3
define Stehlampe MilightDevice RGBW Milight_Wohnzimmer 7

notify Befehl

define SteckdoseWZein notify (Licht1|Licht2) set Stehlampe $EVENT

oder

define SteckdoseWZein notify (Licht.) set Stehlampe $EVENT

Erklärung

Die Werte in der Klammer (wichtig ist das »|«) sind die Rückgabewerte. Alternativ kann in diesem Beispiel auch »Licht.« (zu beachten ist der Punkt) geschrieben werden. Der Punkt ist ein Platzhalter für (genau) ein beliebiges Zeichen.

Danach folgt der set Befehl. Wenn also das Licht1 oder Licht2 den Wert "on" hat, dann hat auch die Steckdose den Wert "on"

Alternative: structure

Einfache UND Funktion

Ob man dieses Konstrukt noch als einfach bezeichnen kann, wage ich mal zu bezeifeln. In FHEM fehlen Loggingfunktionen, die man alle selber mit Perl Code erstellen kann (Danke an MAZ). Dadurch ist FHEM zwar mächtig, wird aber für viele sehr kompliziert.

In diesem Beispiel soll - wenn drei Rollos geschlossen sind - am Taster eine LED eingeschaltet werden.

Vorbereitung

KNX:

3x GDs für die Rückgabewert Rollo geschlossen == 1 (0/0/50 0/0/51 0/0/52)
GD LED am Lichtschalter (0/0/106)

FHEM:

define R1ZU KNX 0/0/50:dpt1.009
attr R1ZU dummy 1
define R2ZU KNX 0/0/51:dpt1.009
attr R2ZU dummy 1
define R3ZU KNX 0/0/52:dpt1.009
attr R3ZU dummy 1
define LEDalleRolloZu KNX 0/0/106:dpt1

Durch das Atribut dummy werden keine Schaltfunktion angeboten. Es kann nur Werte anzeigen.

notify Befehl

define nt.allerolloszu notify (R1ZU|R2ZU|R3ZU) {
my $r1 = Value("R1ZU");;
my $r2 = Value("R2ZU");;
my $r3 = Value("R3ZU");;
if ($r1 eq "on" && $r2 eq "on" && $r3 eq "on") {
  fhem "set LEDalleRolloZu on"
} else {
  fhem "set LEDalleRolloZu off"
}
}

Erklärung

Es werden die drei Rückgabewerte R1ZU, R2ZU und R3ZU ausgewertet. Danach folgt Perl Code, deswegen beginnt das ganze mit einer { und endet mit }

my $r1 => Variable $r1 definieren = Value("R1ZU");; ==> weist den Rückgabewert (on oder off) von R1ZU der Variable $r1 zu

Der doppelte ;; ist ein FHEM Thema. Eigentlich würde für Perl ein ; reichen. Aber FHEM nutzt selbst das ; und daher wird ein ;; benötigt. Mit den ersten drei my Zeilen werden die Rückgabewerte den Variabeln zugewiesen.

Danach erfolgt ein normales "if then else" Konstrukt. Die Zeile »($r1 eq "on" && $r2 eq "on" && $r3 eq "on")« kann man so lesen: Wenn $r1 den Wert "on" und (&&) $r2 den Wert "on" und $r3 den Wert "on" dann schalte die LEDalleRolloZu ein {fhem("set LEDalleRolloZu on")} ansonsten else schalte die LED aus. {fhem("set LEDalleRolloZu off")

Alternative: structure

Zeitverzögert schalten

Aufgabe:	Zeitverzögert schalten
Beschreibung:	Mit einem Notify zeitverzögert eine Aktion auslösen.
Vorbereitung:	Gerät "Lampe" ist definiert und es gibt eine Situation, die ein Ereignis "Fernbedienung:.*" generiert.
Befehl:	`define ntfy1 notify Fernbedienung:.* sleep 7.5;; set Lampe $EVENT`
Erläuterungen:	Bei Eintreten eines Ereignisses "Fernbedienung" wird nach einer Pause von siebeneinhalb Sekunden der Befehl <set Lampe ??> ausgeführt, wobei der eigentliche Befehl aus dem auslösenden Ereignis übernommen wird. Quelle: FHEM Forum*

Eine PV-Anlage (Solarstrom) zur Steuerung der Rollos nutzen (optional Zeit und Datums abhängig)

Hier ein kleines Beispiel, wie man mit Hilfe einer PV-Anlage die Sonneneinstrahlung auf der Südseite ermittelt und dies zur Rolladensteuerung nutzt. Optional: Die Funktion soll allerdings nur zwischen 9:30 und 17:00 stattfinden. (zweites Beispiel) Optional: Die Funktion soll nur zwischen dem 6. und 9. Monat funktioneren. (drittes Beispiel)

Vorbereitung

PV Anlage mit SolarView abfragen. Per Hand ermitteln, ab wieviel erzeugtem Strom es sinnvoll ist die Rollos zu schließen.

notify Syntax

FHEM:

define sv SolarView solarview 15000 wr1 wr2 wr3 wr4                           <----vier Wechselrichter
attr sv event-on-change-reading currentPower

define nt.sonnenlichtpersolar notify (sv:currentPower.*) { 
 if ($EVTPART1 < 3000 ) {
 fhem('set Flur1 Auf');
}else {
 if ($EVTPART1 > 5000 ) {
 fhem('set Flur1 Ab');
 } 
 }
}

Optional 1: Zeitabhängig

(sv:currentPower.*) { 
 my $hm = sprintf("%02d:%02d", $hour, $min);
  if ( $hm gt "09:30" && $hm lt "17:00") { 
  if ($EVTPART1 < 5000 ) {
   fhem('set Flur1 Auf');
   }else {
   if ($EVTPART1 > 8000 ) {
   fhem('set Flur1 Ab');
   } 
   }
  }
 }

Optional 2: Zeit und Datum

(sv:currentPower.*) { 
 my $hm = sprintf("%02d:%02d", $hour, $min);
 if ($month >= 6 && $month <= 9) {
  if ( $hm gt "09:30" && $hm lt "17:00") { 
  if ($EVTPART1 < 5000 ) {
   fhem('set Flur1,RBUERO1,RBUERO2 Auf');
   }else {
   if ($EVTPART1 > 8000 ) {
   fhem('set Flur1,Flur2,RBUERO1,RBUERO2 Ab');
   } 
   }
  }
  }
 }

Erklärung

Das define wird in der Kommandozeile im Webbrowser eingegeben.
Anschliessend wird im Webbrowser die DEF bearbeitet, das erspart uns Probleme mit Perl
define sv SolarView ... <==== ist die Schnittstelle vom SolarView
define nt.sonnenlichtpersolar notify (sv:currentPower.*) { <==== hier wird ein notify angelegt, der auf das "define sv" Wert "currentPower.*" (.* ist irgendwas) reagiert

 if ($EVTPART1 < 3000 ) {
   fhem('set Flur1 Auf');
 }else {
  if ($EVTPART1 > 5000 ) {
   fhem('set Flur1 Ab');
 } 
  }
 }

Diese if-Funktion wertet den Rückgabewert von currentPower aus. Hierbei muss man wissen, dass $EVTPART1 das Splitergebnis vom Rückgabewert ist

Beispiel: Der Rückgabewert (wie im Beispiel) ist "currentPower: 6000". Jetzt steht im "$EVTPART0 == currentPower:" und im "$EVTPART1 == 6000" Das bedeutet, dass man sich nicht selbst den richtigen split (Perl Befehl) Aufruf ausdenken muss, dies übernimmt vielmehr FHEM.

Ergebnis: Das Rollo wird abhängig von der erzeugten IST_Strommenge auf und zu gefahren. Damit dies nicht dauernd hin und her pendelt, wurde der Auf Wert sehr klein und den Ab Wert sehr groß gewählt.

Optional 1: Der Block "my $hm = sprintf("%02d:%02d", $hour, $min);" erzeugt die String-Variable $hm mit dem Inhalt $hour:$min. %02d begrenzt die Ausgabe auf zwei Stellen. Danach wird mit "if ( $hm gt "09:30" && $hm lt "17:00")" mit stringvergleichende Operatoren geprüft, ob die Uhrzeit zwischen 9:30 und 17:00 liegt (lt = kleiner als; gt = größer als). Es wäre auch ein le und ge möglich: le = kleiner/gleich als, ge = größer/gleich als.

Optional 2:if( $month >= 6 && $month <= 9) {

Hier wird die numerische FHEM-Standard-Variable $month (Monat) auf größer/gleich bzw kleiner/gleich mit den binären Operatoren überprüft. Die Funktion arbeitet also nur zwischen dem 6. und dem 9. Monat und dann auch nur zwischen 9:31 und 16:59.

Status eines Kippfensters mit 2 Fensterkontakten abbilden

Vorbereitung

Es ist je ein Fensterkontakt der open oder closed meldet, oben und unten am Fenster angebracht. Die Namen der beiden FHEM-Devices sind fensterKontaktOben und fensterKontaktUnten.

notify Syntax

FHEM:

define statusFenster notify fensterKontakt(Oben|Unten):(open|closed) {
if ( ReadingsVal('fensterKontaktOben', 'state', 'undef') eq 'open' && ReadingsVal('fensterKontaktUnten', 'state', 'undef') eq 'open')
       { fhem 'set Terrassentuer open' }
if ( ReadingsVal('fensterKontaktOben', 'state', 'undef') eq 'closed' && ReadingsVal('fensterKontaktUnten', 'state', 'undef') eq 'closed')
       { fhem 'set Terrassentuer closed' }
if ( ReadingsVal('fensterKontaktOben', 'state', 'undef') eq 'open' && ReadingsVal('fensterKontaktUnten', 'state', 'undef') eq 'closed')
       { fhem 'set Terrassentuer tilted' }
if ( ReadingsVal('fensterKontaktOben', 'state', 'undef') eq 'closed' && ReadingsVal('fensterKontaktUnten', 'state', 'undef') eq 'open')
       { fhem 'set Terrassentuer undef' }
}

Weitere Hinweise

Entsprechend zu $EVENT gibt es auch noch $NAME und $TYPE. $NAME und $TYPE enthalten den Namen bzw. Typ des Ereignis auslösenden Gerätes.
Wird der Perl-Code in einem notify immer länger, lagere den Code wegen der Übersichtlichkeit in eine eigene Programmdatei aus, wie in 99_myUtils anlegen beschrieben.
Achtung! Wenn man das Skript für den notify-Befehl über mehrere Zeilen schreibt, muss man anscheinend darauf achten, dass keine abschliessende Leerzeile mitgespeichert wird. Sonst wird der notify-Befehl ignoriert.
Dieser Beitrag enthält Vorschläge zur Vorgehensweise bei der Erstellung von komplexen notify Definitionen bzw. bei deren Fehlerbehebung.

Weiterführende Links

Hinweise

↑ hierzu gehören u.a. auch DOIF, THRESHOLD und watchdog
↑ vgl. hierzu z.B. FILTER und if-condition
↑ insbesondere: Ist das erforderliche IODevice verfügbar/online, das WLAN angeschaltet, der Aktor mit Strom versorgt?
↑ In diesem Forenbeitrag wird z.B. erläutert, wie man nichtblockierend externe scripte aufrufen kann, die dann ihre Ergebnisse wieder an FHEM übergeben.
↑ Dies ist ausdrücklich keine Empfehlung für diese Technologie und der Module

[1] rzu gehören u.a. auch DOIF, THRESHOLD und watchdog

[2] vgl. hierzu z.B. FILTER und if-condition

[3] sbesondere: Ist das erforderliche IODevice verfügbar/online, das WLAN angeschaltet, der Aktor mit Strom versorgt?

[4] In diesem Forenbeitrag wird z.B. erläutert, wie man nichtblockierend externe scripte aufrufen kann, die dann ihre Ergebnisse wieder an FHEM übergeben.

[5] Dies ist ausdrücklich keine Empfehlung für diese Technologie und der Module

[1]

[2]

[3]

[4]

[5]