Rule Machine is the most powerful built-in tool for creating custom automations in Hubitat Elevation.
Tip: Rule Machine is very powerful but can be somewhat complex for new users. Before using Rule Machine, you may wish to consider if a built-in app (Motion Lighting, Notifier, etc., or Basic Rule for simpler custom automations) meets your needs.
For documentation on how to use Rule Machine rules, see the documentation for the appropriate Rule version:
The remainder of this document focuses on general platform/event concepts that are helpful to know when using Rule Machine (any version). It also covers how to use the Rule Machine API from a custom Groovy app on Hubitat or over HTTP endpoints.
A home automation system is a collection of smart devices and a Hubitat Elevation hub. The objective of the system is to provide automatic control of various devices in the home based on events and conditions. This introduction explains the structure of the system and the way that it operates. Understanding these concepts is essential to being able to design your own home automation system.
An automation system is "event driven". The devices in your home automation system regularly generate events. An event is simply a small message that a device or the hub sends out.
An "automation" is a very small computer program which responds to events, and results in something happening.
Of all of the events occurring in the system, each automation is only interested in a few specific events. To avoid having to process every single event, each automation "subscribes" to the ones it is interested in. In our previous example of the porch light, an automation subscribes to the events from the door contact sensor, and ignores all other events in the system. Its single job is to turn on a light when that contact opens. Each automation in a system has subscriptions to the events it is concerned with. The job of the hub is to send each automation, only the events that it for which it has subscribed.
There are four basic event types:
For every device event or network event to be processed so that an automation can respond to it, there must be a "driver" in the system.
As explained above, an automation is a small app that runs on the hub. Its purpose is to respond to events by causing actions.
Every automation has two elements:
Some automations are very simple. The one described where opening a door causes a light to turn on is very simple, but you may want or need it to be more sophisticated. Suppose you only want the porch light to turn on when the door opens at night, but not during the day. To accomplish this, the automation will need more than just the events and the actions, so it will need to evaluate Conditions. Based on this evaluation of conditions, it may or may not perform an action, or it could perform different actions depending on the conditions that are evaluated. Expanding on the porch light automation example, you could have the Rule also test what the time is, and the result from that additional evaluation of the Time event would determine if the light should turn on when the contact sensor is opened.
You should now have a complete picture of what an automation is all about, with the understanding that all automations have this general form.
It is possible for other apps to use rules defined in Rule Machine. This is very similar, and uses the same mechanism, as actions in Rule Machine that affect other rules. It is also possible to use rules from an HTTP request to an endpoint.
First, import the RM helper class into your app:
import hubitat.helper.RMUtils
Rule Machine maintains a list of available Rules, Triggers, Triggered Rules, and Actions. That list can be obtained with this method call.
def rules = RMUtils.getRuleList()
In this example, the resulting list of the variable rules can be used as an input to an "enum" as the options in app code.
By default, getRuleList() will return Rule Machine Legacy rules (for compatibity reasons). The version number can optionally specified as a string. To return Rule 5.x rules (in "new" Rule Machine), call:
def rules = RMUtils.getRuleList("5.0")
It is possible to set Private Boolean, evaluate a rule (for supported versions), run the rule actions, or stop running rule actions (either delayed or repeating). This is accomplished by sending an action request to Rule Machine. These take the following form.
def RMUtils.sendAction(rules, action, appLabel)
This, again, defaults to Rule Machine Legacy, but an optional fourth parameter for version can be provided:
def RMUtils.sendAction(rules, action, appLabel, "5.0")
Here are possible values for action:
Set Private Boolean True:
action: "setRuleBooleanTrue"
Set Private Boolean False:
action: "setRuleBooleanFalse"
Evaluate Rule (not applicable to Rule 4.x and newer):
action: "runRule"
Run Rule Actions:
action: "runRuleAct"
Stop Rule Actions:
action: "stopRuleAct"
Pause Rule:
action: "pauseRule"
Resume Rule:
action: "resumeRule"
In each case above, a list of Rules selected by input is sent. The rule options come from the variable to which they were input as described above, in the options section of the input.
The appLabel parameter is passed and will appear in the log entry that the rule makes when it performs the action commanded. Typically, simply pass app.label for the name of the app that is causing the action. This has no function, other than logging.
Example:
def rules = RMUtils.getRuleList("5.0")
input "theseRules", "enum", title: "Select rules whose actions to run", options: rules
RMUtils.sendAction(theseRules, "runRuleAct", app.label, "5.0")
It is also possible to cause Rule Machine to perform these same actions from an HTTP request. To accomplish this, you would create a trigger event with either "Local End Point" or "Cloud End Point." The endpoint URL given by Rule Machine has a form similar to the following:
http://192.168.0.36/apps/api/10249/trigger?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db
To run rule actions the above URL must be modified to include the list of rules and the action. The modification takes the following form:
/action=rule1&rule2&rule3
where action is the action from the list above and rule1&rule2&rule3 are the app IDs of the rules to run, separated by ampersands.
This parameter is inserted in the endpoint URL just before the ? that precedes the access_token as follows.
http://192.168.0.36/apps/api/10249/trigger/stopRuleAct=943&956&10217?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db
This example would do the same thing as the code example above, where 943&956&10217 are the app IDs that were selected by consequence of the input for theseRules, and stopRuleAct is the action to perform.
The app IDs are the values selected by the input described above, for example, theseRules. The app IDs can also be found for a rule by opening the rule and observing its appId in its URL as follows.
http://192.168.0.36/installedapp/configure/10249/mainPage
The app ID for that rule would be 10249.
Optionally, the value of the rule's built in %value% variable (normally set to the value of a trigger eevent) can be specified by providing a string instead of an action name, as with myValue in this example (note that this value must be URL-encoded and not conflict with the name of an action):
http://192.168.0.36/apps/api/10249/trigger/myValue?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db
Both HTTP GET and HTTP POST to the above endpoints are supported, with the same outcome for either.
To get the list of rules as returned from getRuleList() , use the following insert for the URL.
/getRuleList
Here's an example of how you would use a full URL:
http://192.168.0.36/apps/api/10249/trigger/getRuleList?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db
This returns a JSON object with app ID and rule name pairs. The other requests return a JSON object with a human-readable description of what was done.
A hub variable can be set by an endpoint trigger. The format for the parameter is this:
/setHubVariable=varName:varString
The varString portion is assumed to be URL encoded, and is URL decoded before being stored into the varName hub variable.
Full URL example:
http://192.168.0.36/apps/api/10249/trigger/setHubVariable=myVariable:example%20value?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db
A global variable (Rule Machine Legacy only; see above for hub variables) can be set by an endpoint trigger. The format for the parameter is this:
/setGlobalVariable=varName:varString
The varString portion is assumed to be URL encoded, and is URL decoded before being stored into the varName global variable.
NOTE: Rule Machine actions Stop Rule Actions, Pause Rule and Resume Rule work for only Rule 2.5 or later. Rule Machine action Set Global Variable works only for Rule 3.0 or Rule 4.0. Set Hub Variable works for only Rule 5.1 or later.
Rule Machine is dedicated to Alan Turing. He gave us the concept of an abstract machine that could compute, and from that we built small implementations of his vision. Today, we all use them every day of our lives.