[Released] Rule 4.0


#1

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.

First, here is a screenshot of the new Rule 4.0 main page:

As you can see there is not a lot to it. 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:

As you can see above, 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.

Here is an example of the most basic rule, first from Rule 3.0:

And now the same rule in 4.0:

Notice a few things about this: 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:

The motion lighting rule from Rule 3.0:

And, in Rule 4.0 it looks like this, with an explicit action to cancel the delay:

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. If we want to prevent that redundant action, here is how that is done:

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.

More Examples

Here is a rule from Rule 3.0 that uses Time of Day in order to turn some fans on and off at set times every day. This use of Time of Day is less than fully obvious in a rule:

Here is the same functionality in Rule 4.0. Instead of a rule with two times and true/false logic, this is a simple straightforward trigger, using Wait for Event to get the second time, when the fans are turned off.

This next example starts from a Rule 3.0 implementation that took a rule and two triggers. The idea is to turn on a garage exhaust fan when the inside garage temperature is above 76° and above the outside temperature by a margin of 2°. The fan will draw cooler outside air into the garage until it's cooled down, or until the the outside temperature is greater than indoors. There are two such garage fans, and in the 3.0 example, both were turned on by a Rule, and then each individually turned off by a Trigger. Here is the Rule and one of the Triggers:


Now, in 4.0 I decided to restructure this into two rules, one for each fan. Below is the new 4.0 rule than replaces both the Rule and the Trigger above, using IF-THEN-ELSE-IF to determine when to turn the fan off:


Road Map and Vlan Support
Hub Update 2.1.2
Rule 4.0 bug?
Introduction to Automation
Rule Machine - This is Frustrating the Heck Out of Me
Rule Machine 4 - Actions for False
RM[4] UI Confusion / Feedback
Rule Machine - This is Frustrating the Heck Out of Me
Quick Rule Tutorial?
Rule documentation
Delay trigger in case state changes for door sensor
Troubleshooting motion lighting
#2

appreciate the hard work! Time for another paradigm shift. I can certainly see how this will be more intuitive for simple rules. I have a couple of questions:

Are multiple top level IF-THEN-ELSE statements allowed? or does everything have to be in a sub-rule?

Also, I don't fully understand this, can you further explain?

is this talking about custom actions, or something else?

thanks


#3

Will this take over the RM3 rules or will we need both RM3 and RM4?


#4

I would assume so. Much like rules created with earlier versions of RM work with RM3.


#5

Can't wait to try it. Let me know if you're looking for beta testers :slight_smile:

I think the Logic in Rule 4.0 will line up better with how I think through these things. Any guess when Rule 4.0 will hit the app list? I'm creating my rules and abusing Cobra's apps now, so I'm motivated.


#6

I am going to spare @bravenel typing the standard answer to this question: "When it is ready" :slight_smile:


#7

In previous iterations of RM existing rules carried on using the version they were built in even if you amended them.
I would think this would be the same with RM4.0.
So if you want to convert to RM4 I would think you will have to rewrite your rules.
Only my guess though. :wink:


#8

I like the “changed” concept. Does this mean we will have access to the previous value so that can be included in the action condition? For example if mode changes... if current value is Day and previous value was Stay do this, if current value is Away and previous value was Cleaning do that, etc. Some state variables have more than 2 values and having access to the previous value would be awesome.


#9

Because Rule 4.0 is a pretty sharp departure from classic RM, both Rule-3.0 and Rule-4.0 will be available for some time. We will retire Rule-3.0 in the future. You don't "need" both. Old rules, irrespective of version ("Rule", "Rule-2.5", "Rule-3.0") will still work and don't need to be changed or converted to Rule 4.0. Most of my rules in my home system are the old "Rule", never updated.


#10

This is talking about the ability to edit conditions created in actions. When you create a condition, it becomes available to be edited, and used in conditional actions. You can also simply create conditions for use in conditional actions

There are two ways to create conditions: First, is right in the creation of a conditional action. Second is in the new section of Action definition where you can create, edit and delete conditions. These are the conditions used in actions.


#11

Not explicitly. However, this is an interesting idea that I will think about. The previous values are obviously stored.


#12

So once I install rm4 the rm3 rules will show up there and rm3 will be gone?


#13

In the type column you can see what RM version your rule was built on.
If you don't rewrite the rule from new then the rule will continue to use the version it was built with.
By default, when you build a brand new rule it will use RM4.0 when it is introduced.

image


#14

Actually, in the first release, you can choose whether to create a Rule 4.0 or Rule 3.0.


#15

I’ll hold off making too many rules and getting my head around RM3.0 then :joy:


#16

Oops. My fault. :blush:
I just made the assumption that the new version would be the default with no choice.


#17

You'll find 4.0 easier to get your head around.


#18

Only one thing I have to say:

WOW!!!

Gone are the Rules,Trigger,Triggered Rules, Actions...YES, finally!
I was hoping for something like this. There were too many options to choose from and it was confusing.
Simplicity is the key!

GREAT job Bravenel.

Can wait to get my hands on it.


#19

I do find what you described more logical....I also swear if said coming soon and now says released.


#20

Yep, soon becomes now at some moment.