WeekdayTimer

Todo: Der Commandref-Abschnitt zu diesem Modul enthält noch einige Fehler und Ungenauigkeiten, die im Zusammenhang mit der Ausarbeitung dieser Wiki-Seite korrigiert werden sollten. Auf dieser Seite fehlen insbesondere noch Anwendungsbeispiele mit Screenshots sowie die Beschreibung von Besonderheiten wie die vereinfachte/integrierte Unterstützung von enable/disable.

WeekdayTimer
Zweck / Funktion
Definition von Wochen-Zeitschaltplänen
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	Unterstuetzende Dienste
Modulname	98_WeekdayTimer.pm
Ersteller	Dietmar63
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

WeekdayTimer ist ein Hilfsmodul zur Erstellung von (Wochen-)Zeitschaltplänen für Geräte. WeekdayTimer ist eine generische Weiterentwicklung des Moduls Heating_Control und verfügt dementsprechend über einige features, die speziell auf die Steuerung mittels Temperaturprofilen zugeschnitten sind. Diese sind im Teil 2 der Anwendungsbeispiele dargestellt.

Voraussetzungen

Keine.

Anwendung

Define

Ein WeekdayTimer wird angelegt mittels

define meinWDT WeekdayTimer Zieldevice [Sprache] [Wochentage] <profil> ...

Elemente einer Definition können sein:

Zieldevice

Das Gerät, an das ein Schaltbefehl zur angegebenen Zeit gesendet werden soll

Sprache

optional) Kann de,en,fr oder nl sein

Wochentage

Kann (optional) als globale Vorgabe vorangestellt werden; Syntax ist identisch zu profil (s.u.)

profil

Das eigentliche Wochenprofil. Die einzelnen Zeiten sind durch Leerzeichen zu trennen, möglich sind "klassische" Profilelemente oder die Angabe eines weekprofile-Geräts (oder mehrerer, Details s.u.)

Klassisches Profilelement

Ein "klassisches" Profilelement enthält die folgenden Elemente:

   [<Wochentag/e>|]<Zeit>|<Parameter>[|w]

• Wochentag/e

Die Angabe ist optional. Wenn nicht gesetzt, gilt dieses Element für die ganze Woche (bzw. die Tage der globalen Vorgabe, s.o.). Genutzt werden können Tagesnummern oder die Kurzbezeichnungen der jeweils eingestellten Sprache, z.B..

• • 0,so Sonntag
  • 1,mo Montag
  • 2,di Dienstag
  • 3,mi Mittwoch
  • 4 ...
  • 7,$we Wochendende ($we) (unter Beachtung der in holiday2we bei global angegebenen Geräte)
  • 8,!$we Wochentag (!$we) (s.o. zu holiday2we)

Hinweis: $we nutzt für heute und morgen intern die allgemeine IsWe()-Funktion. Für die weiteren Tage können dagegen nur Geräte des Typs holiday ausgewertet werden, sofern sie in holiday2we bei global angegeben sind, einschließlich der besonderen Geräte weekEnd und noWeekEnd (beachten Sie hierzu die Beschreibung des Attributes holiday2we bei global).

• Zeit

Die eigentliche Schaltzeit. Kann im Format HH:MM:[SS](HH im 24-Stunden-Format) angeegeben werden oder als Perl-Funktion wie {sunrise_abs()}. Innerhalb der Perl-Funktion {} kann die Variable $date (epoch) genutzt werden, um die genaue Schaltzeit im Wochenverlauf zu ermitteln. Beispiel: {sunrise_abs_dat($date)}

• Parameter

Der eigentliche Schaltparameter. Kann beliebiger Text oder Zahl sein, z.B on, off, dim30%, eco oder comfort, je nachdem, welche Schaltanweisungen im zu schaltenden Gerät möglich sind. Um Leerzeichen zu ersetzen, ist ":" zu verwenden, wird ein Doppelpunkt in der Schaltanweisung benötigt, muss dieser escaped werden. Möglich wäre daher z.B. on-till:06\:00.

• "w"

Die letzte (optionale) Angabe "w" dient der Priorisierung des $we-Parameters. An Tagen, die für IsWe() wahr liefern, wird das Profilelement dann nicht berücksichtigt, sondern nur, wenn es sich (ggf. erst durch Verwendung von noWeekEnd) um einen normalen Wochentag handelt! Beispiele:

• • 06:35|22.5
  • 7|23:35|25
  • 45|23:35|25|w
  • 20:35|on|w

weekprofile Profilelement

Über weekprofile können (ausschließlich) Temperaturlisten dynamisch und unter Nutzung der Topic-Optionen in diesem Modul verändert werden, um so z.B. einfach zwischen Urlaubs- und Normalmodus (oder Heimarbeitstagen) wechseln zu können. Auch für Schichtgruppen kann dies hilfreich sein. Beispiel einer weekprofile Definition:

weekprofile:<weekprofile-device-name>

Beispiel einer weekprofile Definition, bei der das Sonntags-Profil für alle $we-Tage gelten soll (mit Priorisierung des $we):

weekprofile:<weekprofile-device-name>:true

Um zwischen verschiedenen Profilen zu wechseln, die weekprofile bereitstellt, nutzen Sie den entsprechenden set-Befehl

Schaltbefehl/Bedingung

Den letzten (optionalen) Parameter bilden entweder ein Schaltbefehl oder eine Bedingung. Ist keines von beidem angegeben, wird die im commandTemplate-Attribut angegebene Schaltanweisung verwendet.

Schaltbefehl

Ist keine Bedingung gesetzt, werden die verbliebenen Elemente als Schaltbefehl interpretiert. Perl-Code kann angegeben werden und ist wie sonst auch üblich in {} zu setzen. Wird ein Schaltbefehl angegeben, wird auch nur dieser wie angegeben ausgeführt, commandTemplate hat dann keine Auswirkungen. Es können die $NAME und $EVENT als Parameter verwendet werden, wobei $NAME der Name des Zieldevices ist und $EVENT dem Parameter aus dem Profilelement entspricht.

Bedingung

Eine Schaltbedingung muß in runden Klammern angegeben werden ("()") und gültigen Perl-Code enthalten. Dieser muß einen Bool-schen Wert zurückliefern, die Parameter $NAME und $EVENT können auch hier verwendet werden.

Set

disable und enable

Diese Befehle dienen dazu, einen WeekdayTimer zu (de-)aktivieren. Das entsprechende Attribut wird gesetzt, wobei ein enable zusätzlich genutzt werden kann, um eine Neuberechnung aller anstehenden Timer des Tages zu veranlassen. Dies ist z.B. hilfreich, wenn sich der Zustand einer Bedingung ändert, die zur Verzögerung oder dem Überspringen eines in der Vergangenheit liegenden Schaltzeitpunkt geführt hat oder man ein weekprofile-Profil geändert hat und dieses neu eingelesen werden soll.

WDT_Params

Wirkt ähnlich wie das beschriebene enable, wobei man hier die Wahl zwischen

• single
• WDT_Group
• all hat.

Im Unterschied zu enable werden die Schaltzeitpunkte jedoch nicht neu ermittelt, sondern nur die letzten Schaltungen ausgeführt (sofern die Bedingungen hierfür gegeben sind). Mit single wird lediglich der aufgerufene WeekdayTimer aktiviert, mit WDT_Group alle zur selben Gruppe gehörenden WeekdayTimer-Devices, und mit all werden schließlich alle Geräte des TPYEs WeekdayTimer.

weekprofile

Dieser set-Befehl kann ausschließlich dann genutzt werden, wenn in der Definition ein weekprofile-Device angegeben wurde. Die Syntax ist

weekprofile <weekprofile-device:topic:profile>

Dies bewirkt, dass die Daten des angegebenen Profil-Topics von dem weekprofile-Device abgerufen und unmittelbar als neues Profil genutzt werden. Nutzt man das Topic-feature bei weekprofile nicht, ist default als Topic anzugeben. Liefert weekprofile keine Daten zurück (Device oder Profile oder Topic existiert nicht), wird das bisherige Profil verwendet. Solange noch kein Profil angegeben wurde, wird "default:default" beim weekprofile-Device abgerufen und verwendet.

Attribute

delayedExecutionCond

