Aktionen

Es gibt zwei Möglichkeiten, Aktionen zu definieren. Die Aktionen - einzeln Variante wird am Ende der Dokumentation der Vollständigkeit halber beschrieben, kann aber ignoriert werden.

Bei der hier beschriebenen kombinierten Variante zur Definition von Aktionen werden alle Parameter einer Aktion in einem Attribut definiert. Der Aktionsname se_action_<Bedingungsname/Aktionsname> bezieht sich dabei auf das Item, das über se_item_<Bedingungsname/Aktionsname> unter dem Regelwerk-Item definiert und benannt wurde. Die Herangehensweise ähnelt also stark der Deklaration von Bedingungen.

Zusätzlich zu se_item_<Bedingungsname/Aktionsname> lässt sich über den Eintrag se_mindelta_<Bedingungsname/Aktionsname> definieren, um welchen Wert sich ein Item mindestens geändert haben muss, um neu gesetzt zu werden. Im unten stehenden Beispiel wird der Lamellenwert abhängig vom Sonnenstand berechnet. Ohne mindelta würden sich die Lamellen ständig um wenige Grad(bruchteile) ändern. Wird jedoch mindelta beispielsweise auf den Wert 10 gesetzt, findet eine Änderung erst statt, wenn sich der errechnete Wert um mindestens 10 Grad vom aktuellen Lamellenwert unterscheidet.

Beispiel zu Aktionen

Das folgende Beispiel führt je nach Zustand folgende Aktionen aus:

  • Daemmerung: Höhe des Raffstores: 100(%), Lamellendrehung: 25(%)
  • Nachfuehren: Höhe des Raffstores: 100(%), Lamellendrehung: je nach Sonnenausrichtung, aber erst, wenn eine Mindeständerung von 10 Grad vorhanden ist.
  • Sonder: Ausführen der Logic myLogic mit dem Wert 42 und einer Verzögerung von 10 Sekunden.
#items/item.yaml
raffstore1:
    automatik:
        struct: stateengine.general
        rules:
            se_item_height: raffstore1.hoehe # Definition des zu ändernden Höhe-Items
            se_item_lamella: raffstore1.lamelle # Definition des zu ändernden Lamellen-Items
            se_mindelta_lamella: 10 # Mindeständerung von 10 Grad, sonst werden die Lamellen nicht aktualisiert.
            Daemmerung:
                <...>
                se_action_height:
                    - 'function: set'
                    - 'to: value:100'
                se_action_lamella:
                    - 'function: set'
                    - 'to: value:25'
                <...>
            Nachfuehren:
                <...>
                se_action_height:
                    - 'function: set'
                    - 'to: value:100'
                se_action_lamella:
                    - 'function: set'
                    - 'to: eval:se_eval.sun_tracking()'
                <...>
            Sonder:
                <...>
                se_action_logic1:
                    - 'function: trigger'
                    - 'logic: myLogic'
                    - 'value: 42'
                    - 'delay: 10'
                <...>

Aufbau von Aktionen

Bei yaml Files werden die Parameter mittels Aufzählungszeichen „-“ untereinander definiert, die Listeneinträge müssen in Anführungszeichen oder Hochkommas gesetzt werden:

se_action_<Aktionsname>:
   - 'function: <func>'
   - Detailparameter der Funktion, z.B. "to: .."
   - 'delay: <delay>'
   - 'order: <order>'
   - 'repeat: <repeat>'
   - 'conditionset: <conditionset regex>'

Auszuführende Aktionsart

Mit dem Parameter <func> wird die auszuführende Funktion festgelegt. In Abhängigkeit zur gewählten Funktion werden zusätzliche Detailparameter erforderlich. Folgende Werte sind möglich:

Funktion set: Item auf einen Wert setzen

se_action_<Aktionsname>:
    - 'function: set'
    - 'to: <val>'
    - 'force: [True/False]'

