Rule 3.0

New Version of Rule Machine: Rule 3.0

We are introducing a new version of Rule Machine, with Rule 3.0. Rule 3.0 is a new child app for the parent Rule Machine. Existing child app instances that are installed, Rule and Rule 2.5, will continue to function as before. New rules that are created will be Rule 3.0. This release marks the end of development for Rule 2.5, just as its release marked the end of development for Rule. There is no reason to recreate existing old rules in Rule 3.0, unless you want to. The author still has a majority of his rules running the original Rule child.

In recent releases of Rule 2.5, a major effort was made to redo the UI for defining Conditions, Trigger Events, and Rules. In each case, the UI was streamlined and flattened to a single page. The ability to easily edit Conditions, and redo Rules was introduced. Rule 3.0 brings this same UI overhaul to Action definition. The UI is streamlined and flattened, and actions can be easily edited. But, the changes don't stop there: Rule 3.0 introduces considerable new power and flexibility to Rule Machine actions.

New Features

Rule 3.0 represents a complete overhaul of action definition. There are a number of new concepts and capabilities provided.

Actions as ordered script

As you define actions you are creating a script of actions to perform when the rule runs. Instead, for example, of only being able to have a single action for turning on switches in Rule 2.5, you can now have as many actions for each action type as you want. And these actions can be run in whatever order you want. No longer is there a predefined order of execution for RM actions -- it's up to you to order the actions however you want. You can insert a new action anywhere in the list of actions, or at the end of the list.

Actions can be edited

The UI provides the facility to edit or delete any action you have defined, giving you complete control over your list of actions.

[1]

Delay per action and Delay (Pause) all actions

There are three types of delays included in Rule 3.0: 1. Each individual action can have its own delay, which for Rules may include a cancel-on-truth-change option. 2. All actions can be delayed, effectively pausing the action execution for some amount of time. 3. All actions can be delayed for a period of time that depends on the current mode (Delay Actions Per Mode).

These are further described below.

Delay per action

Each action you define can have an optional delay. These delays can be defined with hours, minutes, and seconds. Seconds can have decimal fractions, allowing millisecond resolution. In a Rule, delays can have the option to be cancelled in the event of a change of rule truth.

Delay all actions

It is also possible to delay all actions (also with optional cancel). The script of actions runs sequentially when the rule runs, with each action happening in order. Actions with delays start their timer, which can vary for each action, and the next action in order then runs. By using the Delay Actions action the entire script can be 'paused' by a delay. This feature can also be specified on a per mode basis, so that the time the script is paused varies according to the current mode.

As a consequence of these new features, some of the actions in Rule 2.5 have not been included in Rule 3.0. Specifically, those actions which incorporated a delay, or a delay with cancel, have not been included, since now every action can have such delays.

Conditional Actions

Each action can have a condition tested to control whether or not it is executed. These conditions offer the same choices as those used to define rules, but are independent of the Conditions of a Rule. When such a conditional action is edited, the condition may be edited as well. This simple condition applies to a single action.

IF-THEN-ELSE

You can introduce conditional execution of actions using:

 IF (condition) THEN 
     some actions...
ELSE-IF (condition) THEN 
     some actions...
ELSE 
     some actions...
ENDIF  

IF-THEN and ELSE-IF both accept a condition as described above. IF-THEN-ELSE may not be nested. If the condition on the IF part is true, then those actions following the IF and before any ELSE-IF or ELSE statements are run. If the condition is false, then those actions are skipped, and the ELSE part or ELSE-IF part are run. In the case of ELSE-IF, its condition is tested, and the following actions run or not depending. There can be as many ELSE-IF sections as you want, and both ELSE-IF and ELSE are optional. ENDIF is also optional, and if omitted means all remaining actions are part of the preceding IF-THEN, ELSE-IF or ELSE.

New Repeat Actions

Portions, or all of, the script of actions can be repeated, similar to Rule 2.5's Repeat These Actions. As with Rule 2.5, this supports stopping repetition upon rule truth change for a Rule, and allows for a selected number of iterations. When a Repeat Actions is introduced to the script, following actions will be repeated. A new feature, End Repetition, can be placed in the script. When this is done, only those actions between Repeat Actions and End Repetition are repeated.

Repeat Actions
        some actions...
End Repetition

A Repeat Actions, like any action, can have a condition specified. If the condition is false, the Repeat Actions block of actions will not be executed. If the condition becomes false during repetition, the repetition will be stopped (not in the case of Repeat a selected number of times). This provides three features well known to computer programmers; A while-loop, a for-loop and repeat-until loop. The while-loop runs only if the condition is true, and stops if it is false. A for-loop runs for a fixed number of times, but if a condition exists, it will only start that iteration if the condition is true; the condition is not retested during iteration. A repeat-until loop runs until a condition becomes true, running at least once.

