Difference between revisions of "Rule-5.1"

From Hubitat Documentation
Jump to: navigation, search
(Replaced content with " <big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big> <big> This document is available at: http://docs2.hubitat.com/en/apps/...")
(Tag: Replaced)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
Rule Machine is the most powerful built-in tool for creating custom automations in Hubitat Elevation.
 
  
=Creating a new Rule=
+
<big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big>
  
#Navigate to the hub interface, then click '''Apps''' in the sidebar.
+
<big>
#Find '''Rule Machine''' in the list, and click/tap it to open. (Install Rule Machine with '''Add Built-In App''' first if you have not already.)
+
This document is available at: http://docs2.hubitat.com/en/apps/rule-machine/rule-5-1
#Choose '''Create New Rule''', then follow the prompts to provide a name for your rule. This is how it will appear in the '''Apps''' list and in logs.
+
</big>
#Specify triggers, actions, and other components you need to make your rule work as intended, as described below.
 
 
 
=Anatomy of a rule=
 
Rules consist of up to three parts:
 
 
 
*'''Trigger events:''' When any of the trigger events happen, the "Actions to Run" will begin executing.
 
*'''Required expression:''' ''(optional)'' If used, the rule will not trigger unless the expression evaluates to true at the moment of the trigger event.
 
*'''Actions to run:''' A list of actions to run when the rule is triggered — for example, turning on lights, changing a mode, or running just about any command on any device.
 
 
 
==Trigger events==
 
Each rule can have one or more trigger events specified. Events are generated by devices in your system or by your hub itself. Examples of trigger events include "Motion sensor ''X'' is active" or "Time is 8:00 PM". Rules will listen for trigger events and run the "Actions to Run" when any trigger event happens (except in some cases when a required expression is used, as described below).
 
 
 
To specify a trigger event, open the '''Select Trigger Events''' page by clicking or tapping on the '''Select Trigger Events''' box. Then, choose the "capability" that matches the kind of trigger event you want to add. For example, to trigger on "motion active," choose the "Motion" capability. To trigger on a switch (including a bulb or dimmer) turning on or off, choose "Switch." See the List of Trigger Event Capabilities section below for a complete list of capabilities and the attributes or events they correspond to.
 
 
 
==Required expression==
 
Enabling the '''Use required expression''' option allows you to define an expression (a single condition or any combination of conditions) that must evaluate to true in order for the rule to trigger. If the required expression evaluates to false at the moment when the rule is triggered, the rule will not actually trigger, and the specified actions will not run.
 
 
 
One possible use for required expressions is to trigger only on specific state changes. For example, if you want a rule to trigger only on a specific mode change — say, Away mode to Home mode — then a required expression is an easy way to make that happen:
 
 
 
'''Trigger events:''' Mode becomes Home
 
 
 
'''Required expression:''' Mode is Away
 
 
 
Without the required expression, this rule would trigger any time mode becomes Home, regardless of the previous mode.
 
 
 
Another possible use for a required expression is to restrict the execution of actions under certain conditions (though this can generally also be done with conditional actions in "Actions to Run"; see below for more).
 
 
 
'''NOTE:''' Almost any condition can be used to create a required expression. However, it is recommended to avoid ''local'' variables in conditions used to create required epxression (they do not generate events and thus the required expression will not be re-evaluated when it changes). ''Hub'' variables and Private Boolean will work without caveats.
 
 
 
==Actions to run==
 
This is where you define what happens when the rule is is run. To add an action, first choose the appropriate category for the action under '''Select Action Type to add'''. Then, choose the specific action under '''Select Which Action'''. See the List of Actions section below for a complete list of where to find any particular action in this menu structure. Most actions run a command on a device. For example, '''Set Dimmers and Bulbs > Set dimmer''' can be used to set the level (brightness) on a dimmer or bulb. Under the hood, this calls the "Set Level" command on the device, but you do not need to know this; Rule Machine handles running commands on devices as needed based on your selections here.
 
 
 
Actions to run are essentially an ordered script. You can add as many actions as you need in whatever order you want. Note that some "special" action lines like <code>IF (expression) THEN</code> and <code>Repeat</code> have specific formats that must be followed; see below for more details on these.
 
 
 
===Modifying Actions===
 
Actions can be modified with the '''Edit Action''' or '''Delete Actions''' drop-downs. ('''Edit Actions''' can be used for minor changes, like replacing one device with another or changing a specified value. To completely replace one type of action with another, you will need to delete the action and insert a new one at the desired location.) '''Insert Action Before''' will allow you to choose a specific location to insert a new action; by default, new actions will be added to the end of the list.
 
 
 
