Easy Trigger plug-in - User Guide

[spud]

INSTALLATION / CONFIGURATION

System Requirements:
- HS3 or HS3PRO, both Windows and Linux version are supported

Plugin Installation:
Download and install from the updater (Utilities section) or download package from the Beta Testing thread and follow instructions to install.

Plugin Configuration
Start the plugin from the "PLUG-INS > Manage" page wait a few seconds for the plugin to initialize, then from an event you should see new available triggers and conditions and new actions all prefixed with EasyTrigger like in the screenshots below:

[spud]

Triggers/Conditions based on device's string (EasyTrigger: A Device's string is...)

A lot of devices don't have predefined values and only use status strings (for example the title device of a media player plugin), but there is no native HS trigger/condition that let you fire events based on those status strings.
The EasyTrigger plugin let you do so, it adds the following triggers:

• This device's string changes and becomes...
• This device's string changes and contains...
• This device has a string that just changed:
• This device's string changes and is not...
• This device's string changes and does not contain...
• This device's string changes and matches this regular expression...

and the following conditions:

• This device's string is...
• This device's string contains...
• This device's string is not...
• This device's string does not contain...
• This device's string matches this regular expression...

For example let's say you want to set a specific lighting ambiance when you watch a specific TV show, to do so you could create an event similar to the one below:




Triggers/Conditions based on device's value (EasyTrigger: A Device's value is...)

the new triggers are:

• This device's value was and becomes...
• Comparison between 2 device values becomes true.
• This device's value has been in range [X,Y] for exactly...
• This device's value has NOT been in range [X,Y] for exactly...
• This device's value has NOT changed for exactly...
• This device had its value set and expression is true...

and the new condition are:

• Comparison between 2 device values is true.
• This device's value has been in range [X,Y] for at least...
• This device's value has NOT been in range [X,Y] for at least...
• This device's value has NOT changed for at least...
• This device's value has changed within the last...

The comparison trigger/condition let you compare two devices value. You can optionally add a positive or negative offset to the the second device value.
In the trigger case it will only fire the event if and only if

(a) the condition was previously false
(b) one of the two devices being compared has its value changed
(c) the condition is now true



"This device had its value set and expression is true.." trigger is a very powerful one because you can use any mathematical expression to compare the old and new value of the device. Here is an example that checks if the humidity has increased of at least 2%

[spud]

Conditions based on plugins (EasyTrigger: A Plugin is...)

Using these conditions you can check the current state of a plugin by entering the plugin name and the plugin instance name. The possible conditions are:

• This plugin IS running:
• This plugin IS NOT running:

For example the event below use a "plugin is running" condition and a schedule trigger to stop a Kinect remote instance




Note: Even if it appears in the list of triggers, this one can't be used as a trigger (IF, OR IF) it can only be used as a condition (AND IF)

[spud]

Random triggers and conditions (EasyTrigger: Random)

You can use the "Recurring Random Trigger happens" to randomly trigger an event at least once every X but no more than once every Y. Where X and Y are configurable time period.

"This condition is randomly true" lets you create a condition that is randomly true X% of the time, where X is configurable




Here is an example to randomize the time a light turns on and how long it stays on. Below are a pair of events that will

• Turn a light on at night at some random time from 0-5 hours, but not more often than once every two hours. The light has to have been off for at least an hour before it can come on again.
• Then it will turn off somewhere between 30-90 minutes after it is turned on.
• It will continue this process until sunrise.

