stateengine plugin: update docu

stateengine/user_doc/06_aktionen.rst

@@ -18,8 +18,9 @@ definiert und benannt wurde. Die Herangehensweise ähnelt also stark der Deklara
 
 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
+sich ein Item mindestens geändert haben muss, um neu gesetzt zu werden. Diese Konfiguration
+kann für einzelne Aktionen individuell über die Angabe ``mindelta`` überschrieben 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.
@@ -300,6 +301,7 @@ ursprünglichen Zustands (regen) gesetzt werden soll, kann der Parameter ``insta
 
 .. code-block:: yaml
 
+       'repeat: <eval>/<item>' --> Ergebnis eines Eval-Ausdrucks oder eines Items
        'repeat: [True|False]'
 
 Über das Attribut wird unabhängig vom globalen Setting für das
@@ -393,7 +395,7 @@ regnet hingegen auf den Wert, der in den Settings hinterlegt ist.
 
 .. code-block:: yaml
 
-      previousconditionset: regex:enter_(.*)_test"
+      "previousconditionset: regex:enter_(.*)_test"
 
 Über das Attribut wird festgelegt, dass die Aktion nur dann ausgeführt werden
 soll, wenn die vorherige Bedingungsgruppe des aktuellen Zustands mit dem angegebenen Ausdruck übereinstimmt.
@@ -403,7 +405,7 @@ Die Abfrage erfolgt dabei nach den gleichen Regeln wie bei ``conditionset`` oben
 
 .. code-block:: yaml
 
-      previousstate_conditionset: regex:enter_(.*)_test"
+      "previousstate_conditionset: regex:enter_(.*)_test"
 
 Über das Attribut wird festgelegt, dass die Aktion nur dann ausgeführt werden
 soll, wenn die Bedingungsgruppe, mit der der vorherige Zustand eingenommen wurde, mit dem angegebenen Ausdruck übereinstimmt.
@@ -413,13 +415,55 @@ Die Abfrage erfolgt dabei ebenfalls nach den gleichen Regeln wie bei ``condition
 
 .. code-block:: yaml
 
-      next_conditionset: regex:enter_(.*)_test"
+      "next_conditionset: regex:enter_(.*)_test"
 
 Über das Attribut wird festgelegt, dass die Aktion nur dann ausgeführt werden
 soll, wenn die Bedingungsgruppe, mit der der zukünftige Zustand eingenommen wird, mit dem angegebenen Ausdruck übereinstimmt.
 Die Abfrage erfolgt dabei ebenfalls nach den gleichen Regeln wie bei ``conditionset`` oben angegeben.
 Diese Angabe ist primär bei leave_actions sinnvoll.
 
+**mindelta: <num>**
+
+Im folgenden Beispiel wird mindelta für eine einzelne Aktion gesetzt. Anstatt also eine minimale Änderung
+für alle Aktionen mit bestimmtem Namen festzulegen, wird eine einzelne Aktion nur dann ausgeführt,
+wenn sich der Wert um mindestens den angegeben Wert geändert hat.
+Wird 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.
+
+.. code-block:: yaml
+
+    #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_status_lamella: raffstore1.lamelle.status # Definition des Lamellen Statusitems
+                Daemmerung:
+                    <...>
+                    se_action_height:
+                        - 'function: set'
+                        - 'to: value:100'
+                    se_action_lamella:
+                        - 'function: set'
+                        - 'to: value:25'
+                        - 'mindelta: 10'
+                    <...>
+
+**minagedelta: <num>**
+
+.. code-block:: yaml
+
+      minagedelta: 300
+
+Über das Attribut wird festgelegt, dass eine Aktion nur in einem vorgegebenen Intervall ausgeführt wird.
+Im angegebenen Beispiel wird die Aktion also nur ausgeführt, wenn der letzte Ausführungszeitpunkt mindestens
+5 Minuten zurück liegt. So kann verhindert werden, dass die Aktion bei jeder Neuevaluierung des Status ausgeführt wird.
+Ein Neustart des Plugins setzt den Counter wieder zurück, der letzte Ausführungszeitpunkt wird also nur bei laufendem
+Betrieb gespeichert und überdauert einen Neustart nicht.
+
+
 Templates für Aktionen
 ----------------------
 

stateengine/user_doc/12_aktioneneinzeln.rst

@@ -150,8 +150,50 @@ Es ist möglich, eine Minimumabweichung für
 aktuellen Wert des Items und dem ermittelten neuen Wert kleiner
 ist als die festgelegte Minimumabweichung wird keine Änderung
 vorgenommen. Die Minimumabweichung wird über das Attribut
-``se_mindelta_<Aktionsname>`` auf der Ebene des Regelwerk-Items
-festgelegt.
+``se_mindelta_<Aktionsname>`` auf der Ebene des Regelwerk-Items für alle
+Aktionen mit dem entsprechenden Namen festgelegt. Alternativ kann dieses
+Attribut aber auch für einzelne Aktionen festgelegt und/oder überschrieben werden.
+
+Im angeführten Beispiel werden die Lamellen beim Eintritt in einen Zustand und
+beim Verlassen des Zustands nur dann gesetzt, wenn sich der Wert der Lamellen inzwischen
+um mindestens 10 verändert hat. Wird der Zustand erneut eingenommen (stay), wird der
+Wert hingegen mit 5 überschrieben.
+
+.. code-block:: yaml
+
+    #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_status_lamella: raffstore1.lamelle.status # Definition des Lamellen Statusitems
+                se_mindelta_lamella: 10 # Alle Aktionen mit Namen lamella sind betroffen
+                Daemmerung:
+                    on_enter:
+                        se_set_height: 100
+                        se_set_lamella: 20
+                    on_leave:
+                        se_set_height: 100
+                        se_set_lamella: 15
+                    on_stay:
+                        se_set_height: 100
+                        se_set_lamella: 20
+                        se_set_lamella: 20
+                        se_mindelta_lamella: 5
+
+**minagedelta: <int>**
+
+.. code-block:: yaml
+
+       se_minagedelta_<Aktionsname>: 300 (Sekunden)|30m (Minuten)
+
+Über das Attribut wird festgelegt, dass eine Aktion nur in einem vorgegebenen Intervall ausgeführt wird.
+Im angegebenen Beispiel wird die Aktion also nur ausgeführt, wenn der letzte Ausführungszeitpunkt mindestens
+300 Sekunden zurück liegt. So kann verhindert werden, dass die Aktion bei jeder Neuevaluierung des Status ausgeführt wird.
+Ein Neustart des Plugins setzt den Counter wieder zurück, der letzte Ausführungszeitpunkt wird also nur bei laufendem
+Betrieb gespeichert und überdauert einen Neustart nicht.
 
 **delay: <int>**
 
@@ -167,8 +209,10 @@ 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). 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
-einmalig ausgeführt werden.
+nicht mehr durchgeführt.
+Außerdem ist es möglich, den Timer bewusst abzubrechen, ohne eine Aktion auszuführen,
+indem der Delay auf -1 gesetzt wird. Dies macht insbesondere beim Verlassen von
+Zuständen Sinn, um ungewünschte verzögerte Aktionen vom "alten" Zustand zu verhindern.
 
 **repeat: <bool>**