While loop - repeat while the condition is true:

IF (condition) Repeat Actions
       some actions...
End Repetition

For loop (repeat n times):

Repeat Actions n times
       some actions...
End Repetition

Conditional For loop (repeat n times if condition is true): IF (condition) Repeat Actions n times

       some actions...

End Repetition

Repeat-Until loop: Repeat

       some actions
  IF (condition) Stop

End Repetition

Repeat Actions may not be nested. End Repetition is optional, and if omitted, all actions after Repeat Actions are repeated. Note the "End Repetition" does not have anything to do with the when the Repeated Actions will stop repeating -- it merely marks the end of the list of actions to be repeated. If you use Repeat These Actions without N Times (for loop), and without a Condition (while loop), and without a Conditional Stop, and without Stop on Truth Change (for rules only), that means to repeat forever. That is probably not what you want to have happen. In this case, some other rule would need to cause the repetition to stop.

New Custom Actions

In addition to Custom Commands as have been available in prior versions, Rule 3.0 introduces Custom Actions. A Custom Action allows you to select a device, and send any of the commands that device supports along with parameters it may take. While Custom Commands are pre-defined and available to all rules, a Custom Action is created within your actions and is specific to the rule where it is created.

Global Variable Improvements

Global Variables are now displayed on Rule Machine main page. When creating one, it must be initialized. Global variable values can also be changed in Rule Machine. When a global variable is deleted, a warning is given if the variable is in use in a rule/trigger et al, and if deleted anyway, they are removed from the rule where they are in use. This removal may leave such a rule with holes in it. Conditions based on variables will be removed, which in turn may erase the rule definition. Actions that set variables will be removed. Variables used in comparisons will leave the comparison missing what is to be compared. Actions with dimmers/bulbs set by variables will have missing settings. Manage your global variables with some care to avoid problems.

Global Variables Can Be Used for Level/Color

Global variables can be used in actions that set dimmer or bulb levels, color temperature, or hue/saturation values. To use a variable in this way, include it with %global-variable-name%. In each case only a "Number" global variable is allowed, and it is not range checked

Global Variables can be set by endpoint

A string Global Variable can be set by an endpoint trigger. This is an addition to the [Rule Machine API](https://community.hubitat.com/t/rule-machine-api/7104).

Global Variables can be used with parameters for Custom Actions

A Global Variable can be used with parameters by using %global-variable-name%.

Global Variables in messages

Unlike Rule 2.5, in Rule 3.0 to include the value of a global variable in a message string (or HTTP request url or body), use %global-variable-name%.

Run rule from UI

In prior version of Rule Machine, upon hitting Done on the main page of a Rule, that Rule would be evaluated. This behavior was problematic, as unintended actions would sometimes take place upon that event. In Rule 3.0 this is no longer the case. Instead, each Rule, Trigger, Triggered Rule and Actions has a button on the main page to run the rule. In the case of a Rule or a Triggered Rule the actions run as a consequence of this are determined by the truth of the rule, which is displayed at the bottom of the rule definition and in the app name at the top of the page. In the case of Trigger and Actions, the actions are simply run. In each case, hitting Done on the main page does not cause any action, although it does establish event subscriptions and schedules for the rule.

Other new features

New HTTP action

A new HTTP request action is now available: send an HTTP Post. This accepts URL and a body, which may be JSON, XML, or form encoded.

New Siren Actions

Rule 3.0 now offers actions to control a siren device, with commands siren, strobe, both and off.

New Dimmer Actions

Start raising, start lowering, and stop changing dimmer levels added.

New Color Action

Color per mode is now available.

Set Color Temperature

Set Color Temperature now has option to set the level in same action.

Shade Actions

Shade actions now use the Window Shade capability. Available action are open, close and set position.

Fan Speed and Fan Actions

Capability "Fan Speed" is now supported for Conditions and Trigger Events. This uses the Fan Control capability used for fans. A new action, Set Fan Speed, is available. The Adjust Fan action is changed from controller of fan-as-dimmer, to using Fan Speed commands: low, medium-low, medium, medium-high, high, on, off and auto.

Power Source Capability

Capability "Power Source" is now fully supported for Conditions and Trigger Events. This supports two states: mains and battery.

Screen Shots

Editing Set Global Variable: [2]

IF-THEN Example: [3]