Das Item, das verändert werden soll, muss auf Ebene des Regelwerk-Items über das Attribut se_item_<Aktionsname> oder se_eval_<Aktionsname> angegeben werden.

Der Parameter to: <val> legt fest, auf welchen Wert das Item gesetzt werden soll. Der Wert, auf den das Item gesezt wird, kann als statischer Wert, als Wert eines Items oder als Ergebnis der Ausführung einer Funktion festgelegt werden. Wichtig ist, dass bei z.B. to: item:<item> nach dem item: kein Leerzeichen eingesetzt werden darf!

Wie bei den Bedingungen sind die entsprechenden Prefixe value, item, eval zu nutzen: - statischer Wert, beispielsweise value:500, wobei das value: auch weggelassen werden kann. - Item, z.B. item:settings.helligkeitsschwellwert - Eval-Funktion wie eval:1*2*se_eval.get_relative_itemvalue('..bla') - Template: eine Vorlage, z.B. template:<Name des Templates>

Über den optionalen Parameter force: True kann eine Item-Aktualisierung erzwungen werden, auch wenn sich der Wert nicht ändert. Damit erfolgt auf jeden Fall eine Wertänderung (ggf. sogar zwei) mit allen damit in Zusammenhang stehenden Änderungen (evals, Aktualisierung der Änderungszeiten, etc).

Funktion add: Wert zu einem Listenitem hinzufügen

se_action_<Aktionsname>:
    - 'function: add'
    - 'value: <val>/<eval>/<var>'
    - 'force: [True/False]'

Das Item, das verändert werden soll, muss auf Ebene des Regelwerk-Items über das Attribut se_item_<Aktionsname> oder se_eval_<Aktionsname> angegeben werden.

Der Parameter value: <val> legt fest, welcher Wert zum Item mit dem Typ list hinzugefügt werden soll. Wird hier direkt ein Wert angegeben, ist darauf zu achten, dass ein String unter Anführungszeichen stehen muss, während eine Zahl das nicht sollte.

Funktion remove: Wert von einem Listenitem entfernen

se_action_<Aktionsname>:
    - 'function: remove'
    - 'value: <val>/<eval>/<var>'
    - 'mode: [first/last/all]'

Das Item, das verändert werden soll, muss auf Ebene des Regelwerk-Items über das Attribut se_item_<Aktionsname> oder se_eval_<Aktionsname> angegeben werden.

Der Parameter value: <val> legt fest, welcher Wert vom Item mit dem Typ list entfernt werden soll. Dabei ist zu beachten, dass zwischen String (Anführungszeichen) und Zahlen unterschieden wird. Ist der angegegeben Wert nicht in der Liste, wird der originale Itemwert erneut geschrieben, ohne etwas zu entfernen. Über den Parameter mode lässt sich einstellen, ob jeweils alle mit dem Wert übereinstimmenden Einträge in der Liste (mode: all) oder nur der erste (first) bzw. der letzte (last) Eintrag gelöscht werden sollen. Wird der Parameter nicht angegeben, werden immer alle Einträge gelöscht.

Funktion run: Ausführen einer Funktion

se_action_<Aktionsname>:
    - 'function: run'
    - 'eval: (Funktion)'

Die Angabe ist vergleichbar mit dem Ausführen einer Funktion zur Ermittlung des Werts für ein Item, hier wird jedoch kein Item benötigt. Außerdem wird der Rückgabewert der Funktion ignoriert.

Funktion trigger: Auslösen einer Logikausführung

se_action_<Aktionsname>:
    - 'function: trigger'
    - 'logic: <Logikname>'
    - 'value: <Wert>'

Löst die Ausführung der Logik <Logikname> aus. Um beim Auslösen einen Wert an die Logik zu übergeben, kann dieser Wert über die Angabe von value: <Wert> hinter dem Logiknamen angegeben werden. Die Angabe kann aber auch entfallen.

Funktion byattr: Alle Items, die ein bestimmtes Attribut haben, auf den Wert dieses Attributs setzen

