Difference between revisions of "Rule Machine"

From Hubitat Documentation
Jump to: navigation, search
m
Line 1: Line 1:
<h3>Introduction to Automation</h3>
+
{{Top}}<h3><big>Introduction to Automation</big></h3>
  
A home automation system is a collection of smart devices and a Hubitat Elevation<sup>®</sup> 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.
+
<big>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.</big>
  
<h4>Events</h4>
+
<h4><big>Events</big></h4>
  
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.  
+
<big>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.</big>
  
*'''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 make actions happen in the system.
+
*<big>'''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 make actions happen in the system.</big>
  
====Automations====
+
====<big>Automations</big>====
An "automation" is a very small computer program which responds to events, and results in something happening.
+
<big>An "automation" is a very small computer program which responds to events, and results in something happening.</big>
  
*'''Example''': An automation could respond to the event of a door contact opening by turning on a porch light. These '''automations''' (e.g. Rules), make up the brains of the home automation system, delivering the "Smart" of a Smart Home.
+
*<big>'''Example''': An automation could respond to the event of a door contact opening by turning on a porch light. These '''automations''' (e.g. Rules), make up the brains of the home automation system, delivering the "Smart" of a Smart Home.</big>
  
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.
+
<big>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.</big>
  
'''Event types'''
+
'''<big>Event types</big>'''
  
There are four basic event types:
+
<big>There are four basic event types:</big>
  
#Device events
+
#<big>Device events</big>
#*Devices events are generated by the smart devices in the system, like the door contact sensor reporting 'open'.
+
#*<big>Devices events are generated by the smart devices in the system, like the door contact sensor reporting 'open'.</big>
#Time events
+
#<big>Time events</big>
#*Time events are generated by a scheduler in the hub for things like sunrise, 5:00 PM, etc.
+
#*<big>Time events are generated by a scheduler in the hub for things like sunrise, 5:00 PM, etc.</big>
#Hub events
+
#<big>Hub events</big>
#*Hub events are special events that the hub generates
+
#*<big>Hub events are special events that the hub generates</big>
#**'''Example''': The hub generates an event when it starts up.
+
#**<big>'''Example''': The hub generates an event when it starts up.</big>
#Network events
+
#<big>Network events</big>
#*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.
+
#*<big>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.</big>
  
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.
+
<big>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.</big>
  
*'''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'''.
+
*<big>'''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'''.</big>
  
====Components of an Automation====
+
====<big>Components of an Automation</big>====
As explained above, an '''automation''' is a small app that runs on the hub. Its purpose is to respond to events by causing actions.   
+
<big>As explained above, an '''automation''' is a small app that runs on the hub. Its purpose is to respond to events by causing actions.</big>  
  
Every automation has two elements:   
+
<big>Every automation has two elements:</big>  
  
#The events that provoke it to act.
+
#<big>The events that provoke it to act.</big>
#The actions it performs as a result.
+
#<big>The actions it performs as a result.</big>
  
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.  
+
<big>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.</big>
  
You should now have a complete picture of what an automation is all about, with the understanding that all automations have this general form.
+
<big>You should now have a complete picture of what an automation is all about, with the understanding that all automations have this general form.</big>
  
*An automation responds to '''Events'''
+
*<big>An automation responds to '''Events'''</big>
*Evaluates '''Conditions'''
+
*<big>Evaluates '''Conditions'''</big>
*Performs '''Actions''' based on the '''Conditions'''.
+
*<big>Performs '''Actions''' based on the '''Conditions'''.</big>
<h3>Rule Machine 4.0</h3>
+
<h3><big>Rule Machine 4.0</big></h3>
  
[[Rule-4.0|Rule 4.0]] is a built-in app in Hubitat Elevation<sup>®</sup> that can be used to create automations. Each rule created with Rule Machine<sup>®</sup> has the described form.
+
<big>[[Rule-4.0|Rule 4.0]] is a built-in app in Hubitat Elevation that can be used to create automations. Each rule created with Rule Machine has the described form.</big>
  
*'''Trigger Events'''
+
*'''<big>Trigger Events</big>'''
*'''Actions -''' Actions may have '''Conditions''' to be evaluated as a step in determining what the automation does.
+
*<big>'''Actions -''' Actions may have '''Conditions''' to be evaluated as a step in determining what the automation does.</big>
<h3>Rule Machine API</h3>
+
<h3><big>Rule Machine API</big></h3>
  
