diff --git a/stateengine/user_doc.rst b/stateengine/user_doc.rst index 58bf3d5ac..b9cdbf3b1 100755 --- a/stateengine/user_doc.rst +++ b/stateengine/user_doc.rst @@ -55,11 +55,5 @@ Das Webinterface bietet folgende Übersichtsinformationen: :alt: Web Interface Overview :align: center -Ein Klick auf das Lupensymbol in der Visu-Spalte öffnet die Detailansicht. Hier ist zu sehen, welcher Zustand eingenommen werden könnte, welcher aktiv ist und welche Aktionen bei welcher Bedingung ausgeführt werden. - - .. image:: user_doc/assets/webif_stateengine_detail.png - :height: 1656px - :width: 3312px - :scale: 25% - :alt: Web Interface Detail - :align: center +Ein Klick auf das Lupensymbol in der Visu-Spalte öffnet die Detailansicht. Hier ist zu sehen, welcher Zustand eingenommen werden könnte, welcher aktiv ist und welche Aktionen bei welcher Bedingung ausgeführt werden. Ein Beispiel ist in der +Sektion zu finden. diff --git a/stateengine/user_doc/01_allgemein.rst b/stateengine/user_doc/01_allgemein.rst index 896d0992a..bcae88653 100755 --- a/stateengine/user_doc/01_allgemein.rst +++ b/stateengine/user_doc/01_allgemein.rst @@ -69,15 +69,23 @@ Webinterface Über das Webinterface lässt sich auf einen Blick erkennen, welche State Engine sich in welchem Zustand befindet. Zusätzlich ist es möglich, durch Klick auf einen Eintrag die komplette State Engine visuell zu betrachten. Dabei ist folgende Farbkodierung zu beachten: + - grau: wurde nicht evaluiert (weil bereits ein höherrangiger Zustand eingenommen wurde) - grün: aktueller Zustand / ausgeführte Aktion - rot: Bedingungen nicht erfüllt +Innerhalb einer Bedingungsgruppe wird bei evaluierten Zuständen ein rotes X angezeigt, +wenn die Bedingung nicht wahr ist oder ein grünes Häkchen, falls die Bedingung erfüllt ist. + Bei den Aktionen sind die einzelnen Zeilen unter Umständen ebenfalls farbkodiert: + - schwarz: Aktion normal ausgeführt - weiß: Aktion nicht ausgeführt, da Bedingungen nicht erfüllt - grau: Aktion wird erst mit Verzögerung ausgeführt - rot: Fehler in der Konfiguration -.. image:: assets/webinterface.png +Zudem wird hinter ausgeführten Aktionen ein grünes Häkchen angezeigt, hinter nicht ausgeführten +(weil beispielsweise Bedingungen nicht erfüllt sind) ein rotes X und hinter Problemen ein Warnsignal. + +.. image:: assets/webif_stateengine_detail.png :class: screenshot diff --git a/stateengine/user_doc/02_konfiguration.rst b/stateengine/user_doc/02_konfiguration.rst index 90ea0f69f..5ae67824e 100755 --- a/stateengine/user_doc/02_konfiguration.rst +++ b/stateengine/user_doc/02_konfiguration.rst @@ -46,10 +46,11 @@ Logging Es gibt zwei Möglichkeiten, den Output des Plugins zu loggen: **intern** -Hierbei werden, sofern das Loglevel 1 oder 2 beträgt, sämtliche Logeinträge in +Hierbei werden, sofern das Loglevel 1 oder mehr beträgt, sämtliche Logeinträge in eigene Dateien in einem selbst definierten Verzeichnis geschrieben. Das Loglevel kann sowohl global in der etc/plugin.yaml Datei deklariert, als auch individuell pro Item mittels ``se_log_level`` (dort wo auch se_plugin: active steht) überschrieben werden. +Wird im Item nichts angegeben oder das Attribut mit dem Wert -1 angegeben, wird der Standardwert herangezogen. **logging.yaml** Sowohl der Output des Plugins generell, als auch der Einträge für bestimmte Items diff --git a/stateengine/user_doc/03_regelwerk.rst b/stateengine/user_doc/03_regelwerk.rst index ab841d13c..90cc18339 100755 --- a/stateengine/user_doc/03_regelwerk.rst +++ b/stateengine/user_doc/03_regelwerk.rst @@ -49,14 +49,18 @@ Diese Items müssen auf Ebene des Regelwerk-Items über das Attribut ``se_item_`` bekannt gemacht werden. Um einfacher zwischen Items, die für Bedingungen und solchen, die für Aktionen genutzt werden, unterscheiden zu können, können Items, die nur für Bedingungen gebraucht werden, mittels ``se_status_`` -deklariert werden. Diese Variante ist auch besonders dann relevant, wenn es zwei separate Items -für "Senden" und "Empfangen" gibt, also z.B. Senden der Jalousiehöhe und Empfangen des aktuellen -Werts vom KNX-Aktor. +deklariert werden. + +Anstatt direkt das Item in Form des absoluten oder relativen Pfades zu setzen, kann auch ein +eval-Ausdruck mittels ``eval:`` angegeben werden. -Anstatt direkt das Item in Form des absoluten oder relativen Pfades mittels ``se_item_`` zu -setzen, kann auch die Angabe ``se_eval_`` genutzt werden. In diesem Fall wird eine beliebige -Funktion anstelle des Itemnamen angegeben. Dies ist primär für das Setzen von "dynamischen" Items -gedacht, allerdings ist es auch möglich, hier einen beliebigen Eval-Ausdruck als Bedingung festzulegen. +.. hint:: + + Aus Kompatibilitätsgründen kann für das Setzen "dynamischer" Items auch die Angabe ``se_eval_`` + oder ``se_status_eval_`` genutzt werden. In diesem Fall wird eine beliebige + Funktion anstelle des Itemnamen angegeben, also beispielsweise + se_eval_height: se_eval.get_relative_item('..test'). Hierzu in den Kapiteln :ref:`Bedingungen` + und :ref:`Aktionen` mehr. Beispiel se_item @@ -64,12 +68,12 @@ Beispiel se_item Im Beispiel wird durch ``se_item_height`` das Item ``beispiel.raffstore1.hoehe`` dem Plugin unter dem Namen "height" bekannt gemacht. Das Item ``beispiel.wetterstation.helligkeit`` -wird durch ``se_item_brightness`` (alternativ via ``se_status_brightness``) als "brightness" referenziert. +wird durch ``se_item_brightness`` als "brightness" referenziert. Auf diese Namen beziehen sich nun in weiterer Folge Bedingungen und Aktionen. Im Beispiel wird im Zustand Nacht das Item ``beispiel.raffstore1.hoehe`` auf den Wert 100 gesetzt, sobald -``beispiel.wetterstation.helligkeit`` den Wert 25 übersteigt. Erklärungen zu Bedingungen -und Aktionen folgen auf den nächsten Seiten. +``beispiel.wetterstation.helligkeit`` den Wert 25 übersteigt. Erklärungen zu Bedingungen und +Aktionen folgen auf den nächsten Seiten. .. code-block:: yaml @@ -91,18 +95,41 @@ und Aktionen folgen auf den nächsten Seiten. enter_toodark: se_max_brightness: 25 +Beispiel se_status +================== + +Wie erwähnt, können Items, die nur für Bedingungen genutzt werden, auch mittels se_status deklariert +werden. Diese Variante ist aber auch besonders dann relevant, wenn es zwei separate Items +für "Senden" und "Empfangen" gibt, also z.B. Senden der Jalousiehöhe und Empfangen des aktuellen +Werts vom KNX-Aktor. + +Im Beispiel wird durch ``se_item_height`` das Item ``beispiel.raffstore1.hoehe`` (das den Befehl an den +KNX Aktor übermittelt) dem Plugin unter dem Namen "height" bekannt gemacht. ``se_status_height`` referenziert auf das +separate Status-Item (das vom KNX Aktor den Rückmeldestatus erhält) ``beispiel.raffstore1.hoehe.status``. +Dies ist aktuell insbesondere dann wichtig, wenn `se_mindelta_height`` genutzt wird (siehe :ref:`Aktionen`). + +.. code-block:: yaml + + raffstore1: + automatik: + struct: stateengine.general + rules: + se_item_height: beispiel.raffstore1.hoehe + se_status_height: beispiel.raffstore1.hoehe.status + se_mindelta_height: 10 + + Standard: + on_enter_or_stay: + se_action_height: + - 'function: set' + - 'to: 100' + + Beispiel se_eval ================ -se_eval ist für Sonderfälle und etwas komplexere Konfigurationen sinnvoll, kann aber -im ersten Durchlauf ignoriert werden. Es wird daher empfohlen, als Beginner -dieses Beispiel einfach zu überspringen ;) - -Im Beispiel wird durch ``se_eval_brightness`` das Item für den Check von -Bedingungen bekannt gemacht. Aufgrund der angegebenen Funktion wird das Item -abhängig vom aktuellen Zustandsnamen eruiert. Da Zustand_Eins den Namen "sueden" -hat, wird somit auch der Wert von wetterstation.helligkeit_sueden abgefragt. -Würde der Zustand "osten" heißen, würde der Helligkeitswert vom Osten getestet werden. +Im Beispiel werden zwei Helligkeitswerte addiert und das Resultat durch 2 geteilt +(also der Mittelwert gebildet). Das Resultat wird dann mit dem Wert 5000 verglichen. .. code-block:: yaml @@ -122,7 +149,7 @@ Würde der Zustand "osten" heißen, würde der Helligkeitswert vom Osten geteste automatik: struct: stateengine.general rules: - se_eval_brightness: se_eval.get_relative_itemvalue('wetterstation.helligkeit_{}'.format(se_eval.get_variable('current.state_name'))) + se_eval_brightness: (se_eval.get_relative_itemvalue('wetterstation.helligkeit_sueden') + se_eval.get_relative_itemvalue('wetterstation.helligkeit_osten'))/2 Zustand_Eins: name: sueden diff --git a/stateengine/user_doc/05_bedingungen.rst b/stateengine/user_doc/05_bedingungen.rst index c72b2e312..62c884579 100755 --- a/stateengine/user_doc/05_bedingungen.rst +++ b/stateengine/user_doc/05_bedingungen.rst @@ -26,6 +26,52 @@ die Helligkeit (über se_item_brightness oder se_status_brightness definiert) ü enter: se_min_brightness: 500 +Name der Bedingung +------------------ + +Der Name einer Bedingung setzt sich aus folgenden drei Teilen zusammen, +die jeweils mit einem Unterstrich "_" getrennt werden: + +- ``se_``: eindeutiger Prefix, um dem Plugin zugeordnet zu werden +- ````: siehe unten. Beispiel: min = der Wert des muss mindestens dem beim Attribut angegebenen Wert entsprechen. +- ````: Hier wird entweder das im Regelwerk-Item mittels ``se_item_`` oder ``se_status_`` deklarierte Item oder eine besondere Bedingung (siehe unten) referenziert. + + +Referenzieren von Items +----------------------- + +Für jede "standardmäßige" Bedingung muss ein Item hinterlegt werden, das geprüft werden soll. +Dies geschieht in der Regel durch ``se_status_``, kann aber auch durch ``se_item_`` +erfolgen, falls z.B. das gleiche Item für Bedingungen und Aktionen gebraucht wird. + +Im Beispiel wird durch ``se_status_brightness`` das Item für den Check von +Bedingungen bekannt gemacht. Aufgrund der angegebenen eval-Funktion wird das Item +abhängig vom aktuellen Zustandsnamen eruiert. Da Zustand_Eins den Namen "sueden" +hat, wird somit der Wert von wetterstation.helligkeit_sueden abgefragt. Ist dieser +mehr als 499, ist die Bedingung erfüllt. Würde der Zustand "osten" heißen (Name von Zustand_Zwei), +würde der Helligkeitswert vom Osten getestet werden. Bedingung wäre dann erfüllt, +wenn die Helligkeit 1500 oder mehr beträge. + +.. code-block:: yaml + + #items/item.yaml + raffstore1: + automatik: + struct: stateengine.general + rules: + se_status_brightness: eval:se_eval.get_relative_itemvalue('wetterstation.helligkeit_{}'.format(se_eval.get_variable('current.state_name'))) + + Zustand_Eins: + name: sueden + enter: + se_min_brightness: 500 + + Zustand_Zwei: + name: osten + enter: + se_min_brightness: 1500 + + Bedingungsgruppen ----------------- @@ -67,18 +113,6 @@ Der zu vergleichende Wert einer Bedingung kann auf folgende Arten definiert werd des StateEngine Items eingesetzt werden kann. Angegeben durch ``template:`` -Name der Bedingung ------------------- - -Der Name einer Bedingung setzt sich aus folgenden drei Teilen zusammen, -die jeweils mit einem Unterstrich "_" getrennt werden: - -- ``se_``: eindeutiger Prefix, um dem Plugin zugeordnet zu werden -- ````: siehe unten. Beispiel: min = der Wert des muss mindestens dem beim Attribut angegebenen Wert entsprechen. -- ````: Hier wird entweder das im Regelwerk-Item mittels ``se_item_`` -oder ``se_status_`` deklarierte Item oder eine besondere Bedingung (siehe unten) referenziert. - - Templates für Bedingungsabfragen -------------------------------- @@ -352,7 +386,7 @@ Freitag, 5 = Samstag, 6 = Sonntag Der Azimut (Horizontalwinkel) ist die Kompassrichtung, in der die Sonne steht. Der Azimut wird von smarthomeNg auf Basis der aktuellen Zeit sowie der konfigurierten geographischen Position -berechnet. Siehe auch `Dokumentation `_ +berechnet. Siehe auch `Dokumentation `_ für Voraussetzungen zur Berechnung der Sonnenposition. Beispielwerte: 0 → Sonne exakt im Norden, 90 → Sonne exakt im Osten, 180 → Sonne exakt im Süden, 270 → Sonne exakt im Westen @@ -363,8 +397,8 @@ Osten, 180 → Sonne exakt im Süden, 270 → Sonne exakt im Westen Die Altitude (Vertikalwikel) ist der Winkel, in dem die Sonne über dem Horizont steht. Die Altitude wird von smarthomeNG auf Basis der aktuellen Zeit sowie der konfigurierten geographischen -Position berechnet. Siehe auch `SmarthomeNG -Dokumentation `_ +Position berechnet. Siehe ebenfalls `SmarthomeNG +Dokumentation `_ für Voraussetzungen zur Berechnung der Sonnenposition. Werte: negativ → Sonne unterhalb des Horizonts, 0 → Sonnenaufgang/Sonnenuntergang, 90 → Sonne exakt im Zenith diff --git a/stateengine/user_doc/06_aktionen.rst b/stateengine/user_doc/06_aktionen.rst index 0182d969b..55d6b187c 100755 --- a/stateengine/user_doc/06_aktionen.rst +++ b/stateengine/user_doc/06_aktionen.rst @@ -9,8 +9,7 @@ Aktionen Es gibt zwei Möglichkeiten, Aktionen zu definieren. Die :ref:`Aktionen - einzeln` Variante wird am Ende der Dokumentation der Vollständigkeit halber beschrieben. Für einfache Aktionen ohne Angabe zusätzlicher Attribute wie delay, order, repeat, etc. -kann diese andere Möglichkeit der Aktionsangabe durchaus Sinn machen. Sie wurde -allerdings in der weiteren Pluginentwicklung nicht mehr getestet. +kann diese andere Möglichkeit der Aktionsangabe durchaus Sinn machen. Bei der hier beschriebenen kombinierten Variante zur Definition von Aktionen werden alle Parameter einer Aktion in einem Attribut definiert. Der Aktionsname ``se_action_`` @@ -29,7 +28,7 @@ das den Wert vom KNX-Aktor empfängt. Außerdem ist es möglich, über ``se_repeat_actions`` generell zu definieren, ob Aktionen für die Stateengine wiederholt ausgeführt werden sollen oder nicht. Diese Konfiguration -kann für einzelne Aktionen individuell über die Angabe ``repeat`` überschrieben werden. Siehe auch :ref:`Aktionen`. +kann für einzelne Aktionen individuell über die Angabe ``repeat`` überschrieben werden. Beispiel zu Aktionen -------------------- @@ -346,20 +345,20 @@ Die einzelnen Angaben einer Liste werden als ``OR`` evaluiert. .. code-block:: yaml -screens: - conditionset_to_check: - type: str - value: "screens.osten_s1.automatik.rules.abend.enter_abend" + screens: + conditionset_to_check: + type: str + value: "screens.osten_s1.automatik.rules.abend.enter_abend" - conditionset: - - regex:enter_(.*)_test - - eval:sh.screens.conditionset_to_check.property.name + conditionset: + - regex:enter_(.*)_test + - eval:sh.screens.conditionset_to_check.property.name Der gesamte Pfad könnte wie folgt evaluiert werden: .. code-block:: yaml - "eval:se_eval.get_relative_itemid('{}.'.format(se_eval.get_relative_itemvalue('..state_id')))" + "eval:se_eval.get_relative_itemid('{}.'.format(se_eval.get_relative_itemvalue('..state_id')))" Eine sinnvolle Anwendung hierfür wäre, anstelle von verschiedenen Zuständen mit leicht anderen Bedingungen, alles in einen Zustand zu packen und anhand des Conditionsets diff --git a/stateengine/user_doc/07_zeitpunkt.rst b/stateengine/user_doc/07_zeitpunkt.rst index dadb59360..98774cb2e 100755 --- a/stateengine/user_doc/07_zeitpunkt.rst +++ b/stateengine/user_doc/07_zeitpunkt.rst @@ -52,7 +52,7 @@ Die Konfiguration von instant_leaveaction bestimmt, ob on_leave Aktionen sofort eines Zustands ausgeführt werden oder erst am Ende der Statusevaluierung. Die Option kann sowohl in der globalen Pluginkonfiguration mittels ``instant_leaveaction`` (boolscher Wert True oder False), als auch pro Item -mittels ``se_instant_leaveaction``festgelegt werden. Letzteres Attribut kann auch +mittels ``se_instant_leaveaction`` festgelegt werden. Letzteres Attribut kann auch auf ein Item verweisen, dem der Wert -1 = Nutzen des Default Wertes, 0 = False, 1 = True zugewiesen werden kann. Im ``general struct`` sind bereits entsprechende Einträge und Items angelegt (mit einem Wert von -1). diff --git a/stateengine/user_doc/08_beispiel.rst b/stateengine/user_doc/08_beispiel.rst index c4767ab0b..8a300d35b 100755 --- a/stateengine/user_doc/08_beispiel.rst +++ b/stateengine/user_doc/08_beispiel.rst @@ -390,14 +390,14 @@ Beim zweiten Durchlauf wird somit der Zustand Sonnenschutz aktiviert. Der Raffst Let's play god. Ändern wir das Wetter ;) Entweder über das CLI, Visu oder Backend-Plugin oder Admin-Interface: -c) up beispiel.wetterstation.helligkeit=35000 +c) beispiel.wetterstation.helligkeit=35000 - Die erste Bedingungsgruppe des Sonnenstandzustands ist nicht mehr "wahr", da die Helligkeit zu niedrig ist. - Es wird ``enter_hysterese`` evaluiert. Da die Helligkeit noch über 25000 und die Sonnenposition gleich wie zuvor ist, ist diese Gruppe wahr. Der Sonnenschutz bleibt somit aktiv, weil trotz der Helligkeitsverringerung der untere Schwellwert noch überschritten wurde. Der Raffstore bleibt unten. -d) up beispiel.wetterstation.helligkeit=15000 +d) beispiel.wetterstation.helligkeit=15000 - Die ersten beiden Bedingungsgruppen sind unwahr, da die Helligkeit zu gering ist. - Durch den Eintrag ``se_agemax_brightnessGt25k: 60`` in der Gruppe ``enter_delay`` wird 60 Sekunden gewartet. @@ -411,13 +411,13 @@ e) Es erfolgt eine weitere Evaluierung des Automaten durch das cycle Attribut: Der Zustand wird verlassen. Gibt es einen nachfolgenden Zustand, der eingenommen werden kann, ist dies der neue aktive Zustand. Gibt es keine Zustände, die aktiviert werden könnten, verbleibt die State Engine beim letzten aktiven Zustand, also beim Sonnenschutz. Im Beispiel gibt es noch einen Standard "Tag" Eintrag, wodurch der Raffstore hoch fährt. -f) up beispiel.raffstore1.aufab = 1 +f) beispiel.raffstore1.aufab = 1 - Durch Triggern des "Manuell" Items wird die Zustandsevaluierung pausiert. Sämtliche Änderungen der Helligkeit, Temperatur, etc. werden für die suspend_time ignoriert. Die Dauer ist im Template auf 60 Minuten festgelegt, kann aber manuell durch Ändern des entsprechenden Items geändert werden. -g) up beispiel.raffstore1.automatik.settings.suspendduration = 1 +g) beispiel.raffstore1.automatik.settings.suspendduration = 1 - Die Suspendzeit wird auf eine Minute verkürzt. - Beim erneuten Durchlauf ist die Suspendzeit abgelaufen, daher dieser Zustand nicht mehr aktiv. @@ -639,7 +639,7 @@ Settings für Itemwerte ---------------------- Das Setup ist besonders flexibel, wenn zu setzende Werte nicht fix in den Zustandsvorgaben -definiert werden, sondern in eigenen Items, die dann jederzeit zur Laufzeit abänderbar +definiert werden, sondern in eigenen Items, die dann jederzeit zur Laufzeit änderbar sind. Das folgende Beispiel zeigt eine Leuchte, die abhängig vom aktuell definierten Lichtmodus (z.B. über die Visu) verschiedene Stati einnimmt und immer wieder dieselben Änderungen vornimmt. Sollte eine Änderung nicht möglich sein, weil das entsprechende @@ -649,8 +649,6 @@ Die Struct-Vorlagen sehen dabei folgendermaßen aus. Besonders ist der Eval Ausd Dieser führt dazu, dass der zu setzende Wert aus dem Item ``automatik.settings..sollwert`` im aktuellen Item gelesen wird. Somit kann diese Vorlage für sämtliche Zustände 1:1 eingesetzt werden, wobei natürlich zu beachten ist, dass sowohl "Settings" als auch Zustand richtig benannt sind. -Das Item state_name wird bis zur Pluginversion 1.5.0 erst nach Ausführen der Aktionen aktualisiert, -weshalb diese Vorgehensweise erst ab 1.5.1 empfohlen wird. .. code-block:: yaml @@ -758,7 +756,7 @@ Letzten Endes wird alles in einem item.yaml auf folgende Art und Weise implement - licht_rules_heimkino - licht_rules_lichtkurve - remark: Das eval_trigger muss vor SmarthomeNG 1.7 noch manuell mit der kompletten Liste überschrieben werden, auch wenn die Structs bereits Einträge enthalten. Ab 1.7 würde licht.modus* ausreichen! + remark: Das eval_trigger muss vor SmarthomeNG 1.7 noch manuell mit der kompletten Liste überschrieben werden, auch wenn die Structs bereits Einträge enthalten. Ab 1.7 würde merge_unique* und licht.modus* ausreichen! eval_trigger: - ..settings_edited - ..lock diff --git a/stateengine/user_doc/09_vorlagen.rst b/stateengine/user_doc/09_vorlagen.rst index bd72ebd68..68ce0409e 100755 --- a/stateengine/user_doc/09_vorlagen.rst +++ b/stateengine/user_doc/09_vorlagen.rst @@ -43,9 +43,7 @@ können wie folgt eingebunden werden: rules: eval_trigger: - - ..lock - - ..supsend - - .. release + - merge_unique* - beispiel.trigger additional_state1: @@ -63,81 +61,17 @@ general Die ``general`` Vorlage enthält die Items, die generell für einen Zustandsautomaten angelegt werden sollten. Das "rules" Item ist das Regelwerk-Item mit aktiviertem -se_plugin. Dieser Codeblock wird zwingend von jedem Zustandsautomaten benötigt. - -.. code-block:: yaml - - #stateengine.general - state_id: - # The id/path of the actual state is assigned to this item by the stateengine - type: str - visu_acl: r - cache: True - - state_name: - # The name of the actual state is assigned to this item by the stateengine - type: str - visu_acl: r - cache: True - - conditionset_id: - remark: The id/path of the actual condition set is assigned to this item by the stateengine - type: str - visu_acl: r - cache: True - - conditionset_name: - remark: The name of the actual condition set is assigned to this item by the stateengine - type: str - visu_acl: r - cache: True - - rules: - name: Regeln und Item Verweise für den Zustandsautomaten - type: bool - se_plugin: active - eval: True - - # se_startup_delay: 30 - # se_repeat_actions: true - # se_suspend_time: 7200 - - se_laststate_item_id: ..state_id - se_laststate_item_name: ..state_name - se_lastconditionset_item_id: ..conditionset_id - se_lastconditionset_item_name: ..conditionset_name +se_plugin. Außerdem werden zwei Settings Items angelegt, um das Log Level und +"Instant Leaveaction" per Item konfigurieren und zur Laufzeit ändern zu können. +Dieser Codeblock wird zwingend von jedem Zustandsautomaten benötigt. lock ==== Die ``state_lock`` Vorlage beinhaltet zum einen den Lock Zustand mit dem Namen "gesperrt", zum anderen ein Item mit dem Namen ``lock``. Wird dieses auf "1/True" gesetzt, wird der -Zustand eingenommen. Der Zustand sollte immer als erster Zustand eingebunden werden. - -.. code-block:: yaml - - #stateengine.state_lock - lock: - type: bool - knx_dpt: 1 - visu_acl: rw - cache: 'on' - - rules: - se_item_lock: ..lock - eval_trigger: - - ..lock - - lock: - name: gesperrt - - on_leave: - se_action_lock: - - 'function: set' - - 'to: False' - - enter: - se_value_lock: True +Zustand so lange eingenommen, bis das Item wieder auf False gestellt wird. So lässt sich zeitweise +die Evaluierung anderer Zustände pausieren. Der Zustand sollte immer als erster Zustand eingebunden werden. suspend ======= @@ -162,198 +96,19 @@ Setzt man das Item ``settings.suspend_active`` auf False, wird der Pause-Zustand deaktiviert und manuelle Betätigungen werden beim nächsten Durchlauf eventuell durch andere Zustände überschrieben. -.. code-block:: yaml +suspend_dynamic +=============== - #stateengine.state_suspend - state_suspend: - name: Zustandsvorlage für manuelles Aussetzen - - suspend: - type: bool - knx_dpt: 1 - visu_acl: rw - cache: True - - visu: - type: bool - knx_dpt: 1 - visu_acl: rw - cache: True - - suspend_end: - type: str - visu_acl: ro - eval: "'' if not any(char.isdigit() for char in sh..self.date_time()) else sh..self.date_time().split(' ')[1].split('.')[0]" - eval_trigger: .date_time - crontab: init - - date_time: - type: str - visu_acl: ro - cache: True - - unix_timestamp: - type: num - visu_acl: ro - eval: "0 if not any(char.isdigit() for char in sh...date_time()) else sh.tools.dt2ts(shtime.datetime_transform(sh...date_time())) * 1000" - eval_trigger: ..date_time - crontab: init - - suspend_start: - type: str - visu_acl: ro - eval: "'' if not any(char.isdigit() for char in sh..self.date_time()) else sh..self.date_time().split(' ')[1].split('.')[0]" - eval_trigger: .date_time - crontab: init - - date_time: - type: str - visu_acl: ro - cache: True - - unix_timestamp: - remark: Can be used for the clock.countdown widget - type: num - visu_acl: ro - eval: "0 if not any(char.isdigit() for char in sh...date_time()) else sh.tools.dt2ts(shtime.datetime_transform(sh...date_time())) * 1000" - eval_trigger: ..date_time - crontab: init - - manuell: - type: bool - name: manuell - se_manual_invert: True - remark: Adapt the se_manual_exclude the way you need it - #se_manual_include: KNX:* Force manual mode based on source - se_manual_exclude: - - database:* - - init:* - - retrigger: - remark: Item to retrigger the rule set evaluation - type: bool - visu_acl: rw - enforce_updates: True - on_update: ..rules = True - - settings: - remark: Use these settings for your condition values - type: foo - eval: (sh..suspendduration(sh..suspendduration(), "Init", "Start"), sh..suspendvariant.suspendduration0(sh..suspendduration(), "Init", "Start"), sh..suspendvariant.suspendduration1(sh..suspendvariant.suspendduration1(), "Init", "Start"), sh..suspendvariant.suspendduration2(sh..suspendvariant.suspendduration2(), "Init", "Start")) - crontab: init = True - - suspendduration: - remark: duration of suspend mode in minutes (gets converted automatically) - type: num - visu_acl: rw - cache: True - initial_value: 60 - on_change: .seconds = value * 60 if not sh..self.property.last_change_by == "On_Change:{}".format(sh..seconds.property.path) else None - on_update: .seconds = value * 60 if "Init" in sh..self.property.last_update_by else None - - duration_format: - remark: Can be used for the clock.countdown widget - type: str - cache: True - visu_acl: ro - eval: "'{}d {}h {}i {}s'.format(int(sh...seconds()//86400), int((sh...seconds()%86400)//3600), int((sh...seconds()%3600)//60), round((sh...seconds()%3600)%60))" - eval_trigger: - - ..seconds - - .. - - seconds: - remark: duration of suspend mode in seconds (gets converted automatically) - type: num - visu_acl: rw - cache: True - on_change: .. = value / 60 if not sh..self.property.last_change_by in [ "On_Change:{}".format(sh....property.path), "On_Update:{}".format(sh....property.path)] else None - - suspend_active: - remark: Use this to (de)activate suspend mode in general - type: bool - visu_acl: rw - cache: True - initial_value: True - - settings_edited: - type: bool - name: settings editiert - eval_trigger: ...settings.* - eval: not sh..self() - on_update: ...retrigger = True if sh..self.property.prev_update_age > 0.1 else None - - rules: - se_item_suspend: ..suspend - se_item_suspend_visu: ..suspend.visu - se_item_suspend_end: ..suspend_end.date_time - se_item_suspend_start: ..suspend_start.date_time - se_item_suspend_active: ..settings.suspend_active - se_suspend_time: ..settings.suspendduration - - eval_trigger: - - ..manuell - - suspend: - name: ausgesetzt - - on_enter: - se_action_suspend_visu: - - 'function: set' - - 'to: True' - - 'order: 2' - - on_enter_or_stay: - se_action_suspend: - - 'function: special' - - 'value: suspend:..suspend, ..manuell' - - 'repeat: True' - - 'order: 1' - se_action_suspend_end: - - 'function: set' - - "to: eval:se_eval.insert_suspend_time('..suspend', suspend_text='%Y-%m-%d %H:%M:%S.%f%z')" - - 'repeat: True' - - 'order: 3' - se_action_suspend_start: - - 'function: set' - - "to: eval:str(shtime.now())" - - 'repeat: True' - - 'conditionset: enter_manuell' - - 'order: 4' - se_action_retrigger: - - 'function: special' - - 'value: retrigger:..retrigger' - - 'delay: var:item.suspend_remaining' - - 'repeat: True' - - 'order: 5' - - on_leave: - se_action_suspend: - - 'function: set' - - 'to: False' - - 'order: 2' - se_action_suspend_visu: - - 'function: set' - - 'to: False' - - 'order: 3' - se_action_suspend_end: - - 'function: set' - - 'to: ' - - 'order: 4' - se_action_suspend_start: - - 'function: set' - - 'to: ' - - 'order: 5' - - 'delay: 1' - - enter_manuell: - se_value_trigger_source: eval:se_eval.get_relative_itemproperty('..manuell', 'path') - se_value_suspend_active: True - - enter_stay: - se_value_laststate: var:current.state_id - se_agemax_suspend: var:item.suspend_time - se_value_suspend: True - se_value_suspend_active: True +Eine Variante des Suspendmodus, bei dem es möglich ist, bis zu drei verschiedene +Suspendzeiten zu deklarieren. Außerdem kann man definieren, ob noch zusätzliche Zustände +integriert werden sollen. Dabei ist zu beachten, dass standardmäßig der "Standard"-Status +mit eingebunden wird. Da dieser leer ist, wird nichts passieren. Bei Bedarf kann der Wert +in den Items ``automatik.settings.suspendvariant.additionaluse[0-2]`` geändert werden. + +Welche Zeiten und Zustände letztlich genutzt werden, wird durch Setzen des Items +``suspendvariant`` bestimmt. Der Wert muss zwischen 0 und 2 liegen. + +Weitere Informationen sind unter :ref:`Besondere Zustände` zu finden. release ======= @@ -362,54 +117,11 @@ Die ``state_release`` Vorlage ist nicht unbedingt nötig, kann aber dazu genutzt schnell den Sperr- oder Pause-Zustand zu verlassen und die erneute Evaluierung der Zustände anzuleiern. -.. code-block:: yaml - - #stateengine.state_release - release: #triggers the release - type: bool - knx_dpt: 1 - visu_acl: rw - enforce_updates: True - - rules: - se_item_lock: ..lock - se_item_suspend: ..suspend - se_item_retrigger: ..rules - se_item_release: ..release - se_item_suspend_end: ..suspend_end - eval_trigger: - - ..release - - release: - name: release - - on_enter_or_stay: - se_action_suspend: - - 'function: set' - - 'to: False' - - 'order: 1' - se_action_lock: - - 'function: set' - - 'to: False' - - 'order: 2' - se_action_release: - - 'function: set' - - 'to: False' - - 'order: 3' - se_action_suspend_end: - - 'function: set' - - 'to: ' - - 'order: 4' - se_action_retrigger: - - 'function: set' - - 'to: True' - - 'order: 5' - - 'repeat: True' - - 'delay: 1' - - enter: - se_value_release: True +standard +======== +Ein praktisch leerer Status, der immer am Ende angehängt werden sollte. Dieser Status wird +eingenommen, wenn keine Bedingungen der anderen Stati erfüllt sind. Pluginspezifische Templates --------------------------- diff --git a/stateengine/user_doc/11_sonderzustaende.rst b/stateengine/user_doc/11_sonderzustaende.rst index c59f12456..bda77918c 100755 --- a/stateengine/user_doc/11_sonderzustaende.rst +++ b/stateengine/user_doc/11_sonderzustaende.rst @@ -284,8 +284,37 @@ abweichend sein soll, kann dort das Attribut angegeben werden. Der Parameter kann auch durch ein Item oder eval festgelegt werden. Letzteres ermöglicht es, je nach Situation die Suspenddauer von verschiedenen Items -abhängig zu machen. Im struct ``state_suspend_dynamic`` wird hier das Item automatik.settings.suspendduration.seconds verknüpft bzw. -für die verschiedenen "suspendvariants" automatik.settings.suspendvariant.suspendduration[0-2].seconds. +abhängig zu machen. Im struct ``state_suspend_dynamic`` wird hier das +Item automatik.settings.suspendduration.seconds verknüpft bzw. +für die verschiedenen "suspendvariants" die Items automatik.settings.suspendvariant.suspendduration[0-2].seconds. Hierzu ist im struct ein Item settings.suspendvariant integriert, das einen numerischen Wert zwischen 0 und 2 erwartet. 0 ist dabei die "normale" Funktionsweise, eine 1 würde auf die duration1 und eine 2 auf die duration2 verweisen. + +Um diese unterschiedlichen Dauerangaben zu nutzen, ist der Wert von suspendvariant in den entsprechenden +Zuständen zu setzen. Außerdem sollte beim Beenden des Suspendstatus der Wert wieder auf 0 oder den +vorherigen Wert gesetzt werden (was im entsprechenden Struct auch passiert). + +.. code-block:: yaml + + #items/item.yaml + beispiel: + raffstore1: + automatik: + struct: + - stateengine.general + - stateengine.state_release + - stateengine.state_lock + - stateengine.state_suspend_dynamic + - beschattung_se_state_abend + - beschattung_se_state_nacht + - beschattung_se_state_schnee + - beschattung_se_state_standard + + rules: + nacht: + on_leave: + se_set_suspendvariant: 1 + schnee: + on_leave: + se_set_suspendvariant: 2 diff --git a/stateengine/user_doc/12_aktioneneinzeln.rst b/stateengine/user_doc/12_aktioneneinzeln.rst index 62a88a809..9363459ae 100755 --- a/stateengine/user_doc/12_aktioneneinzeln.rst +++ b/stateengine/user_doc/12_aktioneneinzeln.rst @@ -46,12 +46,12 @@ Einziger Unterschied ist, dass die Wertänderung erzwungen wird: Wenn das Item bereits den zu setzenden Wert hat, dann ändert smarthomeNG das Item nicht. Selbst wenn beim Item das Attribut ``enforce_updates: yes`` gesetzt ist, wird zwar der Wert neu -gesetzt, der von smarthomeNG die Änderungszeit nicht neu gesetzt. Mit +gesetzt, aber nicht die Änderungszeit. Mit dem Attribut ``se_force_`` wird das Plugin den Wert des Items bei Bedarf zuerst auf einen anderen Wert ändern und dann auf dem Zielwert setzen. Damit erfolgt auf jeden Fall eine Wertänderung (ggf. sogar zwei) mit allen damit in Zusammenhang -stehenden Änderungen (eval's, Aktualisierung der Änderungszeiten, +stehenden Änderungen (evals, Aktualisierung der Änderungszeiten, etc). **Aktion run: Ausführen einer Funktion** @@ -164,7 +164,7 @@ Aktion ausgeführt werden soll. Die Angabe erfolgt in Sekunden oder mit dem Suffix "m" in Minuten. Der Timer zur Ausführung der Aktion nach der angegebenen -Verzögerung wird entfernt, wenn eine gleichartike Aktion +Verzögerung wird entfernt, wenn eine gleichartige Aktion ausgeführt werden soll (egal ob verzögert oder nicht). Wenn also die Verzögerung größer als der ``cycle`` ist, wird die Aktion nie durchgeführt werden, es sei denn die Aktion soll nur diff --git a/stateengine/user_doc/assets/webif_stateengine_detail.png b/stateengine/user_doc/assets/webif_stateengine_detail.png old mode 100755 new mode 100644 index a3dccc55d..817b27003 Binary files a/stateengine/user_doc/assets/webif_stateengine_detail.png and b/stateengine/user_doc/assets/webif_stateengine_detail.png differ diff --git a/stateengine/user_doc/assets/webinterface.png b/stateengine/user_doc/assets/webinterface.png deleted file mode 100755 index 5427b61c0..000000000 Binary files a/stateengine/user_doc/assets/webinterface.png and /dev/null differ