From Hubitat Documentation
Revision as of 23:47, 2 July 2019 by Bravenel (talk | contribs) (Created page with "<h1>Rule 4.0 -- The new Rule Machine</h1> Rule 4.0 is the culmination of a journey in the transformation of Rule Machine. At once it simplifies and adds power, resulting in...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Rule 4.0 -- The new Rule Machine

Rule 4.0 is the culmination of a journey in the transformation of Rule Machine. At once it simplifies and adds power, resulting in a fully generalized automation engine. The prior top-level organization of RM is thrown out, replaced by a simpler interface. The changes are described below, and how what was done in prior versions is now accomplished. Gone are Rules, Triggers, Triggered Rules, Actions and Schedules. Instead, you define what causes a rule to run, and then what it does. The functionality of Button Controller is fully incorporated into Rule Machine, but with more power and flexibility. New conditional logic capabilities are provided, allowing the most subtle or complex automations to be created. You define what causes the rule to run, and then what it does.

What Became of Rule, Trigger, Triggered Rule, Action and Schedule?

To explain how the former RM concepts of Rule, Trigger, Triggered Rule, Actions and Schedule are now accomplished, and how Button Controller is incorporated, first we address the easy and obvious:

What was a Trigger is now the basic format for all rules. Select Trigger Events and define actions.

What was an Action is accomplished by simply omitting Trigger Events and only defining actions. Obviously, such a rule needs to be run by some other rule or from the RM API.

What was a Schedule is now available as a new type of Trigger Event, Days of Week Schedule.

Button Controller is fully incorporated as a new type of Trigger Event, Button Device. Once Button Device is selected the full UI of Button Controller 3.0 is pulled up to define actions for any of the buttons available on the selected device. Unlike Button Controller, these actions have full access to conditional logic and global variables.

How to Build a Rule in Rule 4.0

Now, for the more complex cases of a Rule, and a Triggered Rule, we will explain how a former Rule 3.0 Rule is done in Rule 4.0. In a Rule the rule itself can be thought of as an overarching IF-THEN-ELSE, where if the rule was true in the IF part, then Actions for True would run, and if false, Actions for False would run. This same logic can now simply be done with conditional actions IF-THEN and ELSE in the actions section of a rule. As will be described below, IF-THEN now has the same full logical expression capability of the former Rule with AND, OR, XOR, NOT logical operators and nested parenthetical sub-expressions.

The trigger event is contact sensor "Front Door *changed*". In an old Rule, this is exactly how the Condition of Front Door *open* was interpreted -- the rule would be evaluated whenever any event happened for the Front Door. Instead of that being implicit in the old Rule, now it is explicit in the 4.0 rule. In the old Rule, our rule was "Front Door *open*". Now we make that the condition of an IF-THEN action. What were Actions for True become the actions following IF-THEN, and Actions for False become the actions following ELSE. Most Rules follow this basic format.

What became of Rule Truth and Cancel on Truth Change?

There are two subtle issues from Rule 3.0 that have changed, cancel on truth change and requiring truth change to take action. The concept of rule truth is gone in Rule 4.0. Instead, all of this is now explicit in the way you write the actions for a rule. Below are two examples to illustrate cancel on truth change, first for 3.0 and then 4.0. This rule uses Cancel On Truth Change to keep some lights on as long as motion is active:

If we don't want the actions to run unless there was a change, the equivalent of change in rule truth of a 3.0 Rule, we can do that explicitly using Private Boolean. In the example above, if one of the two motion sensors went inactive, and then became active again before the lights turned off, the actions would run again, turning the lights on again. Generally, this is harmless.

What this accomplishes is that once the lights are turned on from motion active, Private Boolean is set to false, and the lights will not be turned on again until the full delay timer has run its course and the lights have been turned off. When that happens, Private Boolean is set to true, and the whole cycle can repeat.

What about Triggered Rules?

All "rules" in Rule 4.0 are in effect Triggered Rules. The rules shown above, the equivalents in Rule 4.0 for Rules in 3.0, are all triggered rules. They each have a trigger event, and then conditional actions. Instead of a rule with Actions for True and Actions for False, as with other rules in 4.0 they simply use conditional logic in the actions to create an equivalent IF-THEN-ELSE structure.

Conditional Actions and Logical Expressions

Rule 4.0 clearly depends entirely on the conditional actions now available for making decisions in rules about what to do.

Unlike Rule 3.0, in Rule 4.0 IF-THEN-ELSE-ENDIF conditional blocks can be nested. The UI uses textual indentation to help guide you in keeping track of which IF-THEN-ELSE-ENDIF block you are currently adding actions to. It falls on you to complete each level of nested IF-THEN blocks.

In Rule 4.0 the condition of an IF-THEN or ELSE-IF action can be a full logical expression built up from individual conditions, and logical operators AND, OR, XOR, and NOT. Parenthesized sub-expressions are also possible. This is the same user interface used to create the rule portion of a Rule or Triggered Rule for Rule 3.0. An individual condition can be created 'on the fly' while defining a logical expression. Every such condition is kept in the list of available conditions. This list of available conditions is available on the Define Actions page. It can be opened, and presents the familiar user interface for creating, editing and deleting conditions. If a condition is edited, those changes will be reflected where it is used in an IF-THEN or ELSE-IF conditional action.

This combination of nested IF-THEN blocks and full logical expression for each IF-THEN and ELSE-IF allows creativity for rules in Rule 4.0 that is limited only by your imagination. To help you with complex logic structures, one more new action is provided: Exit Rule. With Exit Rule the execution of actions for that rule stops, irrespective of where in the rule it is. Pending delays are not cancelled, and current repetitions are not stopped. These can be managed separately if so desired with Stop Repeating Actions, Stop Rule Actions, and Cancel Delayed Actions, as appropriate.

Automatic Condition Creation

When Event Triggers are defined, corresponding conditions are created for most types. Some, like button, Certain Time, etc, do not have state and so have no corresponding condition. These created conditions are available in the Define Actions page for use in Conditional actions. These can be edited. For example, in the rule above where Motion Changed was the trigger event, there is an IF-THEN for Motion Active as the first action. Instead of having to create that by hand, it is automatically created. One needs to edit it to modify from using Changed to using Active.

Every condition that you create in a Conditional action is available for use in other actions, and can be edited.

Wait for Events and Elapsed Time

The Wait for Event action from Rule 3.0 has changed to Wait for Events. Multiple events can be defined to cause the wait to end. In effect, this introduces another trigger-like capability into the actions. There is also a new event type specifically for Wait for Events, Elapsed Time. When the Elapsed Time expires, the wait will be over, irrespective of other events the wait may be waiting for. Unlike Rule 3.0, Wait for Events and Wait for Condition may be used in a Simple Conditional Action.