se_action_<Aktionsname>:
    - 'function: byattr'
    - 'attribute: <Attributname>'

Mit dieser Funktion wird der Name eines anderen (beliebigen) Attributs angegeben. Beim Ausführen werden alle Items herausgesucht, die das angegebene Attribut enthalten. Diese Items werden auf den Wert gesetzt, der dem genannten Attribut in den Items jeweils zugewiesen ist.

dummy1:
        type: num
        <Attributname>: 42

dumm1 wird auf 42 gesetzt. Ein anderes Item, dummy2,

dummy2:
        type: str
        <Attributname>: Rums

wird gleichzeitig auf Rums gesetzt.

Funktion special: Sondervorgänge

se_action_<Aktionsname>:
    - function: special
    - value: <Sondervorgang>

Für bestimmte Sondervorgänge sind besondere Aktionen im Plugin definiert. Aktuell gibt es zwei besondere Vorgänge:

  • suspend:<suspend_item>,<manuell_item> (z.B. suspend:..suspend,..manuell)
  • retrigger:<trigger_item> (z.B. retrigger:..retrigger)

Zusätzliche Parameter

delay: <delay>

Über den optionalen Parameter <delay> wird die Verzögerung angegeben, nach der die Aktion ausgeführt werden soll.

Die Angabe erfolgt in Sekunden oder mit dem Suffix „m“ in Minuten.

'delay: 30'         --> 30 Sekunden
'delay: 30m'        --> 30 Minuten

Der Timer zur Ausführung der Aktion nach der angegebenen Verzögerung wird entfernt, wenn eine gleichartige Aktion ausgeführt werden soll (egal ob verzögert oder nicht).

repeat: <repeat>

'repeat: [True|False]'

Über das Attribut wird unabhängig vom globalen Setting für das stateengine Item festgelegt, ob eine Aktion auch beim erneuten Eintritt in den Status ausgeführt wird oder nicht.

order: <order>

Die Reihenfolge, in der die Aktionen ausgeführt werden, ist nicht zwingend die Reihenfolge in der die Attribute definiert sind. In den meisten Fällen ist dies kein Problem, da oftmals die Aktionen voneinander unabhängig sind und daher in beliebiger Reihenfolge ausgeführt werden können. In Einzelfällen kann es jedoch erforderlich sein, mehrere Aktionen in einer bestimmten Reihenfolge auszuführen. Dies kann über den Parameter order: <order> erfolgen. Mit diesem Attribut wird der Aktion eine Zahl zugewiesen. Aktionen werden in aufsteigender Reihenfolge der zugewiesenen Zahlen ausgeführt.

'order: [1|2|...]'

conditionset: <conditionset regex>

'conditionset: ["enter_(.*)_test", "eval:sh.itemX.property.name"]'

Über das Attribut wird festgelegt, dass die Aktion nur dann ausgeführt werden soll, wenn der Zustand durch die angegebene Bedingungsgruppe eingenommen wurde. Zum Vergleich wird immer der volle Pfad der Bedingungsgruppe herangezogen. Conditionset erlaubt sowohl eine Liste als auch reguläre Ausdrücke, wodurch nicht zwingend der komplette Pfad der Bedingungsgruppe bekannt sein muss. Der gesamte Pfad könnte wie folgt evaluiert werden:

"eval:se_eval.get_relative_itemid('{}.<bedingungsset>'.format(se_eval.get_relative_itemvalue('..state_id')))"

Templates für Aktionen

Setzt man für mehrere Aktionen (z.B. Setzen auf einen Wert abhängig vom aktuellen Zustand) immer die gleichen Ausdrücke ein, so kann Letzteres als Template definiert und referenziert werden. Dadurch wird die die Handhabung komplexerer Wertdeklarationen deutlich vereinfacht. Diese Templates müssen wie se_item/se_eval auf höchster Ebene des StateEngine Items (also z.B. rules) deklariert werden.