Modul YAAHM

YAAHM
Zweck / Funktion
Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface die zyklische Ausführung von Kommandos - mit Tages- und Wochenprofil - zu konfigurieren
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	Unterstuetzende Dienste
Modulname	95_YAAHM.pm
Ersteller	Prof. Dr. Peter A. Henning
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_YAAHM.pm.

Allgemeines

Das Modul 95_YAAHM.pm stellt eine komfortable Oberfläche bereit, um per Webinterface die zyklische Ausführung von Kommandos - mit Tages- und Wochenprofil - zu konfigurieren. Der Titel YAAHM ist das Akronym für Yet Another Auto Home Module, denn es gibt ja schon verschiedene Module, die den Zeitablauf in einem SmartHome vereinfachen sollen. Warum also noch Eines ?

Ganz einfach: Die Philosophie von YAAHM ist die einfache Bedienbarkeit im Frontend, mit Eingabefeldern und Visualisierungselementen - statt dabei Unmengen von Attributen zu setzen. Dafür gibt es verschiedene Begriffe zu verstehen.

Tages-Typ

Ohne weitere Angaben unterscheidet YAAHM die beiden Tagestypen Wochenende und Werktag. Durch das Setzen der Attribute vacationDevices und holidayDevices, die jeweils eine komma-separierte Liste aus holiday-Devices oder Calendar-Devices sein können, holt YAAHM sich jeden Morgen kurz nach Mitternacht noch weitere Informationen. Nämlich, ob es sich um einen Ferientag (vacation) oder einen Feiertag (holiday) handelt. Der letztendliche Tagestyp wird dann in einer Priorisierung festgelegt: Feiertag hat die höchste Priorität, gefolgt von Wochenende, Ferientag und Werktag.

Für jedes Wochen-Profil kann man angeben, ob es auch an einem Ferientag (=Fer) und an einem Feiertag (=Fei) gültig sein soll, siehe Wochen-Profile.

Tages-Profil

Das Tagesprofil besteht aus einer Kette von Ereignissen (Events), die an jedem Tag zeitgesteuert ablaufen. Welcher Event als letztes durchgeführt wurde, steht im Reading housetime, der vorhergehende Event im Reading prev_housetime und der vom gegenwärtigen Zeitpunkt aus nächste Event im Reading next_housetime. Für jedes Event kann eine Liste von FHEM-Kommandos angegeben werden, die dann ausgeführt werden.

Das Modul ermöglicht mit dem Attribut timeHelper die Angabe einer Perl-Hilfsfunktion, die zu jedem Event mit den entsprechenden Argumenten aufgerufen wird, siehe Attribute

Die vordefinierten Events umfassen

• Nach Mitternacht und Vor Mitternacht (aftermidnight, beforemidnight) sind Events, die mit einem Offset an jedem Tag nach bzw. vor Mitternacht ausgeführt werden.
• Sonnenaufgang, Vor Sonnenaufgang und Nach Sonnenaufgang (sunrise, beforesunrise, aftersunrise) sind Events, die an jedem Tag zu Sonnenaufgang bzw. mit einem Offset davor und danach ausgeführt werden. Der Zeitpunkt des Sonnenaufgangs wird aus dem Modul 95_Astro.pm berechnet.
• Sonnenuntergang, Vor Sonnenuntergang und Nach Sonnenuntergang (sunset, beforesunset, aftersunset) sind Events, die an jedem Tag zu Sonnenuntergang bzw. mit einem Offset davor und danach ausgeführt werden. Der Zeitpunkt des Sonnenuntergangs wird aus dem Modul 95_Astro.pm berechnet.
• Morgen, Mittag, Nachmittag, Abend und Nacht (morning, noon, afternoon, evening, night) sind Events, die zu einer einstellbaren Zeit an jedem Tag ausgeführt werden. Das Reading housephase nimmt zwischen Morgen und Nacht den Wert Tageszeit an, sonst den Wert Nachtzeit.
• Wecken und Schlafen (wakeup, sleep) sind Events, die durch die beiden Standard-Wochenprofile gleichen Namens ausgelöst werden. Die entsprechenden Zeiten können von Tag zu Tag beliebig variieren.

Wochen-Profile

