Plugin Docs: Conditions

Posted on
Thu Jul 07, 2016 5:51 pm
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Plugin Docs: Conditions

Forward

So many of my plugins use some kind of conditioning but the look, feel and functionality of conditioning varies from plugin to plugin. To resolve this I have written a "common" conditions library that will be used in all my plugins. If the plugin documentation brings you to this page then that plugin utilizes this new library.

The conditions library is intended to be as robust as possible and very flexible. Each plugin that utilizes this library will have the same look, feel and functionality when it comes to conditions in the plugin and plugin devices, so this one "mini wiki" serves as documentation for multiple plugins regarding using conditions.

Different plugins will employ a different number of allowable conditions and not all types of conditions will be available on all plugins - it depends on the needs of the plugin (if the plugin doesn't need to have a date-based condition then date-based conditioning will not be enabled in the plugin).

Condition Types

Device State
Conditions based on the value or value range of a device state of any Indigo device.

Variable Value
Conditions based on the value or value range of a variable value of any variable defined in Indigo

Current Date and/or Time
Conditions based on the current year, month, day, day of the week or time.

Device State Date and/or Time
Conditions based on the current year, month, day, day of the week or time of any Indigo device representing a date and/or time state of any kind.

Variable Value Date and/or Time
Conditions based on the current year, month, day, day of the week or time of any Indigo variable representing a date and/or time of any kind.

Basics

Each set of conditions can action on one of four groupings: All conditions are true, Any condition is true, All conditions are false and Any condition is false. Using these groupings allows you to easily define what passes and what does not.

Each individual condition allows you to determine if a condition is true or false based on if it is equal to something, not equal to something, greater than something, less than something, between two ranges of values, not between two ranges of values, contains a value or does not contain a value.

Each condition can be fined tuned by date as well, allowing you to define a date and/or time to compare to as well as being able to use calculations such as the last day of the month, first occurrence of a day, second occurrence of a day, third occurrence of a day, fourth occurrence of a day or last occurrence of a day. This makes it easy to allow for complex date requirements like only return true if the date in question is the 3rd Sunday in June.

Device Configuration Window

Due to the sheer number of fields required to do a single condition (let alone five or more), the window is optimized for space. While you can select which condition to modify, only one condition - the currently active condition - will be fully visible in the device configuration window. Even if no conditions are used or if multiple conditions are disabled the window size will remain the same so that when you create or modify conditions you will not have to scroll in the window to see all of the options.

Special Conditions

For the most part the conditions are quite obvious in their use, but there are two (four with variations) that bear a bit more explanation.

Between / Not Between
When you use this method you are supplying a starting value and an ending value and seeing if the value that you are comparing falls between (or equals) the two. So if you had a starting value of 'A' and ending value of 'Z' it would catch every possible word until the letter Z.

All evaluations for Between / Not Between are not case sensitive, so TRUE = true = True = tRuE.

Containing / Not Containing

Think of this option as the opposite of Between / Not Between. Instead of checking if a value falls within a range of two other values, you are seeing if a value is inside a value. For instance, if you wanted to know if the weather is cloudy but don't care if it's party cloudy or mostly cloudy you can look for 'cloudy' inside a weather condition and the result will be true if that word exists in the compared-to value in any form. This value can be any letter or character that you want to look for and is not case sensitive.

Values

While this is not a condition, it bears noting that you can enter any value into Value that you are looking for. If you are comparing to a boolean (true/false) value you simply put 'true' or 'false'. You should keep in mind that Indigo treats several different device states as a boolean expression but what you see is different - for instance On/Off is simply another way of saying True/False. If you want to know if a device is on or off you can evaluate the 'onOffState' state of a device for 'true' or 'false' rather than 'on' or 'off'. Future versions of the library may allow for using native Indigo states but for now it treats them as native Python values instead.

As with everything else in conditions, values are not case sensitive.

Setting Conditions - In Depth

Evaluation Basics

Equal To / Not Equal To - Check if the value is the same or is not the same as the value you provide. When comparing dates seconds are not compared.
Greater Than / Less Than - Check if the value is more or less than the value you provide. This should not be used for boolean values since they can only be one of two values.
Between / Not Between - Check if your value is equal to or falls between the two values you provide.
Contains / Does Not Contain - Check if the value you provide appears within the value you are evaluating.

Date and Time Evaluations

ANY - This special value found in dates is a catch-all and means that you essentially ignore that field when comparing to another date.
Year - The year can be the current year, last year, next year, any year or select between 2010 - 2030.
Month - The month can be selected or you can choose any for a catch-all
Day - You can select a date, use any for a catch-all, use the last day of the month or iterations of a day of the week (first, second, third, fourth, last).
Day of the Week - You can select a specific day of the week or any for any day. If you use iterations in the Day field you must select a day.
Time - Select a time (in 15 minute increments) or any for a catch-all.

Condition Disabled
If you select this option then this condition will not be evaluated, but all others that are not disabled will be.

Containing and Between
Select any Indigo device and then any device state to base your evaluation upon. In pseudo-code it works like this:
Code: Select all
IF [device][state] [equals, not equals, greater than, less than, between, not between, contains, doesn't contain] [value(s) you specify] THEN condition = True

So, if you configured the condition as:
Conditions - Device State.png
Conditions - Device State.png (38.39 KiB) Viewed 13601 times

Then it evaluates as:
Code: Select all
IF WeatherSnoopBowMar  weather state contains the word 'cloudy' THEN condition is True

Therefor if the weather state equals "Cloudy", "Partly Cloudy" or "Mostly Cloudy" then the condition passes, but if it equals "Overcast" it does not.

However if you had these options:
Conditions - Device State 2.png
Conditions - Device State 2.png (42.51 KiB) Viewed 13601 times

Then if the weather state is "Clear", "Cloudy", "Mostly Cloudy" or "Overcast" then the condition passes, but if it was "Partly Cloudy" it would not.

Date and Time
Only returns true when the date and/or time matches your criteria. This is pretty straightforward but there are some nuances to be aware of. One nuance is the use of "any" as the value in any date or time field. Using "any" indicates that you really don't care what the that value is. Take for example this configuration:
Conditions - Date Time.png
Conditions - Date Time.png (45.1 KiB) Viewed 13601 times

Evaluates as:
Code: Select all
IF the time is between 8:00 AM and 11:59:59 PM then return true

It's important to know that when you are evaluating times open ended like this that it will evaluate only the current day, so every minute past 8:00 AM is greater than 8:00 AM, but midnight, which equates to 00:00:00, is less.

You could make this more universal by adding another parameter:
Conditions - Date Time 2.png
Conditions - Date Time 2.png (44.73 KiB) Viewed 13601 times


This option would mean any time past 8:00 AM on the 1st of any month of any year is greater and, thus, true. Since there is no "day 0" it will always be true except before 8:00 AM on the first of any month.

Another key feature of using date and/or time conditions is the ability to select variable dates. For instance:
Conditions - Date Time 3.png
Conditions - Date Time 3.png (41.48 KiB) Viewed 13601 times

Allows you set a condition based on if the current date is the first Sunday of the month. Similarly you can choose the second, third, fourth or last week day of the month as parameters.

Date and Time From Devices or Variables
Evaluating a date and/or time from a device state or variable is the same as using the current date and/or time with the exception that you need to define how that date appears in that device state or variable. The date/time definition is based on Python date/time formatting and the default value will already be set to what the majority of dates and times used in Indigo already are: "%Y-%m-%d %H:%M:%S". If your definition is off, even by a single character, the evaluation will fail and an error will be logged in Indigo.

Conditions - Special Date Time.png
Conditions - Special Date Time.png (54.78 KiB) Viewed 13601 times
Attachments
Screen Shot 2016-07-07 at 6.10.49 PM.png
Stupidly Complex Condition from Powermiser
Screen Shot 2016-07-07 at 6.10.49 PM.png (127.17 KiB) Viewed 13589 times

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Thu Jul 07, 2016 11:02 pm
ckeyes888 offline
Posts: 2417
Joined: Nov 26, 2009
Location: Kalispell, MT

Re: Plugin Docs: Conditions

Is there someway to use this amazing piece of work to replace, or enhance, the existing
Indigo conditions dialogs?

I'm rather drooling at the prospect of getting rid of virtually every conditions script
I have.

Thanks,

Carl

Posted on
Fri Jul 08, 2016 6:11 am
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: Plugin Docs: Conditions

Possibly. I'm going to roll it into all of my plugins that need conditioning so there's that, but outside of that it wouldn't be too terribly difficult to make a "generic" plugin that lets you control a device or variable based on the result of the condition. I would really have to think hard about how to do that because to re-create the Indigo built-in conditions like that would mean that any plugin that I write to that end would have to be quite flexible and robust and be able to do what Indigo does in far less "screen real-estate".

Give me an idea of a few things you would like to replace.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Fri Jul 08, 2016 7:59 am
ckeyes888 offline
Posts: 2417
Joined: Nov 26, 2009
Location: Kalispell, MT

Re: Plugin Docs: Conditions

I have a number of scripts that test for a word in a variable and/or have rather complex date and time
values. For the most part I just really like your UI much better than Indigo's. Much more room for entries
just reads better.

Thanks,

Carl

Posted on
Fri Jul 08, 2016 8:06 am
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: Plugin Docs: Conditions

ckeyes888 wrote:
I have a number of scripts that test for a word in a variable and/or have rather complex date and time

And the scripts then do what after testing true? Given the screen real estate requirements of having so much in my conditions I don't know that I would be able to create something that does much more than either change 2-4 devices/variables or run 2-4 action groups. It won't be like Indigo where you can have a nearly unlimited number of "actions" to perform - so it would be a bit more limited.

The idea is interesting though and since the conditions framework is already in place then it would be a pretty simple matter to do the rest. Since I just released the conditions you might want to pick up Powermiser and play around with the conditions and see how they work and if they fit your basic need, just think about "well if Powermiser will set an auto-off timer then my action group will fire". Just set up Powermiser to auto-off your device(s) after a minute or so to know if the conditions work for you - and if you turn off "physical only" then you can just send the On commands from Indigo for the testing.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Fri Jul 08, 2016 9:25 am
ckeyes888 offline
Posts: 2417
Joined: Nov 26, 2009
Location: Kalispell, MT

Re: Plugin Docs: Conditions

The majority of my actions are simply action groups. So after the conditions are true it just
executes a single action group. For me it saves a lot of duplication and is much easier to edit.

I'll experiment with Powermiser. Not sure I understand the real estate restriction.
It wouldn't matter to me if your conditions popped up and filled the entire screen,
in fact I would find that terrific.

Thanks,

Carl

Posted on
Fri Jul 08, 2016 9:29 am
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: Plugin Docs: Conditions

ckeyes888 wrote:
Not sure I understand the real estate restriction.

Indigo plugin windows have just two columns, so taking up too much room means the window will be as tall as your screen can handle and scrolls the rest. Completely usable but it can be tough to get around and since conditions require a lot of back-and-forth communication with the plugin while you configure it that means that each time you change a condition field the screen refreshes and puts you back at the top of the screen, then you have to scroll down for the next field - it could get annoying. For that reason I've tried to keep the window size such that when the screen refreshes it won't force you to scroll around.

But I will do some test development and see what I can come up with and let you know when there's a beta for you to play with - although it will be a little while as I'm doing other updates on my plugins at the moment.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Fri Jul 08, 2016 12:26 pm
ckeyes888 offline
Posts: 2417
Joined: Nov 26, 2009
Location: Kalispell, MT

Re: Plugin Docs: Conditions

Thanks, appreciate the info and the amazing plugins!

Carl

Posted on
Fri Jul 08, 2016 5:22 pm
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: Plugin Docs: Conditions

I've been giving a lot of thought to incorporating conditions in a way similar to your suggestion and have thought of a good way to do it, look for a full on plugin in the coming weeks.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Fri Aug 26, 2016 11:08 pm
srkinard offline
Posts: 320
Joined: Apr 10, 2016
Location: Austin, Texas

Re: Plugin Docs: Conditions

I'm feeling a little stupid saying this, but I can't find the download anywhere...maybe a lack of sleep or something.

Posted on
Sat Aug 27, 2016 8:15 am
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: Plugin Docs: Conditions

This is just documentation for conditions, the actual functionality itself is currently only in Powermiser but it's something that's going to be a part of a lot of my plugins so I put this up as generic documentation for it for all plugin documentation to point to in order to explain how conditions work.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Page 1 of 1

Who is online

Users browsing this forum: No registered users and 3 guests