Gibt eine Funktion an, mit der geprüft wird, ob ein anstehender Schaltbefehl verzögert werden soll. Wenn die Funktion wahr zurückgibt, wird der Befehl noch nicht ausgeführt; es wird jede Minute geprüft, ob die Bedingung noch wahr ist, solange, bis falsch zurückgegeben wird (wahr und falsch entsprechen dabei 0 und 1). Das Verhalten entspricht einem geöffneten Fensterkontakt.

Beispiel:

attr wd delayedExecutionCond isDelayed("$WEEKDAYTIMER","$TIME","$NAME","$EVENT")
   

Die Parameter $WEEKDAYTIMER(Name des WeekdayTimer), $TIME, $NAME(Zieldevice) und $EVENT werden bei der Abarbeitung mit den entsprechenden Werten ersetzt.

Beispiel einer Function:

   sub isDelayed($$$$) {
      my($wdt, $tim, $nam, $event ) = @_;

      my $theSunIsStillshining = ...

      return ($tim eq "16:30" && $theSunIsStillshining) ;
   }
   

WDT_delayedExecutionDevices

Leerzeichen-separierte Liste von Geräten (derzeit werden nur Tür- und Fensterkontakte unterstützt). Liefert eines der Geräte einen offen-Wert, wird der aktuelle Schaltbefehl verzögert.

WDT_Group

Mit diesem Attribut kann eine WeekdayTimer einer Gruppe zugeordnet werden, die dann zusammen mit set <ein Gruppendevice> WDT_Params WDT_Group geschaltet werden können. Dient v.a. dazu, für frühere Heating_Control-Geräte eine Funktionalität zu bieten, die dem Heating_Control_SetAllTemps()-Befehlsaufruf entspricht.

switchInThePast

Wenn auf "1" gesetzt, wird der letzte ein in der Vergangenheit liegende Timer auch beim Start oder Aktivieren des WeekdayTimer oder bei einer Änderung des Profils ausgeführt. Dient v.a. dazu, Temperaturprofile oder Heizungsgeräte sicher zu steuern; daher werden WeekdayTimer mit Zielgeräten, die als Heizung erkannt werden, auch automatisch so behandelt, als wäre switchInThePast gesetzt.

disable

Deaktiviert einen WeekdayTimer.

Anwendungsbeispiele

Generischer Modus

Rollladensteuerung

Einfaches Beispiel:

define shutter WeekdayTimer bath 12345|05:20|up 12345|20:30|down

Gibt dem Gerät "bath" Mo-Fr um 05:20 Uhr den Befehl "up", und um 20:30 Uhr den Befehl "down" (ggf. modifiziert durch das commandTemplate-Attribut). Fast dasselbe würde define shutter WeekdayTimer bath !$we|05:20|up !$we|20:30|down bewirken, allerdings wären Feiertage unter der Woche dabei ausgenommen.

Weiteres Beispiel, um Rollläden nach Zeitplan, aber mit Zusatzbedingungen zu schließen: siehe dieses Forenthema.

Lichtsteuerung

define dimmer WeekdayTimer livingRoom Sa-Su,We|07:00|dim30% Sa-Su,We|21:00|dim90% (ReadingsVal("WeAreThere", "state", "no") eq "yes")

Die Dimm-Anweisung dimXX% wird nur ausgeführt, wenn das state-Reading des Geräts WeAreThere auf "yes" steht. Einfache ein-Aus-Anweisungen:

define wd    Weekdaytimer  device de         mo-so, $we|{sunrise_abs_dat($date)}|on       mo-so, $we|{sunset_abs_dat($date)}|off
define wd    Weekdaytimer  device de         mo-so,!$we|{sunrise_abs_dat($date)}|aus      mo-so,!$we|{sunset_abs_dat($date)}|aus

Globale Tagesliste mit Perl-Aufruf

Beispiele:

define wd    Weekdaytimer device de  !$we     09:00|19  (function("Ein"))
define wd    Weekdaytimer device de   $we     09:00|19  (function("Ein"))
define wd    Weekdaytimer device de   78      09:00|19  (function("exit"))
define wd    Weekdaytimer device de   57      09:00|19  (function("exit"))
define wd    Weekdaytimer device de  fr,$we   09:00|19  (function("exit"))

disable-Attribut setzen aus readingsGroup

siehe dieses Forenthema Beachte: uU. kann das save nicht mehr aus der readingsGroup heraus ausgeführt werden.