It is possible for other apps to use '''Rules''', '''Triggers''', and '''Actions''' defined in Rule Machine<sup>®</sup>. 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, and Actions from an HTTP request to an endpoint.
+
<big>It is possible for other apps to use '''Rules''', '''Triggers''', 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, and Actions from an HTTP request to an endpoint.</big>
  
<h3>Using Rule Machine from within other apps</h3>
+
<h3><big>Using Rule Machine from within other apps</big></h3>
  
First, import the RM helper class into your app.
+
<big>First, import the RM helper class into your app.</big>
  
<code>'import hubitat.helper.RMUtils'</code>
+
<code><big>'import hubitat.helper.RMUtils'</big></code>
  
====The List of Rules====
+
====<big>The List of Rules</big>====
Rule Machine maintains a list of available Rules, Triggers, Triggered Rules, and Actions. That list can be obtained with this method call.
+
<big>Rule Machine maintains a list of available Rules, Triggers, Triggered Rules, and Actions. That list can be obtained with this method call.</big>
  
     def rules = RMUtils.getRuleList()
+
     <big>def rules = RMUtils.getRuleList()</big>
  
In this example, the resulting list of the variable '''rules''', can be used as an input to an "enum" as the options.
+
<big>In this example, the resulting list of the variable '''rules''', can be used as an input to an "enum" as the options.</big>
  
====Supported Actions====
+
====<big>Supported Actions</big>====
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, with each take the following form.
+
<big>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, with each take the following form.</big>
  
     def RMUtils.sendAction(rules, action, appLabel)
+
     <big>def RMUtils.sendAction(rules, action, appLabel)</big>
  
 
<pre> Set Private Boolean True:     
 
<pre> Set Private Boolean True:     
Line 98: Line 98:
 
     action    "resumeRule"
 
     action    "resumeRule"
 
</pre>
 
</pre>
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.
+
<big>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.</big>
  
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.
+
<big>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.</big>
  
'''Example''':
+
<big>'''Example''':</big>
  
 
     def rules = RMUtils.getRuleList()
 
     def rules = RMUtils.getRuleList()
Line 108: Line 108:
 
     RMUtils.sendAction(theseRules, "stopRuleAct", app.label)
 
     RMUtils.sendAction(theseRules, "stopRuleAct", app.label)
  
<h3>Using Rule Machine from HTTP requests</h3>
+
<h3><big>Using Rule Machine from HTTP requests</big></h3>
  
