Rule Machine
Contents
Introduction to Automation
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.
Events
An automation system is "event driven". The devices in your home automation system regularly generate events. An event is simply a small message a device or the hub sends out. For example, when you turn on a smart switch, it sends out an event reporting that it was turned on. One way to think of the automation system is that there is a constant stream of events. The role of the hub is to make sense out of this stream of events and to cause things to happen in the system.
An "automation" is a very small computer program that responds to events to cause something to happen. For example, an automation could respond to the event of a door contact opening by turning on a porch light. These "automations", or "rules", make up the brains of the home automation system, making it "smart".
Of all of the events occurring in the system, each automation is only interested in a few specific ones. To avoid having to process every single event, each automation "subscribes" to the ones it is interested in. Our example porch light automation subscribes to the events from the door contact sensor; it doesn't care about any other events. Its 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 hub's job is to send each automation just those events that the automation has subscribed to.
There are four basic types of events: device events, time events, hub events, and network events. Devices events are generated by the smart devices in the system, like the door contact sensor reporting 'open'. Time events are generated by a scheduler in the hub for things like sunrise, 5:00 PM, etc. Hub events are special events that the hub generates; for example the hub generates an event when it starts up. Network events are messages that come to the hub from the LAN or internet. Some devices use the LAN to send events, some use Z-Wave or Zigbee radio signals.
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. For example, a driver would receive a message from the Zigbee radio network sent by the door contact, and convert it into an event. Each smart device in the system has a corresponding driver installed in the hub. The hub serves as the traffic cop, forwarding device events to automations.
Automations
As mentioned above, an automation is a small app that runs on the hub. It's purpose is to respond to events by causing actions. Every automation has these two elements: the events that provoke it to act, and the actions if performs as a consequence.
Some automations are very simple. The one described where opening a door causes a light to turn on is very simple. We may want it to be more sophisticated. Suppose we only want the porch light to turn on when the door opens at night, not during the day. To accomplish this, the automation will need more than just the events and the actions -- it needs to evaluate *conditions*. Based on this evaluation of conditions, it may or may not do some action, or perhaps it will do different actions depending on the conditions. For our porch light automation, we want our rule to test what time it is, and decide based on that whether or not to turn on the light.
Now, we have a complete picture of what an automation is: It responds to *events*, evaluates *conditions* and then takes *actions* based on the conditions. All automations have this general form.
Rule Machine 4.0
Rule-4.0 is a built-in app in Hubitat Elevation® that can be used to create automations. Each rule created with it has the described form, with *Trigger Events* and *Actions*, and the *Actions* can have *conditions* to be evaluated as part of deciding what the automation does.
Rule Machine API
It is possible for other apps to use Rules, Triggers, Triggered Rules, and Actions 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, Triggers, Triggered Rules, and Actions from an HTTP request to an endpoint.
Using Rule Machine from other apps
First, import the RM helper class into your app:
`import hubitat.helper.RMUtils`
The List of Rules
Rule Machine maintains a list of available Rules, Triggers, Triggered Rules, and Actions. This list can be obtained with this method call:
def rules = RMUtils.getRuleList()
The resulting list, in this example in the variable "rules", can be used as an input to an "enum", as the options.
Supported Actions
It is possible to set the Private Boolean, evaluate a rule, 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 will each take this form:
def RMUtils.sendAction(rules, action, appLabel)
Set Private Boolean True:
action "setRuleBooleanTrue"
Set Private Boolean False:
action "setRuleBooleanFalse"
Evaluate Rule:
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 other function than logging.
Example:
def rules = RMUtils.getRuleList()
input "theseRules", "enum", title: "Select which rules to stop", options: rules
RMUtils.sendAction(theseRules, "stopRuleAct", app.label)
Using Rule Machine from HTTP requests
It is also possible to cause Rule Machine to perform these same actions from an HTTP request. To do this one would create a Trigger or a Triggered Rule with either a Local End Point or Cloud End Point. The endpoint URL given by Rule Machine has this form:
`http://192.168.0.36/apps/api/10249/trigger?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`
To run rule actions this URL must be modified to include the list of rules and the action. The modification takes this form:
`/action=rule1&rule2&rule3`
Where action is the action from the list above and `rule1&rule2&rule3` are the appIds of the rules to run separated by ampersands.
This parameter is inserted in the endpoint URL just before the ? that precedes the access_token, like this:
This example would do the same thing as the code example above, where 943&956&10217 are the appIds that were selected by consequence of the input for theseRules, and stopRuleAct is the action to perform.
The appIds are the values selected by the input described above, for example `theseRules`. The appIds can also be found for a rule by opening the rule and observing its appId in its url, like this:
`http://192.168.0.36/installedapp/configure/10249/mainPage`
The appId for that rule is 10249.
Get Rule List
To get the list of rules as is returned from `getRuleList()` use this insert for the URL:
`/getRuleList`
for full URL like this:
This returns a JSON object with appId and rule name pairs. The other requests return a JSON object with a human readable description of what was done.
Set Global Variable
A Global Variable 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 only work for Rule 2.5 or later. Rule Machine action Set Global Variable only works for Rule 3.0 or later.
Dedication
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.
