Starthilfe für das Stateengine Plugin

Einleitung

Hinweis: Diese Erklärung basiert auf dem StateEngine Plugin im offiziellen Master 1.6 Plugins Repository. Das Plugin war früher unter dem Namen AutoBlind bekannt und ist auf der Github-Seite des Autors verfügbar: AutoBlind 1.4.0 Alle Konfigurationsattribute, die mit se_ (stateengine) beginnen, waren ursprünglich as_ (autostate)!

Wir beginnen mit einer einfachen Jalousie, für die wir eine Sonnenverfolgung und einen Standardzustand (Tag) erstellen wollen:

blinds:
    type: foo

    room:
        type: foo
        name: Blinds in Room XYZ

        blind_height: # standard item to set the height
            knx_send: 2/1/14
            knx_dpt: 5001
            visu: 'yes'
            type: num
            knx_cache: 2/1/20

        blind_lamella: # standard item to set the lamella angle
            knx_send: 2/1/15
            knx_dpt: 5001
            visu: 'yes'
            type: num
            knx_cache: 2/1/21

        stateengine: # everything below should be added to all stateengine items by default
            type: foo

            stateengine_id:
                type: str
                visu_acl: r
                cache: 'on'

            stateengine_name:
                type: str
                visu_acl: r
                cache: 'on'

            rules: # Here are the rules for the different states.
                type: bool
                se_plugin: active # activates the plugin for this item
                se_laststate_item_id: ..stateengine_id
                se_laststate_item_name: ..stateengine_name

Bis jetzt passiert noch nichts. Fügen wir also ein „eval_trigger“ am Ende von „rules“ ein, um die Auswertung der Regeln auszulösen:

            rules: 
                eval: True
                eval_trigger:
                  - blinds.triggeritem # an item that might trigger every 2 minutes using cycle: 120 = 1

Nun werden die Zustände ausgewertet, sobald das Item blinds.triggeritem auf „1“ gesetzt wird. Da noch keine Regeln definiert sind, wird allerdings auch noch nichts passieren 😉 Fügen wir also einen einfachen Zustand namens suntracking und einen Zustand namens „standard“ hinzu. Am Ende sollte immer ein Zustand ohne Eingangsbedingung als „Standard“-Zustand vorhanden sein.

            rules: 
                suntrack:
                    type: foo
                    name: Suntracking

                    enter_temperature: # This needs to be called "enter". You can add a _name if want 
                        type: foo
                        # if all three conditions are true the state will be entered
                        se_min_sun_altitude: 20 # if altitude is at least 20 degrees.
                        se_max_sun_altitude: 120 # if altitude is max 120 degrees.
                        se_min_temperature: 22 # if temperature is at least 22 degrees.

                    on_enter_or_stay: # these actions will get triggered every time the enter-conditions are met.
                        se_action_height: # action to the item "height" that has to be defined in the rules section
                          - 'function: set' # The height item will get set to a specific value
                          - 'to: 100' # The value the height item is set to
                          - 'order: 1' # If the order of the actions is important you can use this attribute
                        se_action_lamella: # action to the item "lamella" that has to be defined in the rules section
                          - 'function: set'
                          - 'to: eval:stateengine_eval.sun_tracking()' # sun_tracking will calculate the correct lamella angle
                          - 'order: 2'

                standard:
                    type: foo
                    name: Standard

                    on_enter_or_stay:
                        se_action_height: # the blind height gets set to 0
                          - 'function: set'
                          - 'to: 0'
                          - 'order: 1'
                        se_action_lamella:# lamella get set to 0
                          - 'function: set'
                          - 'to: 0'
                          - 'order: 2'

Die se_action_ Items definieren einige Aktionen, die mit den entsprechenden Items passieren sollen. Es ist notwendig, diese Elemente (für Höhe, Lamellen) unter „rules“ zu definieren, sonst weiß das Plugin nicht, welche Elemente zu ändern sind.

            rules:
                se_item_height: ...blind_height # height item, defined relatively
                se_item_lamella: blinds.room.blind_lamella # lamella item, defined absolutely (use whatever you want)

Das Gleiche gilt für die Elemente, die ausgewertet werden, um in den Zustand einzutreten, in unserem Beispiel sind das Höhe und Temperatur:

            rules:
                se_item_sun_altitude: weather.sun.altitude # refer to an item updated by a weather station or weather plugin
                se_item_temperature: weather.temperature # refer to an item updated by a weather station or weather plugin

Bis hierhin sollte klar sein, dass alle Elemente, auf die in den Zustandsdefinitionen verwiesen wird, am Anfang des Regelabschnitts durch „se_item_“ und einen für Sie sinnvollen Namen definiert werden müssen. In den Aktionen selbst verweisen Sie wieder auf diese Namen, aber diesmal nicht mit „se_item_“, sondern mit „se_action_“.

Ähnlich verhält es sich mit den Elementen, die für den Eintritt in einen Zustand relevant sind. So muss die Temperatur als „se_item_temperature“ definiert werden. Für die Zustandsauswertung ersetzen Sie den „item“-Teil durch eine Bedingung wie „min“, „max“, „agemin“, „agemax“, etc. Werfen Sie einen Blick in die Dokumentation des Plugins.

Zusammengefasst sieht der Code wie folgt aus:

