Rule Machine

The Unofficial SmartThings Blog
Jump to: navigation, search

Rule machine icon.png

Rule Machine

Author: Bruce Ravenel / @bravenel

  • Rule Machine is a generalized rule engine for SmartThings. It allows you to predicate actions to be taken in SmartThings by a logical rule based on specified conditions of your system. Rule Machine also provides triggers, basic event-causes-action building blocks. Rules and triggers can work together to create sophisticated automations.

Latest Version

  • Rule Machine 1.6.6
  • Rule 1.6.12

What are rules?

A rule is a method of specifying certain conditions and their truth relationships in order to cause some action to take place in SmartThings. For example, one person posed this case:

Suppose my presence or my wife’s presence is home, there is motion in the bedroom, it’s between 8 PM and 11 PM, and the temperature is below 65 — if those conditions are met, turn on the electric blanket.

In order for this action to take place in SmartThings, based on those conditions, Rule Machine will evaluate those conditions, and if they are met, turn on the blanket. Rule Machine allows you to specify the conditions, the rule they must meet, and the desired actions to take place.

What are triggers?

A Trigger is a simple mechanism through which some event in your system causes a selected action to take place. This is a basic building block of automations.

For example: if the door opens, turn on the light.

Triggers are simpler than rules — they don’t care about conditions, they just do whatever it is to be done when selected events happen. But, you can add conditions and a rule to triggers. When you do this, the trigger causes those conditions to be tested under the rule, and then actions are taken based on the rule truth outcome. More on this below.

You can select multiple triggers. In this case, any of the trigger events selected will cause the action or rule evaluation.

What are conditions and events?

  • Rule Machine allows a wide range of possible conditions and events to be selected. For rules we select conditions. For triggers we select events. Conditions and events are closely related because each event results in a condition. For example, the door opening is an event and results in the condition of the door being open. Both rules and triggers rely on events to cause their actions. Rules examine the conditions, and act on truth change. Triggers act on events.

Events are created by the devices in your system. Each device creates events appropriate to the type of device. When you create a rule, Rule Machine listens for any event that might affect the truth of the rule. When a rule receives a selected event, it evaluates the truth of its rule, and then takes selected actions based on that evaluation. A trigger also listens for events. When a trigger receives a selected event, it either takes the selected actions unconditionally (if no conditions were specified), or it causes the conditions to be evaluated under the rule and actions taken accordingly.

Rule Machine allows the following conditions/events in a SmartThings system to be tested in a rule or acted upon in a trigger. Each condition results in a single test. There may be as many conditions as you want in a rule, or as many event triggers as you want in a trigger. The supported conditions, events and states that can be tested are listed below. Note: Days of week and Time of Day are not available in a trigger. There are additional events available for triggers; see below.

   Acceleration:    active / inactive
   Battery:             compare current value to a number or to another device
   Contact:	      open / closed
   Days of week:   Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
   Dimmer level:    compare current value to a number or to another device
   Energy meter:   compare current value to a number or to another device
   Garage door:    open / closed
   Humidity:	      compare current value to a number or to another device
   Illuminance:      compare current value to a number or to another device
   Lock:	              locked / unlocked
   Mode:	              any of your location’s modes
   Motion:	      active / inactive
   Power meter:    compare current value to a number or to another device
   Presence:	      present / not present
   Rule truth:         true / false
   SHMonitor:        alarm state
   Switch:	      on / off
   Temperature:    compare current value to a number or to another device
   Time of day:      between two times, including sunrise / sunset with offsets
   Water sensor:   dry / wet

Triggers respond to these additional events:

   Button:          pressed / held
   Certain Time:    at a certain time, including sunrise / sunset with offset
   Physical switch: on / off
   Routine:         runs

For each condition/event that refers to a device, one or more devices can be selected, and then the device state required for the condition to be met can be selected. When multiple devices are selected, the condition/event may apply for ANY (default) or ALL of the devices.

