DOIF/Einsteigerleitfaden, Grundfunktionen und Erläuterungen
Das DOIF, ursprünglich für Einsteiger entwickelt, hat sich zu einem immer vielfältigeren Werkzeug entwickelt, dass auch spezielle und komplexe Probleme in kompakter Weise lösen kann. Damit nimmt auch die Zahl der Einstellungsmöglichkeiten über Attribute, Syntaxvarianten und deren Kombinationen zu. Da ist es für Einsteiger und Fortgeschrittene meist nicht leicht den Überblick zu behalten.
Hinweis!
Die deutschsprachige FHEM-Befehlsreferenz (Commandref) zum DOIF sollte bei Fragen immer das erste Nachschlagewerk sein. Sie ist genauer und mit Beispielen versehen. Dieser Artikel ist eine geraffte Darstellung der Grundlagen des DOIF mit einigen Erläuterungen.
Voraussetzung
Die FHEM-Begriffe Device (Gerät), State (Status), Readings, Internals, Attribute, Event (Ereignis), Befehl (Command) und deren Funktion sollen bekannt sein.
DOIF-Light für Einsteiger
Die meisten Verknüpfungsaufgaben können mit einem Verständnis der folgenden Abschnitte der Hilfe zum DOIF (deutschsprachige Befehlsreferenz) gelöst werden.
- Einleitung
- Features
- Lesbarkeit der Definitionen
- Ereignissteuerung
- Zeitsteuerung
- Wochentagsteuerung
- Zeitsteuerung mit Zeitintervallen
- Indirekte Zeitangaben
- Angaben im Ausführungsteil
- do always
- wait
- do resetwait
- readingList, setList (Frontendgestaltung)
- zu beachten
- Kurzreferenz als Überblick
Struktur und Verhalten des DOIF
Der Aufbau des DOIF entspricht einer Baumstruktur mit Bedingungszweigen.
Verhaltensweise ohne steuernde Attribute
Angaben im Bedingungsteil
Der Bedingungsteil besteht aus einer Perl-Ebene und einer Präprozessorebene.
Die erste Ebene der ersten runden Klammer nach den Schlüsselwörtern DOIF oder DOELSEIF umschliesst eine Bedingung.
Für Angaben in dieser Klammer (Perl-Ebene) gilt die Perl-Syntax (Operatoren, Operanden, wie Funktionen, Variablen), ausgenommen sind die Angaben in der ersten Ebene der eckigen Klammern, sie umschliessen die Ebene des DOIF-Präprozessors, dort gilt die Syntax des DOIF-Präprozessors.
In dieser Ebene der eckigen Klammern werden DOIF-Operanden angegeben. Die DOIF-Operanden beinhalten Auslöser.
Auslöser sind Zeitpunkte, Gerätenamen und Reguläre Ausdrücke, die auf Gerätenamen oder das Ereignis passen.
Ereignisse sind ablaufende Timer oder Ereignisse (Event Events) die durch Geräte initiert werden.
Der DOIF-Prozess wird gestartet wenn ein Ereignis eintrifft.
Passt ein Auslöser einer Bedingung zu dem Ereignis wird diese Bedingung geprüft.
Ist die Bedingung wahr, werden die nach der Bedingung stehenden Befehle ausgeführt.
Nach der Befehlsausführung wird der Status des DOIF auf die Befehlsnummer gesetzt (cmd_x).
Ist die Bedingung unwahr (falsch) wird der nächste Zweig bearbeitet.
Ist DOELSE angegeben, es gab einen passenden Auslöser und alle geprüften Bedingungen waren unwahr, dann werden die nach DOELSE angegebenen Befehle ausgeführt.
Die Befehle eines Zweiges werden ohne vorherigen Statuswechsel nur einmal ausgeführt.
Ein DOIF mit nur einem Zweig enthält ein internes DOELSE, d.h. bei unwahrer Bedingung und vorhandenem Auslöser, findet ein Statuswechsel auf cmd_2 statt.
Auslöser
Readings und Internals
[<Gerätename>] oder [<Gerätename>:&STATE]bezieht sich auf das Internal STATE des Gerätes.
[<Gerätename>:<Readingname>] bezieht sich auf das Reading des Gerätes.
[<Gerätename>:<Readingname>:d] bezieht sich auf den numerischen Teil des Readings.
[<Gerätename>:<Readingname>:sec] bezieht sich auf das Alter des Zeitstempels in Sekunden.
[<Gerätename>:&<Internalname>] bezieht sich auf das Internal des Gerätes.
[<Auslöserangabe>,<Vorgabewert>] nicht existierende Auslöser können mit einem Vorgabewert angegeben werden.
Zeitangaben
[<Zeitpunkt>] gibt einen Zeitpunkt an
[<Zeitpunkt Beginn>-<Zeitpunkt Ende>|<Wochentagangaben>] gibt eine Zeitspanne an, optionale Wochentagangabe
[[<Auslöserangabe>]] gibt einen Zeitpunkt indirekt an.
Mit Zeitangaben kann gerechnet werden, Berechnungen erfolgen in runden Klammern.
Liefert eine Perl-Funktion HH:MM:SS muss die in geschweifte Klammern eingeschlossen werden.
Auslöser (erweitert)
Auslöser können auch allgemein formuliert werden, dazu ist die Fertigkeit erforderlich "Reguläre Ausdrücke" formulieren zu können.
Readings und Internals
[<Auslöserangabe>,<Vorgabewert>] nicht vorhandene Auslöser können mit einem Vorgabewert angegeben werden.
[<Auslöserangabe>:<Regexp Filter>,<Ausgabeformatierung>] Auslöser können mit einem Filter eränzt werden, die gefilterten Werte können in der Ausgabeformatierung weiterverarbeitet werden.
Ereignisse
[<Gerätename>:"<Regexp Ereignisrest>"]
["<Regexp Gerätename>:<Regexp Ereignisrest>"]
["<Regexp Ereignis>",<Vorgabewert>]
["<Regexp Ereignis>":<Regexp Filter>,<Ausgabeformatierung>,<Vorgabewert>] optional: Filter und Formatierung, verpflichtend: Vorgabe
Alle Auslöser
[?<Auslöserangabe>] Auslöser, die mit Fragezeichen beginnen lösen nicht aus, Sie werden nur abgefragt
Angaben im Befehlsteil
Befehle stehen nach einer Bedingung oder nach DOELSE in runden Klammern (erste Klammerebene), das ist die FHEM-Ebene. Befehle können direkt angegeben werden.
Befehle können zu Sequenzen gruppiert werden durch mehrere runde Klammerpaare der ersten Ebene)
Trennzeichen für Befehle ist das Komma, daher ist keine Verdoppelung der Trennzeichen erforderlich.
Enthält ein Befehl ein Komma, dass kein Befehlstrennzeichen ist, dann ist der Befehl in zusätzliche runde Klammern einzuschliessen.
Berechnungen erfolgen in geschweiften Klammern auf der Perl-Ebene und müssen unmittelbar mit einer runden Klammer beginnen.
der Zugriff auf Readings, Internals usw. erfolgt wie im DOIF üblich, über Angaben in eckigen Klammern inklusive Ausgabeformatierung und Präprozessorersatznamen, wie $SELF, $DEVICE, $EVENT, $EVENTS (extended set magic).
Häufige Attribute
Attribute verändern das Standardverhalten des DOIF.
do always
Ohne do always gilt:Die Befehle eines Bedingungszweiges werden ohne vorherigen Statuswechsel nur einmal ausgeführt.
Das Attribut setzt diese Regel ausser Kraft.
Das interne DOELSE entfällt bei DOIF mit einem Zweig.
Wait-Timer werden bei wiederholtem wahr werden der Bedingung nicht abgebrochen.
wait
Das Attribut verzögert die Befehlsausführung, nach wahr werden einer Bedingung.
Laufende Wait-Timer werden bei einem Statuswechsel abgebrochen und die Befehle werden nicht ausgeführt.
do resetwait
Das Attribut beinhaltet do always, bricht aber die Wait-Timer bei wiederholtem wahr werden der Bedingung ab.
readingList, setList, webCmd, widgetOverride
Diese Attribute statten DOIF mit Dummy-Eigenschaften aus, so dass DOIF als erweitertes Eingabeelement im Frontend dienen kann.