Jedes Wochenprofil besteht aus einem Ereignis (Event) je Wochentag. Für dieses Event kann eine Liste von FHEM-Kommandos angegeben werden, die dann ausgeführt werden. Zwei Standard-Wochenprofile Wecken und Schlafen sind vordefiniert und können nicht gelöscht werden. Eine beliebige Anzahl weiterer Wochenprofile kann angelegt und wieder gelöscht werden.

Das Modul ermöglicht mit dem Attribut timeHelper die Angabe einer Perl-Hilfsfunktion, die für die beiden ersten (Standard-)Wochenprofile bei Eintritt des Events mit den entsprechenden Argumenten aufgerufen wird, siehe Attribute.

Für jedes Wochenprofil kann eine manuelle Auslösezeit eingegeben werden. Ist diese später als der gegenwärtige Zeitpunkt, wird sie für den aktuellen Tag verwendet. Ist diese früher als der gegenwärtige Zeitpunkt, wird sie erst am nächsten Tag als Ausnahmezeit verwendet.

(Nutzungs-)Modus

Der housemode (bzw. (Nutzungs-)Modus) besagt, dass sich das SmartHome in einem der drei Modi Normal, Party oder Abwesenheit befindet. Dabei bedeutet:

• Normal = normale Tages- und Wochen-Profile werden angewandt, keine speziellen Anordnungen.
• Party = kann in Hilfsfunktionen verwendet werden, um spezielle Anordnungen betreffend die Sicherheit und den Übergang in den Nachtzustand zu realisieren. Das Modul selbst sorgt dafür, dass im Party-Modus das SmartHome nicht in einen gesicherten Zustand versetzt werden kann.
  • Abwesenheit = kann in Hilfsfunktionen verwendet werden, um spezielle Anordnungen zu realisieren.

