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