For example, the conditions for the electric blanket case are,

   my presence or my wife’s presence is present (ANY)
   bedroom motion is active
   time of day is between 8:00 PM and 11:00 PM
   bedroom temperature is <  65

Limitation: a rule may only have at most one each of Days of week, Mode, or Time of day as conditions. If you need logic for two different Time of day periods, that would have to be done in two separate rules. A trigger can have at most one each of Certain Time or Mode change as a trigger event. If you need more time events, that would have to be done in two separate triggers.

How is a rule defined?

A rule is a logical expression built up using the conditions and the two logical operators `AND` and `OR`, along with parenthesized sub-rules, each of which is itself a logical expression. A logical expression defines the logical relationship between the various conditions. In order to decide if the end action should be taken or not, Rule Machine evaluates the truth of the defined rule. In the electric blanket case, we have a very simple rule:

   my presence or my wife’s presence is present AND
   bedroom motion is active AND
   time of day is between 8:00 PM and 11:00 PM AND
   bedroom temperature is <  65

There can be more complex rules than this. Suppose we want the same basic rule, but want it to apply if either bedroom motion is active or the bedroom door is closed. We would add the additional condition of “bedroom door is closed”. That rule would be this:

   my presence or my wife’s presence is present AND
   (bedroom motion is active OR bedroom door is closed) AND
   time of day is between 8:00 PM and 11:00 PM AND
   bedroom temperature is <  65

In this example, we have used parentheses to group two conditions into a sub-rule: (bedroom motion is active `OR` bedroom door is closed). Rule Machine allows arbitrarily complex rules to be defined, with parentheses used to group conditions into sub-rules. To use this feature of sub-rules in parentheses, you must first turn on the "Advanced Rule input" option, found under More Options at the bottom of the main page. It allows nested sub-rules to any depth, and it allows any number of conditions. To help you see exactly the rule you are building, Rule Machine displays the partial rule at each step as you define it. See screen shots in a following post.

Rule Machine is a fully generalized rule engine. The logical expression can be described as a sequence of terms, separated by operators, where each term is either a condition or a parenthesized sub-rule (available with Advanced Rule input enabled, under More Options), and the operators are `AND` and `OR`. There is no need in Rule Machine for a `NOT` operator, because each condition can be stated in the negative. The evaluation of a rule or sub-rule is strictly left to right. If at any point in the evaluation, the truth value preceding an `AND` operator is `false`, the sub-rule or the rule itself is `false` without further evaluation. Similarly, if the truth value preceding an `OR` operator is `true`, the sub-rule or the rule itself is `true` without further evaluation. For those familiar with coding, there is no operator precedence. Each rule or sub-rule may have as many terms as desired.

Rule Evaluation

Once Rule Machine is installed with conditions, rule, and actions, what happens next? Whenever something happens in SmartThings that could affect the conditions, Rule Machine evaluates the rule to see if it is `true` or `false`. If it becomes `true`, then it will take some selected actions; if it becomes `false`, it can take some other selected actions. In the case of the electric blanket, the rule would be evaluated whenever any of the following things happen:

   my presence or my wife’s presence arrives or leaves
   the bedroom motion goes active or inactive
   the bedroom door is opened or closed
   the time becomes 8:00 PM, or becomes 11:00 PM
   the bedroom temperature is reported

Since our rule for this case involves all of these possible events, any of those events might be the one that changes the evaluation outcome from `false` to `true`. If that happens, Rule Machine will turn on the electric blanket.

Rule Machine only acts on the change of rule state from `false` to `true`, or `true` to `false`, except in the case of a trigger event causing rule evaluation. It may evaluate the rule many times, depending on what sort of events are subscribed to, but only a truth change causes action. A trigger causing rule evaluation will result in action if the rule is true, without regard to prior rule truth or rule truth changing.