Nutzung zur Heizungskontrolle

Einfache Heizungsdefinitionen

Einige Beispieldefinitionen:

define wd    Weekdaytimer  device de         7|23:35|25        34|23:30|22 23:30|16 23:15|22     8|23:45|16
define wd    Weekdaytimer  device de         fr,$we|23:35|25   34|23:30|22 23:30|16 23:15|22    12|23:45|16
define wd    Weekdaytimer  device de         20:35|25          34|14:30|22 21:30|16 21:15|22    12|23:00|16
define wd    Weekdaytimer  device de         {sunrise_abs_dat($date)}|19           {sunset_abs_dat($date)}|21
define wd    Weekdaytimer  device de         22:35|25  23:00|16

Zwei Schaltbefehle

define heatingBath WeekdayTimer bath 07:00|16 Mo,Tu,Th-Fr|16:00|18.5 20:00|eco {fhem("set dummy on"); fhem("set $NAME desired-temp $EVENT");}

Letzte Schaltbefehle erneut ausführen

Um z.B. bei Rückkehr aus oder auf dem Weg in den Urlaub (oder vom/zum Homeoffice usw.) einen, mehrere oder alle WeekdayTimer anzuweisen, ihren aktuellen Sollwert (erneut) an die Zieldevices zu senden, gibt es mehrere Möglichkeiten. Man kann die Funktion WeekdayTimer_SetParm("WD-device") oder WeekdayTimer_SetAllParms() nutzen, oder einen der oben beschriebenene set-Befehle (enable oder WDT_Params). Soll nur eine Teilmenge der WeekdayTimer geschaltet werden, kann das WDT_Group-Attribut gesetzt und WeekdayTimer_SetAllParms("<Gruppenname>") als Aufruf verwendet werden. Beispiel, wie das mit einem notify umgesetzt werden könnte:

define dummyNotify notify Dummy:. * {WeekdayTimer_SetAllParms()}

Zusammenspiel mit weekprofile

Mit dem Modul weekprofile können Temperaturprofile erstellt werden und für verschiedene Anlässe vorbereitet werden. WeekdayTimer kann diese Temperaturlisten verwenden. Dazu ist Voraussetzung, dass in der Definition das weekprofile-Device angegeben wird. Einfaches Beispiel ohne $we-Berücksichtigung (myWeekprofiles ist der Name des weekprofile-Devices):

define wd    Weekdaytimer  device weekprofile:myWeekprofiles

Dasselbe mit $we-Berücksichtigung:

define wd    Weekdaytimer  device weekprofile:myWeekprofiles:true

Dann kann mit

set wd weekprofile myWeekprofiles:holiday:livingrooms

das Profil livingrooms (mit Topic = holiday) angewendet werden.

Anmerkungen zum Gebrauch des weekprofile-features:

• Der set-Befehl kann nur erfolgreich ausgeführt werdne, wenn das <weekprofile-device> in der Definition des WeekdayTimers enthalten ist, das angegebene Device existiert und es unter der angegebenen topic:profile-Kombination Daten bereitstellt. Sollten Sie das topic feature in dem weekprofile-Gerät nicht nutzen, geben Sie dafür default an. Haben Sie ein weekprofile erfolgreich gesetzt, finden Sie die gesetzte Kombination in einem Reading namens weekprofiles, eventuel auch mehrere dieser Angaben, alls mehrere weekprofile-Geräte angegeben sein sollten (nicht empfohlen!).
• WeekdayTimer berechnet die Schaltzeiten für jeden Tag kurz nach Mitternacht, für weekprofile-gesteuerte WeekdayTimer wird daher als erster Schaltzeitpunkt 10 Minuten nach Mitternacht festgelegt.
• Der set ... weekprofile Aufruf wird auch durch das Modul weekprofile verwendet, um von dort aus den WeekdayTimer zur Neuberechnung der Schaltzeiten auf Basis des übermittelten Profils zu veranlassen. Dementssprechend ist

set wd weekprofile myWeekprofiles:holiday:livingrooms

gleichbedeutend mit dem weekprofile Kommando

set myWeekprofiles send_to_device holiday:livingrooms wd

Hearing_Control

Das unter Heating_Control aufgeführte Anwendungsbeispiel funktioniert 1:1 auch unter WeekdayTimer