Note: This explanation is based on the StateEngine plugin in the official master 1.6  plugins repository. The plugin is formerly known as AutoBlind that is available at the author’s github site: AutoBlind 1.4.0

All config attributes starting with se_ (stateengine) were originally as_ (autostate)!

We start with a simple blind item that we want to create a sun tracking and a standard (day) state for:


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

So far nothing will happen. So let’s add an „eval_trigger“ at the end of „rules“ to trigger the evaluation of the rules:


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

Now the states are evaluated as soon as the item blinds.triggeritem gets set to „1“. As there are no rules defined yet, still nothing will happen though 😉 So let’s add a simple state called suntracking and one state called „standard“. There should always be one state at the end without any entry condition as a „standard“ state.


            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'

The se_action_ Items define some actions that should happen with the corresponding items. It is necessary to define these items (for height, lamella) under „rules“, otherwise the plugin won’t know what items to change. The name has to be the same as in the action – this time you use the se_item prefix. This „links“ the actions with the items.


            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)

The same is true for the items that are evaluated to enter the state, in our example that’s altitude and temperature:


            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

So far it should be clear that all items referenced in the state definitions have to be defined at the beginning of the rules section by „se_item_“ and a name that makes sense for you. In the actions themselves you reference those names again, but this time not by „se_item_“ but by „se_action_„.

It’s similar with the items that are relevant for entering a state. So the temperature has to be defined as „se_item_temperature“. For the state evaluation you exchange the „item“ part with a condition like „min“, „max“, „agemin“, „agemax“, etc. Have a look at the plugin documentation.

Putting it all together the code looks like this:


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'

After activating the plugin in plugin.yaml like this you now have a blind that will close if the temperature is above 22 degrees and the sun has a specific height. Otherwise the blinds will open.

Usually you want to use some state definitions for more than one item. It would be very tedious to update the code for all of your items if you want to change some conditions, etc. That’s why you can define default states on a global base and reference those states in the „rules“ section of the items using „se_use“. Have a look at the documentation for details or – even better – just use „struct“ item templates! This „struct“ feature is available since SmarthomeNG 1.6 and a huge time saver for your setups. The state engine plugin provides some standard states and items that you can easily implement the following way. You can actually also skip the laststate and lastconditionset items and just use the struct: 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:
                  - ..lock
                  - ..manuell
                  - ..release
                  - ..retrigger
                  - weather.temperature

The templates for suntrack and standard states have to be defined in etc/struct.yaml. The se_suntrack and se_standard items have the same entries as in the example above:


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'

The following diagram shows the hierarchical evaluation of the states:

Kategorien: Plugins

3 Kommentare

onkelandy · 18. Juli 2019 um 23:14

Bernd, hier kommt deine gewünschte Grafik.. tadaaaaa!

Andreas · 9. November 2018 um 13:20

Bezüglich Deutsch hilft dir der Browser/Google 😉

Was für ne Grafik schwebt dir vor? Ein Ablaufdiagramm? Kann ich im (noch ausstehenden) advanced Beitrag einbinden. Hier wird ja nur ein einziger Zustand evaluiert.

Bernd Meiners · 9. November 2018 um 13:10

Es wäre schön das in deutsch lesen zu können und dazu auch ein paar Grafiken zur Veranschaulichung zu haben. So verliere ich dann doch ein wenig den Überblick. Aber Danke für die Mühe!

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.