Introduction
A rule is a set of instructions that are executed by the Automation Controller (AC).
Processing logic
The AC operates with a set of rules, given by its configuration. Each of the rules is processed independent to other rules and their data (a configuration of only one rule for the AC would be OK), but the outcome of one rule may affect other rules.
Triggers
Each rule must have one or more triggers. A trigger is either a calibrated result or a sensor event. While updating its own configuration the AC subscribes for the calibrated results or sensor events which are defined in the trigger section of the rule configuration.
<rule rule_id="BreakIn">
<triggers>
<trigger value_name="motion" trigger_topic="calibrated_result" sensor_id="BTS_Motion_Control_AdamDI3" value_type="boolean"/>
<trigger value_name="door_open" trigger_topic="calibrated_result" sensor_id="BTS_ShelterDoor_AdamDI0" value_type="boolean"/>
<trigger value_name="arm_state" trigger_topic="calibrated_result" sensor_id="BTS_arm_state" value_type="string"/>
</triggers>
...
</rule>
The same calibrated result or sensor event can be trigger for more then one rule.
Each time the AC receives a trigger, all rules which have a trigger with that sensor_id are processed sequential. The order of sequential processing (which rule comes first) is not defined.
A sensor_id must be uinque within the triggers of one rule. This means, the same sensor cannot be used as trigger event and trigger cal_result within one rule (which makes also no sense). An error message is logged if such a configuration occurs.
States
The triggers of a rule define as well the states within that rule. Each calibrated result has one value and each event has one state. The value_name of a trigger defines the name of the state for a rule and the value_type of that trigger the type of this state within that rule. The incoming values for the states get casted to their value_type. Possible types are boolean, decimal (cast to integer), float and string.
The states of a rule are only valid for that rule. A state of another rule with the same name is independent.
Regarding to the rule-example above the rule BreakIn has thus the states motion, door_open and arm_state.
Before the AC goes to the next step, the condition handling, it check if any of the rule- states has changed. If none of the states has changed, the further processing of that rule for that trigger is skipped.
The name of a state (value_name) might be chosen almost free.
But following names are forbidden:
- uid
- sensor_id
- topic
- value
§xpressions
Each rule must contain at least one expression. One expression is part of one conditions in the rule configuration. The expression is a string which gets evaluated by python. In the XML config the expression name is abbreviated.
Example of an expression for a condition
<conditions>
<condition expr="arm_state == 'armed' and (motion or door_open)">
</conditions>
The result of the evaluation of an expression is always logically true or false. Expressions like expr="True" are possible.
The states of a rule are are available as local variables for the expressions.
Condition handling
The processing of a rule finds at least one conditional expression which is either true or not. For both cases a set of:
- actions
- result publishing
- event publishing
- state changes
- timer kills (see section timers of this document)
can be executed. The order of processing is the same as in the list above. Empty sets are allowed.
Actions
The documentation of SiteController actions is not part of this document. In short words: Publishing an action to MQTT lets a specific actuator module do something, e.g. setting a coil of a digittal output device to a configured value. The AC publishes actions if configured in the <true> or the <false> branch of a condition.
<conditions>
<condition expr="access == 'granted'">
<true>
<action_list>
<action action_id="Switch_M2M_WTSC_Relay" command="ON"/>
<action action_id="Switch_M2M_WTSC_DO_1_red_LED" command="OFF"/>
<action action_id="Switch_M2M_WTSC_DO_2_green_LED" command="ON"/>
</action_list>
</true>
</condition>
</conditions>
Results
The AC publishes calibrated results if configured in the <true> or the <false>branch of a condition.
<conditions>
<condition expr="arm_button == True">
<true>
<result_list>
<result sensor_id="BTS_arm_state" result_value="armed" timer="T1" value_type="string"/>
<result ... />
</result_list>
</true>
</condition>
</conditions>
The timer in the example above will be discussed in the section timers of this document. The result_value will be casted to the given value_type when published. At the moment it is not necessary to define the sensor with the used sensor_id in the sensor section of the sensor configuration XML.
Results with evaluated result_value
<rule rule_id="LastValidVal">
<triggers>
<trigger value_name="res" trigger_topic="calibrated_result" sensor_id="snmpZyxel_port7" value_type="decimal"/>
<trigger value_name="res" trigger_topic="calibrated_result" sensor_id="snmpgetzyxel_port7" value_type="decimal"/>
</triggers>
<conditions>
<condition expr="True">
<true>
<result_list>
<result sensor_id="VS_ZyxelPort7" result_value="res" evaluate="true" value_type="decimal"/>
</result_list>
</true>
</condition>
</conditions>
</rule>
In the example above the optinal attribute evaluate="true" is used. If this attribute is set to true the result value will be evaluated like an expression. Both triggers use the same value_name, so there is only one state with the name res in this rule. res will always contain the latest received value (from one of the both triggers). Because the result_value is evaluated, the calibrated result will contain the latest received value when published. This way the AC reduces several inputs to one output.
The evaluation of result_value is encapsulated by exception handling. If an exception occures (for insatance: addition of None values) an error is written to the log of AC and no result is procudeced in that case.
Events
Similiar to calibrated results AC may publish events as well. Here is a short snippet (must be inside a <true> or <false> condition case):
<event_list>
<event sensor_id="VS_opened_door" state="CRITICAL" output="Door is open!" value_type="string"/>
</event_list>
The publishing of an event cannot be delayed
States
The AC is able to change the states of a rule by itself. Here is a short snippet (must be inside a <true> or <false> condition case):
<state_list>
<state state_name="vs_door_open" state_value="False"/>
</state_list>
Timers
The publishing of actions and calibrated results caused by the condition cases of a rule expression can be delayed by timers. The definition of timers in the XML takes place between the trigger definition and the defintion of conditions.
...
</triggers>
<timers>
<timer delay="10" timer_id="T1"/>
<timer delay="20" timer_id="T2"/>
</timers>
<conditions>
<condition expr=...">
...
The delay is measured in seconds. The timer_id is an arbritrary string, it must me uniquie for its rule. To get an action or a result published with delay, add the attribute timer="T1" (or other id then "T1") to its definition. Times can be killed within a rule (see section 'timer kills').
If the same timer is used again before it ran out (e.g. same condition case is triggered again), then the timer will be restarted.
Within a rule one timer (one timer_id) should be used only for one action or calibrated result. Do not use the same timer_id parallel.
Timer kills
Please refer to the section timers in this document. The publishing of some things in a rule can be delayed by timers. The change of a state of a rule could make it necessary to kill the delayed publishing.
<condition expr="arm_state == 'armed'">
<true>
<kill_timers>
<timer_id>T1</timer_id>
<timer_id>T2</timer_id>
</kill_timers>
</true>
</condition>
Of course the timer kill may take place in the <false> branch of a condition as well. In the example above the timers with the ID T1 and T2 will be killed. Please note: The used timers are not repeating. So, if a timer has finished it will disappear by itself. The AC is stable against killing of non existent timers.
Next Steps
- More information can be found in the/wiki/spaces/SC13/pages/75104368 section.
- Link to other articles
- and more links