blinds:
    triggeritem:
        type: bool
        name: Trigger
        cycle: 120 = 1

    room:
        name: Blinds in Room XYZ

        blind_height:
            knx_send: 2/1/14
            knx_dpt: 5001
            visu: 'yes'
            type: num
            knx_cache: 2/1/20

        blind_lamella:
            knx_send: 2/1/15
            knx_dpt: 5001
            visu: 'yes'
            type: num
            knx_cache: 2/1/21

        stateengine:

            stateengine_id:
                type: str
                visu_acl: r
                cache: 'on'

            stateengine_name:
                type: str
                visu_acl: r
                cache: 'on'

            conditionset_id:
                type: str
                visu_acl: r
                cache: 'on'

            conditionset_name:
                type: str
                visu_acl: r
                cache: 'on'

            lock:
                type: bool
                knx_dpt: 1
                visu_acl: rw
                cache: 'on'

            rules:
                type: bool
                se_plugin: active
                se_laststate_item_id: ..stateengine_id
                se_laststate_item_name: ..stateengine_name
                se_lastconditionset_item_id: ..conditionset_id
                se_lastconditionset_item_name: ..conditionset_name
                se_item_height: ...blind_height
                se_item_lamella: ...blind_lamella
                se_item_altitude: weather.sun.altitude
                se_item_temperature: weather.temperature
                eval: True
                eval_trigger:
                  - blinds.triggeritem

                suntrack:
                    type: foo
                    name: Suntracking

                    enter:
                        type: foo
                        se_min_sun_altitude: 20 
                        se_max_sun_altitude: 120 
                        se_min_temperature: 22 

                    on_enter_or_stay: 
                        se_action_height:
                          - 'function: set'
                          - 'to: 100' 
                          - 'order: 1' 
                        se_action_lamella: 
                          - 'function: set'
                          - 'to: eval:stateengine_eval.sun_tracking()' 
                          - 'order: 2'

                standard:
                    type: foo
                    name: Standard

                    on_enter_or_stay:
                        se_action_height: 
                          - 'function: set'
                          - 'to: 0'
                          - 'order: 1'
                        se_action_lamella:
                          - 'function: set'
                          - 'to: 0'
                          - 'order: 2'

Nachdem Sie das Plugin in der plugin.yaml so aktiviert haben, haben Sie nun eine Jalousie, die sich schließt, wenn die Temperatur über 22 Grad liegt und die Sonne eine bestimmte Höhe hat. Andernfalls werden die Jalousien geöffnet.

Stateengine Definitionen wiederverwerten

In der Regel möchten Sie einige Zustandsdefinitionen für mehr als ein Element verwenden. Es wäre sehr mühsam, den Code für alle Ihre Elemente zu aktualisieren, wenn Sie einige Bedingungen usw. ändern möchten. Aus diesem Grund können Sie Standardzustände auf globaler Basis definieren und diese Zustände im Abschnitt „rules“ der Elemente mit „se_use“ referenzieren. Schauen Sie in die Dokumentation für Details oder – noch besser – verwenden Sie einfach „struct“-Elementvorlagen! Dieses „struct“-Feature steht seit SmarthomeNG 1.6 zur Verfügung und ist eine enorme Zeitersparnis für Ihre Setups. Das State-Engine-Plugin stellt einige Standard-Zustände und -Elemente zur Verfügung, die Sie auf die folgende Weise einfach implementieren können. Sie können auch die Elemente laststate und lastconditionset weglassen und einfach die struct verwenden: stateengine.general.

blinds:
    room:
        blind_height:
            type: num

        blind_lamella:
            type: num

        stateengine:
            remark: >-
                With "general" all last state/condition items etc. are created. The release, lock and suspend states are 
                useful states provided by the plugin, too. The last two are defined in the etc/struct.yaml file manually.
            struct:
                - stateengine.general
                - stateengine.state_release
                - stateengine.state_lock
                - stateengine.state_suspend
                - se_suntrack
                - se_standard

            manuell:
                remark: You have to setup the manual item based on your items (e.g. blind_height, etc.)
                type: bool
                name: manuelle bedienung
                eval_trigger: 
                  - ...blind_height
                  - ...blind_lamella
                se_manual_invert: True

            rules:
                se_item_height: ...blind_height
                se_item_lamella: ...blind_lamella
                remark: If you want to add own eval_triggers you have to re-define also the standard triggers from the plugin structs
                eval_trigger:
                  - merge_unique*
                  - weather.temperature

Vor smarthomeNG 1.7 mussten Sie den eval_trigger der Regeln für jedes Element überschreiben, da die Attributliste nicht kombiniert wurde. Die Regeln hätten wie folgt ausgesehen:

            rules:
                se_item_height: ...blind_height
                se_item_lamella: ...blind_lamella
                remark: If you want to add own eval_triggers you have to re-define also the standard triggers from the plugin structs
                eval_trigger:
                  - ..lock
                  - ..manuell
                  - ..release
                  - ..retrigger
                  - weather.temperature

Die Vorlagen für suntrack und standard states müssen in etc/struct.yaml definiert werden. Die Elemente se_suntrack und se_standard haben die gleichen Einträge wie im obigen Beispiel:

se_suntrack:
    rules:
        se_item_altitude: weather.sun.altitude
        se_item_temperature: weather.temperature
            
        enter:
            se_min_sun_altitude: 20 
            se_max_sun_altitude: 120 
            se_min_temperature: 22 

        on_enter_or_stay: 
            se_action_height:
              - 'function: set'
              - 'to: 100'
            se_action_lamella: 
              - 'function: set'
              - 'to: eval:stateengine_eval.sun_tracking()' 

se_standard:
    rules:
        on_enter_or_stay:
            se_action_height: 
              - 'function: set'
              - 'to: 0'
            se_action_lamella:
              - 'function: set'
              - 'to: 0'

Das folgende Diagramm zeigt die hierarchische Auswertung der Zustände. Eine ähnliche Visualisierung bietet auch die Weboberfläche des Plugins. Klicken Sie einfach auf einen Eintrag, um ihn zu öffnen!

Stateengine Ablaufdiagramm