Triggers/Conditions based on a group of devices (EasyTrigger: Any Device's Value in Group is)

These triggers/conditions are useful to avoid long list of "OR IF" and "AND IF" instead of checking the value of several device one by one, you can check values for a group of devices. The groups can be created from the Config page as in the screenshot below or they can be based on devices Name, Location1, Location2 or Type.



the possible triggers are:

• Any device's value in this group changes and becomes...
• Any device's value in this group had its value set and is not equal to...
• Any device's value in this group had its value set and is greater than...
• Any device's value in this group had its value set and is less than...
• Any device's value in this group has just changed...
• Any device's value in this group had its value set and expression is true...

and the possible conditions are:

• Any/All device's value in this group is/are...
• Any/All device's value in this group is/are not equal to...
• Any/All device's value in this group is/are greater than...
• Any/All device's value in this group is/are less than...

Here is an example that set the value of a virtual device to vacant/occupied based on the state of several motion sensors:




When a trigger based on a group is fired 4 global variables ETDeviceRef, ETDeviceName, ETDEviceLocation1, ETDeviceLocation2, ETDeviceValue and ETDeviceStatus are set, which respectively track the ref#, the name, the location 1, the location 2, the value and the status of the triggering device.
This allows to use information about the triggering device in the event action, like in the screenshot below:

[spud]

Action to control a device using a replacement variable (EasyTrigger: Set Device to Variable)

You can use this action to set a device value to any replacement variable: this can be a global variable, another device value, a counter, basically anything that is in this list and has a numerical value

Optionnally you can add or substract an offset value.

set device value to a global variable:


set device value to another device value minus 1



Action to control a device using another device value (EasyTrigger: Set Device to another Device)

This action is another way to set a device value to another device value. It is more user friendly than the replacement variable method above, because you can select the device by name instead of using the reference number.




Action to set a device's string (EasyTrigger: Set Device's string)

This action allows to change a device's string. The string can contains one or more replacement variable
Here is an example that set a virtual device's string to the value of an existing timer:

and here is how the device would look like after the above action is run



Action to control a device using an expression (EasyTrigger: Set Device to Expression)

This action allows you to use a mix of replacement variables and mathematical operations to set a device value. For example in the screenshot below the "Ecobee Target Temperature Low" device is increased by 2%. $$DVR:3968: is the replacement variable for the device.
Note the use of the Round function; as most of control values for devices are integer, you will often have to round the result of your expression to the nearest integer.


The supported functions and operators are listed here

another interesting function is "if(condition, value if condition is true, value if condition is false)" that allows us to use conditional expression like

if($$DVR:123: > $$DVR:234:, 60, 70)

which means if device #123 has a value greater than device #234 then returns 60 else 70

To test/troubleshoot your expression you can set the log level to debug, and you will see something like the following in the logs everytime the expression is evaluated:

 Expression Round($$DVR:3968: * 102/100, 0) evaluated to 65

[spud]

Action to toggle a device between several values (EasyTrigger: Toggle Device)

This action lets you toggle a device between several values:


you can use more than 2 values (up to ten):


and you can even choose specific value within a range:


Ideally the values you select need to be both control and status, if they are control only, the plugin won't be able to match the current status of the device with one of the toggle value, so in this case it will use the last toggle choice that has been fired and increment from that value. If instead you want the plugin to use the toggle which is the closest to the current device value, then switch to "Advanced Editing Mode" (blue bird button) then check the checbox like in the screenshot below:



Action to copy a schedule to another schedule (EasyTrigger: Set Schedule to another Schedule)

This action can be very handy if you want to have an event based on a schedule, but the schedule can change depending on the time of year.
Let's say for example you want some lights to turn on/off according to a schedule, but you want this schedule to be different in the holiday:

To do that, define 3 schedules as in the screenshot below: one that define when lights should go on during the holiday period, one that define when the lights should go on during the regular period, and one master schedule that can be blank.


Then define 2 events to copy the holiday schedule to the master schedule every Dec 1st, and to copy the regular schedule to the master schedule every Jan 7th.


Then you just need to use the master schedule in your lights logic as shown at the beginning of this thread.
i.e. IF time enters Lights_Master time range THEN turn lights on

[spud]

Action to control a group of devices (EasyTrigger: Set Group of devices to Expression)

This action is designed to set a group of devices defined from the Config page to a specific value. You can use a mix of simple values, variables and mathematical formulas. For example the action in the screenshot below will set all the devices in group1 to the value of the device which has a reference id equals to 123, plus 5.


The supported functions and operators are listed here, and replacement variables syntax is explained here

Action to disable/enable an event (EasyTrigger: Disable Event / Enable Event)

This action will let you disable or enable an event exactly like if you were clicking the green checkmark button from the web interface.

[spud]

Actions to back up/restore a device state:

• EasyTrigger: Push Device's value to stack
• EasyTrigger: Pop Device's value from stack and Set Device
• EasyTrigger: Clear Stack