Die Festsetzung des Modus bleibt bestehen, bis eine erneute manuelle Änderung durchgeführt wird. Ausnahme: Wenn das Attribut modeAuto gesetzt wird, kann sich der Modus auch bei bestimmten Events ändern. Für jedes Wochen-Profil kann man angeben, ob es auch im Party-Modus (=Par) und bei Abwesenheit (=Abw) gültig sein soll, siehe [#Einrichtung der Wochen-Profile | Wochen-Profile].

Das Modul ermöglicht mit dem Attribut modeHelper die Angabe einer Perl-Hilfsfunktion, die zu jedem Wechsel des Modus mit den entsprechenden Argumenten aufgerufen wird, siehe Attribute

(Sicherheits-)Zustand

Der housestate (bzw. (Sicherheits-)Zustand) besagt, dass sich das SmartHome in einem der vier Zustände Nicht gesichert, Gesichert, Geschützt oder Überwacht befindet. Die Festsetzung des Zustands bleibt bestehen, bis eine erneute manuelle Änderung durchgeführt wird. Ausnahme: Wenn das Attribut stateAuto gesetzt wird, kann sich der Zustand auch bei bestimmten Events ändern. Dabei bedeutet:

• • Nicht gesichert =
  • Gesichert =
  • Geschützt =
  • Überwacht =

Das Modul ermöglicht mit dem Attribut stateHelper die Angabe einer Perl-Hilfsfunktion, die zu jedem Wechsel des Zustands mit den entsprechenden Argumenten aufgerufen wird, siehe Attribute

YAAHM-Device

Definition

Das YAAHM_Device - hier mit dem Namen YYY versehen - selbst wird über

define YYY YAAHM

definiert. Diese Definition legt einen versteckten Raum "ProfileRoom" an, welcher über einen Weblink im oberen Menü des Webinterfaces erreichbar ist.

• Der Name dieses Raumes kann durch das Attribut hiddenRoom geändert werden.
• Dieses Modul verwendet das globale Attribut language zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten muss in FHEM das Attribut

attr global language DE

gesetzt werden. Für dieses Wiki werden die deutschen Ausgabedaten verwendet.

Beim Anklicken des Begriffes Profile (eben der genannte Weblink) im oberen Menü des Webinterfaces wird dieser versteckte Raum angezeigt. Er enthält an erster Stelle das YAAHM-Device. Für die Konfiguration dieses Devices siehe den nächsten Abschnitt, für die Bedienung siehe den Abschnitt [Bedienung].

Set-Befehle

Das YAAHM-Device kennt die folgenden Set-Befehle (YYY ist duch den tatsächlichen Device-Namen zu ersetzen):

set YYY time (after|before)midnight | [before|after]sunrise | [before|after]sunset | morning | noon | afternoon | evening | night | wakeup | sleep

Erzeugt manuell den entsprechenden Event.

set YYY manualnext <timernumber> <time>
set YYY manualnext <timername> <time>

Setzt die manuelle Auslösezeit für den Wochen-Timer, der durch die Angabe einer fortlaufenden Nummerierung (beginnend bei 0) oder seinen Namen identifiiert wird.

set YYY mode normal | party | absence

Setzt den (Nutzungs-)Modus des SmartHome

set YYY state unsecured | secured | protected | guarded

Setzt den (Sicherheits-)Zustand des SmartHome

set YYY createWeekly <string>
set YYY deleteWeekly <string>

Erzeuge oder entferne ein Wochen-Profil mit dem entsprechenden Namen.

set YYY locked  |unlocked

Sperre oder entsperre das Überschreiben der Timer, siehe Sperrung.

Get-Befehle

Das YAAHM-Device kennt die folgenden Get-Befehle (YYY ist duch den tatsächlichen Device-Namen zu ersetzen):

 get YYY version

Gibt die Versionsnummer des Modul szurück

get YYY template

Gibt Vorschläge für Helferfunktionen zurück.

Attribute

• Wenn das Attribut timeHelper auf einen Perl-Funktionsnamen gesetzt wird, erfolgt automatisch der Eintrag des Perl-Funktionsnamens in das Aktionsfeld für das Tages-Profil und die Aktionsfelder der beiden ersten (=Standard-)Wochenprofile, verbunden mit dem Argument des entsprechenden Events. Einen entsprechenden Vorschlag für eine solche Helferfunktion kann man sich durch get YYY template anzeigen lassen.

• Wenn das Attribut modeHelper auf einen Perl-Funktionsnamen gesetzt wird, erfolgt automatisch die Ausführung dieser Funktion (verbunden mit dem Argument des entsprechenden Events) bei einem Wechsel des (Nutzungs-)Modus. Einen entsprechenden Vorschlag für eine solche Helferfunktion kann man sich durch get YYY template anzeigen lassen.
• Wenn das Attribut modeAuto' auf 1 gesetzt wird, wechselt der (Nutzungs-)Modus automatisch zu bestimmten Events:
  • Die Events sleep und morning bewirken, dass der Modus Party aufgehoben wird und wieder Normal ist.
  • Der Event wakeup bewirkt, dass der Modus Abwesenheit aufgehoben wird und wieder Normal ist.

• Wenn das Attribut stateHelper auf einen Perl-Funktionsnamen gesetzt wird, erfolgt automatisch die Ausführung dieser Funktion (verbunden mit dem Argument des entsprechenden Events) bei einem Wechsel des (Sicherheits-)Zustands. Einen entsprechenden Vorschlag für eine solche Helferfunktion kann man sich durch get YYY template anzeigen lassen.
• Wenn das Attribut stateAuto' auf 1 gesetzt wird, wechselt der (Sicherheits-)Zustand automatisch zu bestimmten Events:
  • Wenn der Modus Normal ist und der Zustand Nicht gesichert ist, wird bei Eintritt der Events sleep oder night der Zustand auf Gesichert gesetzt.
  • Wenn der Modus Party durch den Event sleep verlassen wurde, und der Zustand Nicht gesichert ist, wird der Zustand auf Gesichert gesetzt.

• linkname ist der Name für den Link im FHEM-Menü. Default: Profile.
• hiddenroom ist der Name für den versteckten Raum, der das YAAHM-Device enthält. Default: ProfileRoom
• lockstate ist der Sperrzustand für das Device, siehe Sperrung
• Wenn dass Attribut simulation auf 1 gesetzt wird, werden die Kommandos in den Aktionsfeldern nicht ausgeführt, sondern nur eine Log-Meldung geschrieben.

Webinterface

In diesem Abschnitt wird die Bedienung des Webinterfaces und damit die Konfiguration der Hausautomatik beschrieben. Um sie zu erreichen, klickt man auf den Begriff Profile im oberen Menü des Webinterfaces.

Das Webinterface teilt sich in zwei Abschnitte: Die Übersicht (oder toptable), bestehend aus den beiden Flächen Aktion und Zusammenfassung, sowie die Profilbereiche. Die Übersicht lässt sich auch separat als Weblink <YAAHM_Device-Name>_shortlink in einen beliebigen FHEM-Raum einbinden.

Aktion

Zusammenfassung

Hier werden in nicht-editierbarer Form die wichtigsten Daten für den gegenwärtigen und den darauffolgenden Tag angezeigt

Das YAAHM-Widget

Dabei handelt es sich um eine dynamisch erzeugte SVG-Datei, die man auch in beliebige eigene Webseiten einbinden kann. Der Aufruf dafür lautet

<IP-Adresse:Port>/fhem/YAAHM_timewidget?name='<Device-Name>'&size='<breite>x<höhe>'

Selbstverständlich kann man das auch in einen eigenen Weblink einbauen. Markiert sind auf diesem Kreis die housetime-Events Sonnenaufgang, Morgen, Mittag, Nachmittag, Abend, Sonnenuntergang und Nacht. Die Tageszeit ist ferner durch einen türkisfarbenen Sektor gekennzeichnet, und Mitternacht ist immer "unten".

Die gegenwärtige Zeit (beim Aufruf !) wird in rot angezeigt.

Hinweis: Es ist angedacht, dieses Widget noch sehr viel interaktiver zu machen.

Einstellung des Tages-Profils

• Der Startbutton erzeugt einen externen Timer (mit dem DOIF-Modul), der auf die Zeiten der definierten housetime-Events zugreift.
• Wenn dieser Timer erzeugt wurde, zeigt das Webinterface den entsprechenden Link an. Ein grüner Haken bedeutet, dass der Timer aktiv (enabled) ist, wenn er deaktiviert wurde (disabled), wird ein rotes Kreuz angezeigt.
• Die Aktionsfelder enthalten jeweils eine komma-getrennte List von FHEM-Befehlen, die bei Eintreten des Timer-Events abgearbeitet wird.
• Wenn das Attribut timeHelper auf einen Perl-Funktionsnamen gesetzt wird, erfolgt automatisch der Eintrag des Perl-Funktionsnamens in das Aktionsfeld, verbunden mit dem Argument des entsprechenden Events.

Einstellung der Wochen-Profile

• Der Startbutton erzeugt externe Timer (mit dem DOIF-Modul), die auf das Reading ring_<timer-no> zugreifen. Dieses Reading wird jeweils kurs nach Mitternacht auf den korrekten Wert für den entsprechenden Tag gesetzt.
• Wenn diese Timer erzeugt wurden, zeigt das Webinterface den entsprechenden Link an. Ein grüner Haken bedeutet, dass der Timer aktiv (enabled) ist, wenn er deaktiviert wurde (disabled), wird ein rotes Kreuz angezeigt.
• Die Checkboxen Par und Abw geben an, ob das betreffende Wochen-Profil (und damit der Timer) auch in den Modi Party und Abwesenheit aktiv ist. Die Checkboxen Fer und Fei geben an, ob das betreffende Wochen-Profil (und damit der Timer) auch an den Tagestypen Ferientag und Feiertag aktiv ist.
• Die Aktionsfelder enthalten jeweils eine komma-getrennte List von FHEM-Befehlen, die bei Eintreten des Timer-Events abgearbeitet wird.
• Wenn das Attribut timeHelper auf einen Perl-Funktionsnamen gesetzt wird, erfolgt bei den beiden ersten (=Standard-) Timern automatisch der Eintrag des Perl-Funktionsnamens in das Aktionsfeld, verbunden mit dem Argument wakeup oder sleep.

Sonstiges

Sperrung

Das Reading lockstate muss den Wert unlocked haben, damit durch Anklicken der Start-Buttons für die Timer diese auch gestartet werden. Das ist in der Regel beim ersten Laden des Moduls nicht der Fall, hierzu muss also das Reading von Hand auf den richtigen Wert gesetzt werden. Dazu muss der Befehl set ... unlocked ausgeführt werden.