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 aktueller, 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.

Achtung! Der Begriff Ereignis wird in diesem Artikel erweitert verwendet und umfasst ablaufende Timer und Ereignisse(Events).

Verhaltensweise ohne steuernde Attribute

Angaben im Bedingungsteil

Der Bedingungsteil besteht aus einer Perl-Ebene und einer Präprozessorebene.

(Perl-Ebene [DOIF-Präprozessor] Perl-Ebene [DOIF-Präprozessor] ...)

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 für DOIF ablaufende Timer oder Ereignisse (Events) die durch Geräte initiiert 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) und DOIF wartet auf das nächste Ereignis.

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 Statuswechsel findet statt, wenn ein anderer Bedingungszweig wahr wird.

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

Auslöser können durch direkte Angabe des Gerätenamen, Readings, Internals usw. angegeben werden.

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 Reading-Wertes.

[<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 sie 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 (Regex) formulieren zu können.

Readings und Internals

[<Auslöserangabe>:<Regex 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>:"<Regex Ereignisrest>"]

["<Regex Gerätename>:<Regex Ereignisrest>"]

["<Regex Ereignis>",<Vorgabewert>]

["<Regex Ereignis>":<Regex 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.

(<FHEM-Befehle>), ("<Systembefehle>") oder ({<Perl-Befehle>})

Befehle können zu Sequenzen gruppiert werden durch mehrere runde Klammerpaare der ersten Ebene)

(<Befehle der Sequenz 1>) (<Befehle der Sequenz 2>) ... (<Befehle der Sequenz n>)

Trennzeichen für Befehle ist das Komma, daher ist keine Verdoppelung der Trennzeichen erforderlich.

(<Befehl 1>, <Befehl 2>, ... <Befehl n>)

Enthält ein Befehl ein Komma, dass kein Befehlstrennzeichen ist, dann ist der Befehl in zusätzliche runde Klammern einzuschliessen.

((<Befehlsteil 1a>,<Befehlsteil 1b>), <Befehl 2>, ... <Befehl n>)

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. Befehle werden wiederholt im bestehenden Status ausgeführt.

Das interne DOELSE entfällt bei DOIF mit einem Zweig.

Wait-Timer werden bei wiederholtem Wahrwerden 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.

Links

• DOIF
• DOIF/Tipps zur leichteren Bedienung Erstellung, Bearbeitung, Syntaxhervorhebung, Klammerprüfung, Suchen&Ersetzen, Zeilennummerierung, uvm. (nicht nur) von DOIF
• Regulärer_Ausdruck
• Event Ereignisse
• Readings
• Internals
• Attribute

• http://perldoc.perl.org/perlop.html Perloperatoren
• http://perldoc.perl.org/perlre.html Reguläre Ausdrücke