Each device can have an associated LIFO (Last In First Out) stack that can contains a maximum of 50 values.
These actions can be use to back up a device value before an automatic change happens and then restore the original value.

So, if you push the device value to the stack and then set it to another value like that:

You can set back the device to its previous value like that:



Note that this will only work for device values that are both status and control, because when the plugin push a value to the stack it retrieves the current device's status value, if it is not a control value as well, the pop action will return an error as it will not be able to set the device.

[spud]

Scripting

You can use the following function from scripts:

void   SetSchedule(string scheduleName, string timeSlots)
string GetSchedule(string scheduleName)
string GetScheduleNextTimeRangeStart(string scheduleName)
string GetScheduleNextTimeRangeEnd(string scheduleName)
bool   IsTimeInScheduleTimeRange(string scheduleName)
bool   IsPluginRunning(string pluginName, string pluginInstance = "")
bool   AnyDevicesValueInThisGroupIsEqualTo(string groupName, double value)
bool   AnyDevicesValueInThisGroupIsNotEqualTo(string groupName, double value)
bool   AnyDevicesValueInThisGroupIsGreaterThan(string groupName, double value)
bool   AnyDevicesValueInThisGroupIsLessThan(string groupName, double value)
bool   AllDevicesValueInThisGroupAreEqualTo(string groupName, double value)
bool   AllDevicesValueInThisGroupAreNotEqualTo(string groupName, double value)
bool   AllDevicesValueInThisGroupAreGreaterThan(string groupName, double value)
bool   AllDevicesValueInThisGroupAreLessThan(string groupName, double value)

For example here is a small C# script that uses the IsTimeInScheduleTimeRange function

public object Main(object[] Parms)
{
    bool isInSchedule = (bool) hs.PluginFunction("EasyTrigger", "", "IsTimeInScheduleTimeRange", new object[] { "Test" });

    hs.WriteLog("EasyTrigger Script", "IsInSchedule = " + isInSchedule.ToString());
    return 0;
}

[spud]

Triggers/Conditions based on schedules (EasyTrigger: The Time is...)

Go to the Config page (PLUG-INS > EasyTrigger > Config), then click the green '+ button to create a new schedule, then enter a name for this schecule (containing only alphanumeric characters or underscore). Then by clicking the Edit button you will have access to a user friendly widget that let you create time ranges by clicking and dragging. You can also move or resize an already existing time range or you can delete one by clicking on it.



When you are done, click the OK button at the bottom of the schedule widget. This will create a string representing your time ranges looking like this:

[Mon 05:00;Mon 06:30],[Mon 19:00;Mon 23:00],[Tue 05:00;Tue 06:30],...

When you move or resize a time range using the schedule widget it only let you do so using 5 minutes steps. If you need finer steps, you can manually modify the string and submit.

NOTE: Schedules cannot cross midnight on Sunday night. If you want to use a schedule that includes

[Sun 22:00;Mon 05:00]

you must break it into two parts

[Sun 22:00;Mon 00:00],[Mon 00:00;Mon 05:00]

Repeat the process to create as many schedule as you want. And of course you can use the same schedule in as many events as you want.

Once you have some schedules configured you can use them as triggers and conditions. Go to the events page and create or edit an event, and choose the trigger/condition called "EasyTrigger: The Time is..."

the possible subtriggers are:

• The time enters this schedule time range:
• The time leaves this schedule time range:

the possible subconditions are:

• The time is in this schedule time range:
• The time is NOT in this schedule time range:
• The time is before (sunrise +/- T)
• The time is after (sunrise +/- T)
• The time is before (sunset +/- T)
• The time is after (sunset +/- T)

For example to have a light turn on and off based on a specific schedule you would setup 2 events like in the screenshot below



If you want the light to be turned on based on a motion detector and when the time is in a specific schedule, you can use the motion detector as the trigger and the schedule as a condition:



Schedule time ranges relative to sunrise/sunset

To define a time range relative to sunrise/sunset you have to manually enter the relative time in the text field. For example:

Mon Sunrise+00:20

the offset is optional and can be positive or negative



then you can edit the schedule, drag and drop a time range or resize it, and the offset will be recomputed accordingly.

for example the schedule below could be used to turn on some lights from 3am to sunrise+20minutes, and from sunset-20minutes to 11:45pm