The '''Cut Action''', '''Copy Action''', and '''Paste Action Before''' drop-downs can be used to cut, copy, and insert actions in typical "clipboard" fashion. Cut or copied actions can be shared to another rule by selecting the '''Export clipboard?''' option in one rule and then using the '''Import Clipboard From''' drop-down in another rule.
 
 
 
=Rule options=
 
 
 
*Each rule has options for '''Logging''':
 
**'''Events''': logs any time a trigger event happens. The log entry will contain the name of the rule and a description of the event (e.g., "My Rule event: Side Door Lock unlocked)
 
**'''Triggers''': logs any time the rule was triggered (e.g., "My Rule Triggered")
 
**'''Actions''': writes a log immediately before each action in the rule is run (or also if it was skipped — for example, because it is inside a conditional action that evaluated to false)
 
 
 
All log entries will appear in "Logs," accessible from the sidebar. These options can be useful for troubleshooting.
 
 
 
*'''Display current values:''' if enabled, the current value for any selected device attributes, variables, etc. will be displayed next to the device the list of trigger events and actions to run. These values will also be displayed with the actions in "Logs" if action logging is enabled.
 
*'''Run Actions'''  button: will run the Actions to Run section (effectively a way to manually trigger a rule)
 
*'''Update Rule''' button: re-initializes rule like '''Done''' but without leaving the rule editor page
 
*'''Remove''' button: removes this rule. Note that the '''Remove''' button inside a rule removes only that rule; the '''Remove Rule Machine''' button inside the "parent" Rule Machine app will remove Rule Machine and all rules.
 
*'''Done''' button: re-initializes rule (updates trigger event subscriptions; cancels any timers/scheduled jobs), then returns to the Apps list page. (Note that changes inside the "Select Actions to Run" page are saved as they are made and do not require use of this button.)
 
 
 
=Special Actions=
 
Most Rule Machine actions run commands on devices. For example, '''Control Switches, Push Buttons > Turn switches on/off''' will send an "On" or "Off" command to the selected device(s), depending on the options chosen. '''Toggle switches''' will turn the switch (or dimmer, bulb, etc.) off it it is on or on of it is off. However, Rule Machine also contains various types of special actions, like delays and repeats.
 
 
 
==Delay==
 
Rule Machine has two types of delays. A delay can be added as a special type of action under '''Delay, Wait, Exit or Comment > Delay Actions''' (or '''Delay Actions Per Mode''' to specify a different delay for each mode). This causes the actions to effectively pause at the delay, wait for the specified amount of time, then resume with the next action when the time is up.
 
 
 
Alternatively, with most actions, a delay option can be specified ''on'' the action itself. To do this, select an option from the '''Delay?''' drop-down when creating or editing the action. Choose '''hrs:min:sec''' to specify a specific amount of time, or choose '''variable''' to use a local or hub variable (must be of type number or decimal).
 
 
 
For any delay, the '''Cancelable?''' option may be selected. By default, a rule being re-triggered (or the rule actions running again for any reason) does not cancel previously scheduled delays. Choosing the '''Cancelable''' option allows the delay to be cancelled with the '''Cancel Delayed Actions''' action elsewhere in the same rule.
 
 
 
Care must be taken when using delays embedded inside conditionals. If the rule re-triggers while the delay is pending, you may get a "Multiple simultaneous rule execution error" in [[Logs]] (and the rule actions will not run as intended). Solutions include restricting execution of the rule while the delay is pending (e.g., with a required expression), cancelling the delay earlier in the rule, or using a "Wait for events: elapsed time" action instead if you want the timer to be cancelled on re-trigger of the rule.
 
 
 
==Wait==
 
Rule Machine offers two types of waits under  '''Delay, Wait, Exit or Comment''': the '''Wait for Events''' action and the '''Wait for Expression''' action.
 
 
 
===Wait for Events===
 
'''Wait for Events''' allows you to specify one or more events. The rule will effectively pause at this point and wait for one of the specified event(s) to fire. When any of the specified events happen, the rule will proceed with the next action.
 
 
 
To add more than one event to wait for, press '''Add another Wait Event''' after adding the first (or any subsequent) event. When you are finished with everything, press '''Done with Wait Events''' to return to the previous page to add or edit other actions.
 
 
 
The '''Timeout?''' option allows you to specify an amount of time after which the rule will proceed with the next action in case none of the specified event(s) happen.
 
 
 
===Wait for Expression===
 
'''Wait for Expression''' allows you to specify a condition or combination of conditions (i.e., an expression). If the expression is true when this wait is reached, the rule will immediately proceed with the next action (unless a duration is required; see below). If it is false, the rule will effectively pause at this point and wait for the expression to become true.
 
 
 
The '''Timeout?''' option allows you to specify an amount of time after which the rule will proceed with the next action in case the specified expression does not become true before that amount of time passes. The '''Use Duration?''' option allows you to specify a '''Duration''', an amount of time for which the expression must remain true in order for rule to proceed to the next action. If a duration is specified and the action becomes (or is) true for some amount of time less than the duration and then becomes false again, the wait will start over.
 
 
 
===Cancellation of Waits===
 
Any type of "Wait" action is cancelled upon re-triggering of a rule. (The '''Cancel Rule Timers''' action will also cancel waits but is rarely necessary, and it affects all rule timers ,as described elsewhere.) Note that this behavior differs from delays, which must be explicitly cancelled.
 
 
 
==Exit Rule==
 
'''Exit Rule''' stops the execution of rule actions past the '''Exit Rule''' action itself. Note that it does ''not'' cancel any repeats, delays, waits, or other scheduled actions.
 
 
 
This action is generally most useful if used as part of a conditional action. For example:
 
<code>IF (Mode is Night) THEN
 
  Exit Rule
 
END-IF
 
(remaining actions to run only in modes besides Night...)</code>
 
 
 
==Comment==
 
This action has no effect; it simply allows you to write a "comment" at that location in your rule actions that will display in the editor (this could be helpful if you want to document for yourself why you are using certain actions at that point in the rule).
 
 
 
==Repeat==
 
Rule Machine offers two types of repeat: '''Repeat Actions''' and '''Repeat While Expression'''.
 
 
 
===Repeat Actions===
 
A block of repeats starts with a <code>Repeat</code> action (under '''Repeat Actions > Repeat Actions''' in the action selectors) and ends with an <code>END-REP</code> action (under '''Repeat Actions > END-REP''' in the action selectors, or the '''END-REP''' button that will appear when editing inside a repeat).
 
 
 
A repeat ''must'' be specified with a repeat interval (under '''Repeat every...'''). This is the duration the rule will wait after starting one repetition of the actions between the <code>Repeat</code> and <code>END-REP</code> before starting the next repetition.
 
 
 
A repeat ''may'' use the '''Repeat ''n'' times''' (or '''Repeat variable ''n'' times''') option. However, without the use of this option, you will likely want to ensure you have some way to stop the repeat; see below.
 
 
 
A repeat may also use the '''Stoppable''' action. This enables the '''Stop repeating actions''' action to stop this repeat (without this option selected, the repeat will not be affected by use of this action).
 
 
 
Here is an example rule actions that, if triggered on "Contact sensor is opened," will send a notification immediately and every 5 minutes afterwards until the contact sensor is closed:
 
<code>Repeat every 0:05:00 (stoppable)
 
    IF (Contact Sensor is closed) THEN
 
      Stop Repeating Actions
 
    ELSE
 
      Send "Contact sensor is open!" TO notification device
 
    END-IF
 
END-REP</code>
 
For more examples examples of repeats, see this post: <nowiki>https://community.hubitat.com/t/how-to-get-repeated-notifications-using-rule-machine/19652</nowiki>
 
 
 
===Repeat While Expression===
 
The '''Repeat Actions > Repeat While Expression''' action works similarly to the above in terms of repeat interval. However, it provides an easier way to exit the repeat if you only want to repeat under certain conditions. For example, the above could be re-written as:
 
<code>While (Contact sensor is open) Repeat every 0:05:00
 
    Send "Contact sensor is open!" TO notification device
 
END-REP</code>
 
The '''Repeat ''n'' times''' (or '''Repeat variable ''n'' times''') option may also be applied to this type of repeat. The repeat will end when either the specified expression becomes false or the number of times has been reached, whichever comes first.
 
 
 
=Special Features=
 
 
 
*Local variables: each rule supports the creation of local variables. As their name suggests, they are available for use only in the same rule (not other rules or apps).
 
**Note: Hub variables are also available for use in Rule Machine (and many other apps); they are similar in possible uses except that they can be shared among multiple rules/apps rather than just within the rule in which they are created.
 
*Private Boolean: a Boolean (true/false) variable built in to each rule, which can be modified by either the rule itself or (unlike a "full" local variable) other rules. It is simply a place to store a value and does not do anything on its own, though you can use it as part of expressions to create the desired effect.
 
 
 
=Frequently asked questions=
 
 
 
==Why didn't my rule run?==
 
Try enabling logging as described in the Rule Options section. Then, use "Logs" in the sidebar to see what, if anything, your rule did and when. (Note that you'll need to use the "Past Logs" option on this page unless you had "Current Logs" open at the time the log entry was generated.) Sometimes, you will find that your rule, in fact, did excecute as expected, but a device may not have responded as intended. This will help you begin troubleshooting. The "Display current values" may also be helpful to have enabled if you have conditional actions or may otherwise care about the value of conditions/expressions, variables, and other states during execution.
 
 
 
Additionally, ensure your rule was created correctly. For example, without trigger events, rule actions will never execute unless run from another rule or app (or run manually from the rule page itself).
 
 
 
==Why can't I use "AND" in the list of trigger events?==
 
Triggers represent events, which are an instant in time — for example, motion becoming active, a switch turning on, or the time becoming 8:30 PM. If you want to check a ''state'' rather than respond to a specific ''event'', you can do so in the actions (using a conditional actions), or you can use a required expression to restrict triggering when a certain condition or combination of conditions is not true.
 
 
 
==Need more help?==
 
The Hubitat Community is a great place to ask questions and share ideas with fellow users.
 
 
 
=Capabilities and Actions=
 
Below is a complete list of trigger event capabilities (on the "Select Trigger Events" page) and available actions (on the "Actions to Run") page, which can be useful to consult if you are not sure where to find something or what capability to choose for a specific event.
 
 
 
==List of Trigger Event Capabilities==
 
The following is a list of capabilities found on the "Select Trigger Events" page and the attribute or event that the trigger can listen for. Most of these capabilities can also be used to create conditions and expressions in rules as well.
 
{| class="wikitable"
 
!Capability
 
!Description (attribute, event, etc.)
 
|-
 
|Acceleration:
 
|active / inactive
 
|-
 
|Between two dates:
 
|starting month on this date / ending month on this date
 
|-
 
|Battery:
 
|value
 
|-
 
|Button:
 
|pressed / held / doubleTapped / released
 
|-
 
|Certain Time:
 
|at a certain time, including sunrise / sunset with offset
 
|-
 
|Cloud End Point:
 
|trigger with HTTP GET on generated cloud URL
 
|-
 
|Contact:
 
|open / closed
 
|-
 
|Custom attribute:
 
|device capability
 
|-
 
|Days of Week:
 
|on certain days of the week
 
|-
 
|Dimmer level:
 
|value
 
|-
 
|Door:
 
|open, closed, opening, closing, unknown
 
|-
 
|Energy meter:
 
|value
 
|-
 
|Garage door:
 
|open, closed, opening, closing, unknown
 
|-
 
|HSM alert:
 
|intrusion, intrusion-delay, intrusion-home, intrusion-home-delay,  intrusion-night, cancelRuleAlerts, intrusion-night-delay,
 
|-
 
|
 
|smoke, water, rule, arming, armingHome, armingNight, cancel
 
|-
 
|HSM status:
 
|armed away, armed home, armed night, delayed arming home, delayed arming  night, delayed arming away, disarmed, all disarmed
 
|-
 
|Humidity:
 
|value
 
|-
 
|Illuminance:
 
|value
 
|-
 
|Last Event Device
 
|select device and attribute
 
|-
 
|Local End Point:
 
|trigger with HTTP GET on generated local URL
 
|-
 
|Lock:
 
|locked / unlocked
 
|-
 
|Mode:
 
|any of your hub's modes
 
|-
 
|Motion:
 
|active / inactive
 
|-
 
|Music player:
 
|playing, paused, stopped
 
|-
 
|Periodic:
 
|allows periodic schedules for minutes, hourly, daily, weekly, monthly or  yearly
 
|-
 
|Physical dimmer level:
 
|value
 
|-
 
|Physical switch:
 
|on / off
 
|-
 
|Power meter:
 
|value
 
|-
 
|Power source:
 
|mains / battery
 
|-
 
|Presence:
 
|present / not present or arrives / leaves
 
|-
 
|Private Boolean:
 
|true / false
 
|-
 
|Rule paused:
 
|rule
 
|-
 
|Smoke detector:
 
|clear, detected, tested
 
|-
 
|Switch:
 
|on / off
 
|-
 
|Temperature:
 
|value
 
|-
 
|Thermostat cool setpoint:
 
|value
 
|-
 
|Thermostat fan mode:
 
|value
 
|-
 
|Thermostat heat setpoint:
 
|value
 
|-
 
|Thermostat mode:
 
|heat / cool / auto / off / emergency heat
 
|-
 
|Thermostat state:
 
|heating / cooling / fan only / idle / pending heat / pending cool
 
|-
 
|Time of day:
 
|specific time / sunrise / sunset
 
|-
 
|Variable:
 
|value
 
|-
 
|Water sensor:
 
|dry / wet
 
|}
 
 
 
==List of Actions==
 
The following is a list of the actions available on the "Select Actions to Run" page. This can be helpful to consult if you are unsure where to find a specific action in the menus.
 
{| class="wikitable"
 
!Select Action Type to Add
 
!Select Which Action
 
|-
 
|Conditional Actions
 
|IF (expression) THEN
 
ELSE-IF (expression) THEN<br />
 
ELSE<br />
 
END-IF<br />
 
Simple Conditional Action
 
|-
 
|Control Switches, Push Buttons
 
|Turn switches on/off
 
Toggle switches<br />
 
Flash switches<br />
 
Set switches per mode<br />
 
Push button<br />
 
Push button per mode
 
|-
 
|Set Dimmers and Bulbs
 
|Set dimmer
 
Toggle dimmer<br />
 
Adjust dimmer<br />
 
Set dimmer per mode<br />
 
Fade dimmer over time<br />
 
Stop dimmer fade<br />
 
Start raising/lowering dimmer<br />
 
Stop changing dimmer<br />
 
Set color<br />
 
Toggle color<br />
 
Set color per mode<br />
 
Set color temperature<br />
 
Toggle color temperature<br />
 
Set color temperature per mode<br />
 
Change color temperature over time<br />
 
Stop changing color temperature
 
|-
 
|Activate Scenes, Adjust Shades or Fans
 
|Activate scenes
 
Activate scenes per mode<br />
 
Open/Close shades/blinds<br />
 
Set shade/blind position<br />
 
Set fan speed<br />
 
Cycle fans
 
|-
 
|Control HSM, Garage Doors, Locks, or Valves
 
|Arm/Disarm Hubitat® Safety Monitor
 
Open/Close garage door<br />
 
Lock/Unlock locks<br />
 
Open/Close valves
 
|-
 
|Control Thermostats or Thermostat Scheduler
 
|Set thermostats
 
Set Thermostat Scheduler
 
|-
 
|Send, Speak, or Log a Message, Send HTTP Request
 
|Send/Speak a Message
 
Log a Message<br />
 
Send HTTP Get<br />
 
Send HTTP Post<br />
 
Ping IP address<br />
 
|-
 
|Control Music Player, Volume, Sounds
 
|Control Music Player
 
Set Volume<br />
 
Mute/Unmute<br />
 
Sound Tone<br />
 
Sound Chime<br />
 
Control Siren
 
|-
 
|Set Variable, Mode or File, Run Custom Action
 
|Set Variable
 
Set Mode<br />
 
Run Custom Action<br />
 
Write to local file<br />
 
Append to local file<br />
 
Delete local file
 
|-
 
|Set Private Boolean, Run/Cancel/Pause Rules
 
|Set Private Booleans
 
Run Rule Actions<br />
 
Cancel Rule Timers<br />
 
Pause/Resume Rules
 
|-
 
|Capture/Restore, Device Refresh or Polling
 
|Capture Devices
 
Restore Devices<br />
 
Refresh devices<br />
 
Poll devices<br />
 
Disable/Enable devices<br />
 
Start/Stop Z-Wave Polling
 
|-
 
|Repeat actions
 
|Repeat Actions
 
Repeat While Expression<br />
 
END-REP<br />
 
Repeat Until Expression<br />
 
Stop Repeating Actions
 
|-
 
|Delay, Wait, Exit or Comment
 
|Delay Actions
 
Delay Actions Per Mode<br />
 
Cancel Delayed Actions<br />
 
Wait for Events<br />
 
Wait for Expression<br />
 
Exit Rule<br />
 
Comment
 
|}
 

Latest revision as of 20:02, 25 September 2022

We're moving! Please visit http://docs2.hubitat.com for the latest documentation.

This document is available at: http://docs2.hubitat.com/en/apps/rule-machine/rule-5-1