It is also possible to cause Rule Machine<sup>®</sup> to perform these same actions from an HTTP request. To accomplish this, you would create a '''Trigger''' with either a Local End Point or Cloud End Point. The endpoint URL given by Rule Machine has the following form.
+
<big>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''' with either a Local End Point or Cloud End Point. The endpoint URL given by Rule Machine has the following form.</big>
  
`http://192.168.0.36/apps/api/10249/trigger?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`
+
<big>`http://192.168.0.36/apps/api/10249/trigger?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`</big>
  
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.
+
<big>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.</big>
  
<code>`/action=rule1&rule2&rule3`</code>
+
<code><big>`/action=rule1&rule2&rule3`</big></code>
  
Where action is the action from the list above and <code>`rule1&rule2&rule3`</code> are the '''appIds''' of the rules to run, separated by ampersands.  
+
<big>Where action is the action from the list above and <code>`rule1&rule2&rule3`</code> are the '''appIds''' of the rules to run, separated by ampersands.</big>
  
This parameter is inserted in the endpoint URL just before the '''?''' that precedes the access_token as follows.
+
<big>This parameter is inserted in the endpoint URL just before the '''?''' that precedes the access_token as follows.</big>
  
`http://192.168.0.36/apps/api/10249/trigger/stopRuleAct=943&956&10217?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`
+
<big>`http://192.168.0.36/apps/api/10249/trigger/stopRuleAct=943&956&10217?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`</big>
  
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.
+
<big>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.</big>
  
The '''appIds''' are the values selected by the input described above. For example, <code>`theseRules`</code>. The appIds can also be found for a rule by opening the rule and observing its appId in its URL as follows.
+
<big>The '''appIds''' are the values selected by the input described above. For example, <code>`theseRules`</code>. The appIds can also be found for a rule by opening the rule and observing its appId in its URL as follows.</big>
  
`http://192.168.0.36/installedapp/configure/10249/mainPage`
+
<big>`http://192.168.0.36/installedapp/configure/10249/mainPage`</big>
  
The '''appId''' for that rule would be '''10249.'''
+
<big>The '''appId''' for that rule would be '''10249.'''</big>
  
====Get Rule List====
+
====<big>Get Rule List</big>====
To get the list of rules as returned from <code>`getRuleList()`</code> , use the following insert for the URL.
+
<big>To get the list of rules as returned from <code>`getRuleList()`</code> , use the following insert for the URL.</big>
  
<code>`/getRuleList`</code>
+
<code><big>`/getRuleList`</big></code>
  
Here's an example of how you would use a full URL.
+
<big>Here's an example of how you would use a full URL.</big>
  
`http://192.168.0.36/apps/api/10249/trigger/getRuleList?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`
+
<big>`http://192.168.0.36/apps/api/10249/trigger/getRuleList?access_token=ecd95469-bbcd-4889-a694-9b05ef80f4db`</big>
  
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.
+
<big>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.</big>
  
====Set Global Variable====
+
====<big>Set Global Variable</big>====
A Global Variable can be set by an endpoint trigger, using this format for the parameter.
+
<big>A Global Variable can be set by an endpoint trigger, using this format for the parameter.</big>
  
<code>`/setGlobalVariable=varName:varString`</code>
+
<code><big>`/setGlobalVariable=varName:varString`</big></code>
  
The <code>`varString`</code> portion is assumed to be URL encoded, and will be URL decoded before it is stored in the <code>`varName`</code> global variable.
+
<big>The <code>`varString`</code> portion is assumed to be URL encoded, and will be URL decoded before it is stored in the <code>`varName`</code> global variable.</big>
  
'''Note''': Rule Machine actions '''Stop Rule Actions''', '''Pause Rule''' and '''Resume Rule''' only work for Rule 2.5 or later. The Rule Machine action '''Set Global Variable''' only works for Rule 3.0 or later.
+
<big>'''Note''': Rule Machine actions '''Stop Rule Actions''', '''Pause Rule''' and '''Resume Rule''' only work for Rule 2.5 or later. The Rule Machine action '''Set Global Variable''' only works for Rule 3.0 or later.</big>
  
<h3>Dedication</h3>
+
<h3><big>Dedication</big></h3>
  
<p>Rule Machine<sup>®</sup> is dedicated to [[wikipedia:Alan_Turing|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.</p>
+
<p><big>Rule Machine is dedicated to [[wikipedia:Alan_Turing|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.</big></p>
 
__FORCETOC__
 
__FORCETOC__

Revision as of 06:51, 22 March 2021

Go to the top of the page

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 that a device or the hub sends out.

  • 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 make actions happen in the system.

Automations

An "automation" is a very small computer program which responds to events, and results in something happening.

  • Example: An automation could respond to the event of a door contact opening by turning on a porch light. These automations (e.g. Rules), make up the brains of the home automation system, delivering the "Smart" of a Smart Home.

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.

Event types

There are four basic event types:

  1. Device events
    • Devices events are generated by the smart devices in the system, like the door contact sensor reporting 'open'.
  2. Time events
    • Time events are generated by a scheduler in the hub for things like sunrise, 5:00 PM, etc.
  3. Hub events
    • Hub events are special events that the hub generates
      • Example: The hub generates an event when it starts up.
  4. Network events
    • 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.

  • 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.

Components of an Automation

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:

  1. The events that provoke it to act.
  2. The actions it performs as a result.

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.

  • An automation responds to Events
  • Evaluates Conditions
  • Performs Actions based on the Conditions.

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 Rule Machine has the described form.

  • Trigger Events
  • Actions - Actions may have Conditions to be evaluated as a step in determining what the automation does.

Rule Machine API

It is possible for other apps to use Rules, Triggers, 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, and Actions from an HTTP request to an endpoint.

Using Rule Machine from within 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. 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.

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, with each take the following 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 function, other 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 accomplish this, you would create a Trigger with either a Local End Point or Cloud End Point. The endpoint URL given by Rule Machine has the following form.

`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 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 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 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 as follows.

`http://192.168.0.36/installedapp/configure/10249/mainPage`

The appId for that rule would be 10249.

Get Rule List

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 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, using this format for the parameter.

`/setGlobalVariable=varName:varString`

The `varString` portion is assumed to be URL encoded, and will be URL decoded before it is stored in the `varName` global variable.

Note: Rule Machine actions Stop Rule Actions, Pause Rule and Resume Rule only work for Rule 2.5 or later. The 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.