Lua Scenes — conditions

Actions can be triggered automatically (after trigger meeting condition occurs and other scene conditions are met) or manually. After an event occurs in the system (e.g. device is turned on), the scene checks the triggers. Next, all conditions with logical operators joining them are checked. Single condition can look like this:

1{
2    type = "device",
3    id = 25,
4    property = "value",
5    operator = "==",
6    value = true,
7    duration = 20,
8    isTrigger = true
9}

Description of individual fields:

• type - the type of event in the system, the scene is waiting for.
• id - optional field, depending on the condition type can be interpreted differently.
• property - the property the scene is waiting to be changed.
• operator - the way of comparing current property value and provided value.
• value - the value of the property the scene expects.
• duration - time in seconds of how long the value must be set to match the condition or trigger the scene. 0 by default.
• isTrigger - indicates whether a given condition is also a trigger. Permissible values are true and false.

Triggers and conditions are stored in one array. Example:

1{
2    operator = "any",
3    conditions = {
4        {
5            type = "device",
6            id = 25,
7            property = "value",
8            operator = "==",
9            value = true,
10            isTrigger = true
11        },
12        {
13            type = "device",
14            id = 26,
15            property = "value",
16            operator = "==",
17            value = true,
18            isTrigger = false
19        }
20    }
21}

First condition for device with ID 25 is a trigger. Second condition for device with ID 26 is only a condition.

To join triggers/condition you must use "operator" field. The "operator" field is required even for scenes with one trigger/condition:

1{
2    operator = "any",
3    conditions = {
4        {
5            type = "device",
6            id = 25,
7            property = "value",
8            operator = "==",
9            value = true,
10            isTrigger = true
11        }
12    }
13}

Operator field accepts one of two values:

• any - at least one of the triggers/conditions must be met.
• all - all of the triggers/conditions must be met.

Conditions can be joined and mixed:

1{
2    operator = "all",
3    conditions = {
4        {
5            type = "device",
6            id = 25,
7            property = "value",
8            operator = "==",
9            value = true,
10            isTrigger = true
11        },
12        {
13            operator = "any",
14            conditions = {
15                {
16                    type = "device",
17                    id = 26,
18                    property = "value",
19                    operator = "==",
20                    value = true,
21                    isTrigger = true
22                },
23                {
24                    type = "device",
25                    id = 27,
26                    property = "value",
27                    operator = "==",
28                    value = true,
29                    isTrigger = true
30                }
31            }
32        }
33    }
34}

The example above will start the scene if property "value" changes to true for device with id 25 and for at least one of the devices with id 26 or 27.

Trigger vs condition

Distincting between triggers and conditions is done by setting "isTrigger" field appropriately, if the field is not set, it takes false by default.

1. Trigger (isTrigger set to true) - an event in the system, specified exactly in the scene, which checks the remaining conditions of the scene.
2. Condition (isTrigger set to false or not set) - the factor on which the stage execution depends.

1{
2    operator = "all",
3    conditions = {
4        {
5            type = "device",
6            id = 25,
7            property = "value",
8            operator = "==",
9            value = true,
10            isTrigger = true
11        },
12        {
13            type = "device",
14            id = 26,
15            property = "value",
16            operator = "==",
17            value = true,
18            isTrigger = false
19        }
20    }
21}

The first condition for device with ID 25 is a trigger, while the second condition for device with ID 26 is only a condition. This means that if an event occurs that changes "value" property of device 25 to true, the same event will trigger a check of all triggers used in the scenes. Only when the trigger is met (as in the above scene), further conditions (isTrigger = false) are checked. Checking the condition means checking that for device 26 the "value" property is set to true. If so, then all the conditions of the above scene (trigger + condition) have been met and the action can be performed.

There may also be a situation, where the "value" property is changed to true for device 26. This situation will also generate event of changing the value value for a given device. However, because the condition for device 26 is not a trigger, the scene conditions will not be checked (even if the "value" property in device 25 was previously set to true).

Types of triggers and conditions

The following chapter will discuss each type of trigger and the conditions that are available in the system.

Devices

For devices, the interpretation of conditions fields is as follows:

• type - takes value "device".
• id - takes the ID of the device for which to check if the given property has the given value.
• property - the name of the property to check.
• value - value of the property to compare the current value to.
• operator - depending on type:

  1* text type: 
  2    * `"=="` -  are the texts the same
  3    * `"!="` - are the texts different
  4    * `"anyValue"` - match any value
  5* numeric type:
  6    * `"=="` - are the values ​​the same
  7    * `"!="` - are the values ​​different
  8    * `">"` - is the current value greater than the one in the condition
  9    * `">="` - is the current value greater than or equal to the one in the condition
  10    * `"<"` - is the current value lesser than the one in the condition
  11    * `"<="` - is the current value lesser than or equal to the one in the condition
  12    * `"anyValue"` - match any value
  13* logical type: 
  14    * `"=="` - are the values ​​the same
  15    * `"!="` - are the values ​​different

  rigger the scene if value of device with ID 30
• isTrigger - is the condition also a trigger:
  • true - is a trigger
  • false - is only a condition (default)

Examples: Trigger the scene if value of device with ID 30 is higher than 25.

1{ 
2    type = "device",
3    id = 30,
4    property = "value", 
5    operator = ">", 
6    value = 25,
7    isTrigger = true
8}

Trigger the scene if value of device with ID 30 is true for 20 seconds.

1{ 
2    type = "device",
3    id = 30,
4    property = "state", 
5    operator = "==", 
6    value = true,
7    duration = 20,
8    isTrigger = true
9}

rigger the scene if value of device with ID 30 changed to any value.

1{ 
2    type = "device",
3    id = 30,
4    property = "value", 
5    operator = "anyValue",
6    isTrigger = true
7}

Time and date

For time and date, the interpretation of conditions fields is as follows:

• type - takes value "date".
• property - takes value "cron".
• value - is an array of text values whose subsequent elements take the following:
  • minutes - takes value from 0 to 59,
  • hours - takes value from od 0 to 23,
  • day of month - takes value from od 1 to 31,
  • month - takes value from od 1 to 12,
  • day of week - takes value from od 1 to 7,
  • year
• operator - for different types:
  • "match" - whether the date matches the date in the condition, in this operator we can use "*" which means any match.
  • "match==" - are the dates the same.
  • "match!=" - are the dates ​​different.
  • "match>" - is the date later than date in the condition.
  • "match>=" - is the date the same or later than date in the condition.
  • "match<" - is the date earlier than date in the condition.
  • "match<=" - is the date the same or earlier than date in the condition.
• isTrigger - is the condition also a trigger:
  • true - is a trigger
  • false - is only a condition (default) With time conditions, you should use isTrigger carefully, especially for time intervals. Every minute the system emits an event that results in checking scenes triggers. Inappropriate use of the timer can trigger the scene every minute.

Examples: Every day at 15:30.

1{
2    type = "date",
3    property = "cron",
4    operator = "match",
5    value = {"30", "15", "*", "*", "*", "*"},
6    isTrigger = true
7}

13.06.2018 at 12:30.

1{
2    type = "date",
3    property = "cron",
4    operator = "match",
5    value = {"30", "12", "13", "6", "1", "2018"},
6    isTrigger = true
7}

Every Monday and Wednesday at 15:30.

1{
2    type = "date",
3    property = "cron",
4    operator = "match",
5    value = {"30", "15", "*", "*", "1,3", "*"},
6    isTrigger = true
7}

Every Monday and Wednesday and Friday.

1{
2    type = "date",
3    property = "cron",
4    operator = "match",
5    value = {"*", "*", "*", "*", "1,3,5", "*"}
6}

25th day of every month.

1{
2    type = "date",
3    property = "cron",
4    operator = "match",
5    value = {"*", "*", "25", "*", "*","*"}
6}

Every day between 9:00 and 10:00. No isTrigger means it is false.

1{
2    operator = "all",
3    conditions = {
4        {
5            type = "date",
6            property = "cron",
7            operator = "match>=",
8            value = {"0", "9", "*", "*", "*","*"}
9        },
10        {
11            type = "date",
12            property = "cron",
13            operator = "match<",
14            value = {"0", "10", "*", "*", "*","*"}
15        }
16    }
17}

Interval

For intervals, the interpretation of conditions fields is as follows:

• type - takes value "date".
• property - takes value "cron".
• value - consists of 2 fields:
  • date - is the starting date of the interval and is an array of text values whose subsequent elements take the following:
    • minutes - takes value from 0 to 59,
    • hours - takes value from od 0 to 23,
    • day of month - takes value from od 1 to 31,
    • month - takes value from od 1 to 12,
    • day of week - takes value from od 1 to 7,
    • year
  • interval - time in seconds between each execution.
• operator - takes value "matchInterval".
• isTrigger - is the condition also a trigger:
  • true - is a trigger (recommended)
  • false - is only a condition (default)

Examples: Condition true every 5 minutes, starting at 12:00 5.04.2019

1{
2    type = "date",
3    property = "cron",
4    operator = "matchInterval",
5    value = {
6        date = { "0", "12", "5", "4", "*", "2019" },
7        interval = 300
8    },
9    isTrigger = true
10}

Sunrise and sunset

For sunrise and sunset, the interpretation of conditions fields is as follows:

• type - takes value "date".
• property - takes one of two values:
  • "sunrise" - sunrise,
  • "sunset" - sunset.
• value - time in minutes before/after sunrise/sunset:
  • Values lower than 0 indicate how many minutes before sunrise/sunset the scene should start.
  • Value 0 means that the scene should take place at sunrise/sunset.
  • Values greater than 0 indicate how many minutes after sunrise/sunset the scene should start.
• operator - takes value "==".
• isTrigger - is the condition also a trigger:
  • true - is a trigger (recommended)
  • false - is only a condition (default)

Examples: Everyday 60 minutes before sunset.

1{
2    type = "date",
3    property = "sunset",
4    operator = "==",
5    value = -60,
6    isTrigger = true
7}

Everyday 120 minutes after sunset.

1{
2    type = "date",
3    property = "sunrise",
4    operator = "==",
5    value = 120,
6    isTrigger = true
7}

Everyday at sunrise.

1{
2    type = "date",
3    property = "sunrise",
4    operator = "==",
5    value = 0,
6    isTrigger = true
7}

Weather

For weather, the interpretation of conditions fields is as follows:

• type - takes value "weather".
• property - takes one of these values:
  • "Temperature" - temperature,
  • "Wind" - windspeed,
  • "WeatherCondition" - weather condition,
  • "Humidity" - air humidity.
• value - values depend on used property, available values:
  • Temperature - numerical value, the temperature unit depends on the system settings. If the unit is changed after creating the scene, the scene should be corrected by the user, because after changing the unit in the system, the value will not be automatically recalculated.
  • Wind - numerical value, the wind unit depends on system settings. If the unit is changed after creating the scene, the scene should be corrected by the user, because after changing the unit in the system, the value will not be automatically recalculated.
  • WeatherCondition - text value of selected weather condition:
    • "cloudy"
    • "rain"
    • "snow"
    • "storm"
    • "clear"
    • "fog"
    • "unavailable"
  • Humidity - numerical value.
• operator - depending on type:
  • text type:
    • "==" - are the texts the same
    • "!=" - are the texts different
    • "anyValue" - match any value
  • numeric type:
    • "==" - are the values ​​the same
    • "!=" - are the values ​​different
    • ">" - is the current value greater than the one in the condition
    • ">=" - is the current value greater than or equal to the one in the condition
    • "<" - is the current value lesser than the one in the condition
    • "<=" - is the current value lesser than or equal to the one in the condition
    • "anyValue" - match any value
• isTrigger - is the condition also a trigger:
  • true - is a trigger
  • false - is only a condition (default)

Examples: True, when temperature drops below 20°C or 20°F (depending on settings).

1{
2    type = "weather",
3    property = "Temperature",
4    operator = "<",
5    value = 20,
6    isTrigger = true
7}

True, when when wind speed is higher than 15[km/h] or 15[mph] (depending on settings).

1{
2    type = "weather",
3    property = "Wind",
4    operator = ">",
5    value = 15,
6    isTrigger = true
7}

True, when weather turns cloudy.

1{
2    type = "weather",
3    property = "WeatherCondition",
4    operator = "==",
5    value = "cloudy",
6    isTrigger = true
7}

True, when humidity rises above 80%.

1{
2    type = "weather",
3    property = "Humidity",
4    operator = ">",
5    value = 80,
6    isTrigger = true
7}

Location

For location, the interpretation of conditions fields is as follows:

• type - takes value "location".
• property - ID of location the user enters/leaves (numerical).
• id - ID of the user (numerical).
• value - takes one of two values:
  • "leave" - user leaves the location
  • "enter" - user enters the location
• operator - depending on type:
  • "==" - are the values the same
  • "!=" - are the values different
  • "anyValue" - match any value
• isTrigger - is the condition also a trigger:
  • true - is a trigger
  • false - is only a condition (default)

Examples: True, when user 36 enters location 2.

1{
2    type = "location",
3    id = 36,
4    property = 2,
5    operator = "==",
6    value = "enter",
7    isTrigger = true
8}

Custom events

For custom events, the interpretation of conditions fields is as follows:

• type - takes value "custom-event".
• property - name of the custom event (text).
• isTrigger - takes value true.

Examples: True, when custom event with name "event_name" occurs.

1{
2    type = "custom-event",
3    property = "event_name",
4    operator = "==",
5    isTrigger = true
6}

Alarms

For alarms, the interpretation of conditions fields is as follows:

• type - takes value "alarm".
• property - takes one of these values:
  • "armed" - check if zone with given id is armed
  • "breached" - check if zone with given id is breached
  • "homeArmed" - check if alarm for whole house is armed
  • "homeBreached" - check if alarm in house is breached
• id - zone ID, required only for properties "armed" and "breached".
• value - takes one of these values:
  • true - if alarm is armed/breached for zone/house
  • false - if alarm is NOT armed/breached for zone/house
• operator - depending on type:
  • "==" - are the values the same
  • "!=" - are the values different
  • "anyValue" - match any value
• isTrigger - is the condition also a trigger:
  • true - is a trigger
  • false - is only a condition (default)

Examples: True, when zone 1 was armed.

1{
2    type = "alarm",
3    property = "armed",
4    id = 1,
5    operator = "==",
6    value = true,
7    isTrigger = true
8}

True, when zone 1 was disarmed.

1{
2    type = "alarm",
3    property = "armed",
4    id = 1,
5    operator = "==",
6    value = false,
7    isTrigger = true
8}

True, when alarm in zone 1 was breached.

1{
2    type = "alarm",
3    property = "breached",
4    id = 1,
5    operator = "==",
6    value = true,
7    isTrigger = true
8}

True, when alarm in zone 1 was deactivated.

1{
2    type = "alarm",
3    property = "breached",
4    id = 1,
5    operator = "==",
6    value = false,
7    isTrigger = false
8}

True, when whole house was armed.

1{
2    type = "alarm",
3    property = "homeArmed",
4    operator = "==",
5    value = true,
6    isTrigger = true
7}

True, when whole house was disarmed.

1{
2    type = "alarm",
3    property = "homeArmed",
4    operator = "==",
5    value = false,
6    isTrigger = true
7}

True, when alarm in house was breached.

1{
2    type = "alarm",
3    property = "homeBreached",
4    operator = "==",
5    value = true,
6    isTrigger = true
7}

True, when alarm in house was deactivated.

1{
2    type = "alarm",
3    property = "homeBreached",
4    operator = "==",
5    value = false,
6    isTrigger = true
7}

Gateway startup

For gateway startup, the interpretation of conditions fields is as follows:

• type - takes value "se-start".
• property - takes value "start".
• value - takes value "true".
• operator - takes one of these values:
  • "==" - are the values the same
  • "!=" - are the values different
• isTrigger - is the condition also a trigger:
  • true - is a trigger (recommended)
  • false - is only a condition (default)

Examples: Trigger on every startup.

1{
2    type = "se-start",
3    property = "start",
4    operator = "==",
5    value = true,
6    isTrigger = true
7}

Profiles

For profiles, the interpretation of conditions fields is as follows:

• type - takes value "profile".
• property - takes value "activeProfile".
• value - ID of profile to check.
• operator - takes one of these values:
  • "==" - are the values the same
  • "!=" - are the values different
  • "anyValue" - match any value
• isTrigger - is the condition also a trigger:
  • true - is a trigger (recommended)
  • false - is only a condition (default)

Examples: True, when Profile 1 was set as active.

1{
2    type = "profile",
3    property = "activeProfile",
4    operator = "==",
5    value = 1,
6    isTrigger = true
7}