The evaluation of a rule is strictly from left to right. If at any point in the evaluation, the truth value preceding an `AND` operator is `false`, the rule is `false` without any further evaluation. Similarly, if the truth value preceding an `OR` operator is `true`, the rule is `true` without any further evaluation. You must take this into consideration as you define your rule, if you have many terms.

Actions for Rules and Triggers

When the rule proves `true`, after previously `false`, or it’s true after being triggered, Rule Machine will do the actions selected on the Actions for True page. When the rule proves `false`, after previously `true`, or it’s false after being triggered, Rule Machine will do the actions on the Actions for False page. The actions supported are the following:

   Delay these actions by minutes, seconds, or milliseconds, with optional cancel on change
   Switches to turn on
   Switches to turn off
   Switches to toggle
   Switches to turn on/off after a delay 
   Switches to turn on/off after a delay, cancellable
   Dimmers to level A, or to track
   Dimmers to level B
   Dimmers to toggle
   Dimmers to adjust +/-
   Set color temperature
   Set colors
   Locks to lock
   Locks to unlock
   Fans to adjust — low, medium, high, off
   Valves to open
   Valves to close
   Thermostats to set
   Set SHM alarm state
   Change mode
   Run Routine
   Evaluate rules
   Send push, speak or SMS message, with triggering device name
   Take photos
   Custom commands


Note: If you want to use Rule Machine in motion on/off situations, be sure to use "Cancel on truth change" option for the delay instead of a simple delayed on/off. This action allows renewed motion to stop the turn-off timer.

Rule - Trigger Integration

One of the most powerful features of Rule Machine is the ability of Rules and Triggers to be combined to create sophisticated automations. Just as with the devices in your system, the Rules you have in Rule Machine have a state, their truth state. Both Rules and Triggers can use rule-truth as a condition or as an event. This leads to many possibilities, several of which are very useful:

A Trigger can use rule-truth as an event. When a Rule changes state, a Trigger can take actions. This integration allows you to have additional actions for each Rule. If you need more Actions for True, simply create a Trigger tied to rule-truth for that Rule becoming true, and you have additional actions available in the Trigger. For example, suppose you want one Rule to start a sequence of actions. Perhaps do one thing after 3 minutes, something else after 10 minutes, and then a final thing after 30 minutes. One Rule plus two Triggers can do this, where each Trigger is tied to the rule-truth, then has an action that it delays taking for 10, or 30 minutes; the rule itself has the action of true of doing something after 3 minutes.

A Rule can also use rule-truth as a condition. This feature allows generalized linking of Rules. One example would be to have a master set of conditions, that several Rules would need. One Rule has those conditions but no actions. The other Rules have the first rule-truth as a condition, and have whatever additional conditions they need, and take whatever actions they want. This can make repetitive rule creation much simpler, or lead to very sophisticated automations.

Both Triggers and Rules can take an action to cause a selected Rule (or Rules) to be evaluated. This would allow, for example, a button to cause a Rule to be evaluated, through the use of a Trigger tied to the button. Or, at a certain time of day, a Rule can be caused to be evaluated. The reason these things might be useful, is that ordinarily a Rule only takes action when it changes truth state. By causing a rule evaluation, the actions will be taken as selected for that Rule based on its truth, irrespective of the prior state of the rule-truth for that Rule.

Caution: Rules that use multiple rule-truths as conditions will fail due to race conditions when installed. You must avoid using multiple rule-truth conditions in a single Rule. Triggers do not have this issue; multiple rule-truth events in a Trigger are treated such that any of the Rules proving true/false (as selected) causes the Trigger to take action. This is a bug that will be addressed, so that it is not possible to enter multiple rule-truths in a rule.

Expert Features

Additional information and discussion thread maintained by Mike_Maxwell https://community.smartthings.com/t/rule-machine-expert-features/33148

There is an Experts Features section of Rule Machine that allows control over virtually any device, including custom device types and otherwise not supported devices. This feature allows commands to be sent to such devices as actions of rules or triggers. See the post below for more details:

Rule Machine Expert Features Bruce has been gracious enough to humor my request to add some previously unavailable functionality (unavailable anywhere), to his fantastic Rule Machine38.

Expert Features extends the Select Action choices in your rules with a new Run custom device command option. This feature allows you to control devices that have custom (IE non stock, un published or yet to be published capabilities) These devices could be devices that you or someone else has created.

Notable examples of published devices with custom capabilities:

  • Fibaro RGBW controller, all of the buttons in the device detail tile have associated custom commands.
  • Sonos and other Speaker devices, playTrackAndRestore and playTrackAndResume being two.
  • Thing Shields, every thing shield has nothing but custom commands, you can now run these commands directly from Rule Machine.

Have a multi channel relay, and you want to ditch all those virtual switches?, well here you go...

Basically any device that formally required a custom smartApp to support could be a candidate to migrate and control using Rule Machine.

Here's a few examples that I'm using in Rule Machine

The cool thing about expert is you don't even need to know what commands the device supports, it will give you a list to choose from and experiment with. (see cautions below)

There are two steps required to use custom commands in your rules.

  • Create/test and save your command
  • Select the device and command to execute in your rule

Create/test and save your command

  • Open Rule Machine
  • Select Expert Features, then Configure Custom Commands
  • Select a device to extract the available commands from (any device with capability actuator will be shown)
  • Select New Custom command, then select Available device commands (all standard and custom commands will be displayed)
  • Select the command you wish to create from the above list, the results of the command execution will be immediately shown.
  • Add any required parameters to the command.
  • After the command is executing against the device as expected, select save command now, then done, then done again to return to the Custom Commands page.
  • The saved command will now be available in the "saved command to test" list, and also in your new and existing rules.

Select the device and command to execute in your rule --Create a new rule or edit an existing one --In the Actions section (at the very bottom), select the custom device(s) and the command (saved above) to execute against them. --If multiple devices are selected, each one should support the selected command, any errors will be trapped and show in the logs.

Managing commands One or more commands can be removed by selecting them in Delete Custom Commands, then Delete commands now, then done.

Tips --Un-select your test device or the "saved command to test" before leaving the custom commands page, otherwise the command will execute the next time you open the page. --Un-Select "available device commands" after saving the new command, otherwise the command will execute the next time you open the page. --Un-Select "parameter type" for each of your parameters, in reverse order (ie 3,2,1) after saving the new command, this is just a convenience thing. --The success or failure of any parameters can't be determined by expert, use the logging in the IDE if you're having issues getting a command to function. --If your wizBang device isn't in the list, add capability actuator to it.

Cautions Expert will expose commands on device types that aren't published by ST, when you find these commands and play with them, you are doing so at your own. Neither Bruce, ST or myself are going to have any sympathy when you successfully execute wipeDisk() on your new Samsung appliance and have bricked it. So, be advised it's probably better to play with device types and commands that you have the code for, there I said it.

Installation

There are two SmartApps on Github.

  • The first is called "Rule Machine".
  • The second app is called "Rule".

After you install "Rule Machine" and "Rule", you can install "Rule Machine" in your mobile app. It can be found in the Marketplace, under SmartApps, My Apps. When you install it, the first thing you should do is click on Done in the upper right hand corner. After that, Rule Machine will appear in the list of your installed SmartApps.

Please report bugs should you encounter one, in the SmartThings Community Rule Machine topic.

Here are links to the two SmartApps you need:

Rule Machine - You should install this in the IDE and Publish For Me.

Rule - This you should install in the IDE, and Publish For Me. Rule Machine is a parent-child app, where you can create as many rules or triggers as you want, each an instance of Rule

Screenshots

Rule machine screenshot1.jpg Rule machine screenshot2.jpg Rule machine screenshot3.jpg Rule machine screenshot4.jpg Rule machine screenshot5.jpg Rule machine screenshot6.jpg