Events

Under the Events menu you find functionality to automate things like switching on lights when it becomes dark.
Things are architectured such that an event is executed when it is triggered and (optional) condition(s) are met and resulting in one or more action(s) to be executed.

The list of Events can be accessed through the Events icon in the Main menu bar on the left, using the Events menu (Events --> List Events).

The sub-menus can be accessed through the Events menu or when you have that open, through the Events, Triggers and Actions buttons under the main tab row.


Events

An event is something that links an trigger and (optional) conditions to one or more action(s) to be executed.

You can list the current defined events using the Events button under the main tab row.
You can add an event using Events -> Add Event.

  • To edit an event double click or right click -> Edit event on the line of the event in the event list.
  • To delete an event do a right click -> Delete event on the line of the event in the event list or open the event editor and press the Delete button
  • To run the action(s) tight to an event right click -> Run action(s)
Event Main tab
  • The Name is a name for the event and must be unique.
  • Enabled should be set to make it active
  • Run First and Run Last indicate the first and last run
  • Right from IF you can select/create an trigger.
    • Push the drop down arrow to get a list of current triggers or press Create to create a new trigger.
  • Right from AND you can add (optional) condition(s).
    • Push the drop down arrow to get a list of current triggers or press Create to create a new condition.
  • Enable Don't run event if it already ran in the last if the trigger is active not once but a longer time and you like the action to be executed only once or once a while.
  • Under Action(s) there is a list of the action(s) (one or more) that should be executed.
 
Event Options tab
  • Description can be used to give a description for the event
  • Log event changes = When the event occurs, it will be shown in the main logfile
  • Category = You can sort different events in a specified category (lights, PIR, ....)
    In the event list you can show the different events in different category.
    You need to add the category before you can add a event to it.
     

Triggers

An trigger is what starts an event.
For triggers you can think of:
  • Time is sunset
  • Movement outside is detected
  • Bathroom is humid

You can list the current defined triggers using the Triggers button under the main tab row or by pressing the drop down arrow in the Create/Edit Event window.

You can add a trigger using Events -> Add Trigger or pressing the Create button when in the Event window.

Time Now triggers

Time Now triggers utilize cron, and entries therefore comply with crontab entries

For a trigger that happens every 5 minutes:

*/5 * * * *

*/5 means the minute count needs to be divisible by 5

For a trigger that occurs every 15 minutes between 06-22 on Monday-Friday use:

*/15 6-22 * * 1-5

You can also specify minute-intervals manually, for example, 6min interval

0,6,12,18,24,30,36,42,48,54 * * * *

Time Now triggers are only checked once a minutes so if you want a trigger that fires 24x7 each minute, use:

* * * * *

You can "or" multiple cron entries using a multi-trigger.

Sunrise and Sunset

The Sunrise and Sunset Time Now triggers are special in the sense that Time Now CronTab string are updated by the Astro module at startup and the begin of every new day.

The triggers having the name "Time is Sunset" and "Time is Sunrise" are the ones that are updated, so if you want to use them, make sure the name is exactly this.

The "41 16 * * *" value you see above is updated the begin of every new day, 16:41 is the sun set time in Rotterdam for 2 January.

Variable triggers

With a Variable trigger you can trigger an event when a "global variable" becomes a certain value, for example:

Var_Dark = TRUE

Device Status

This Device Status trigger will fire when a value from a device becomes equal to/larger than/smaller than/not equal to a given Compare Value.


So to get a notification (E-mail, Prowl, Notify My Android, Pushover etc.) when the temperature outside becomes near to the freezing point:
  • Select a device that measures the temperature outside and select the right variable
  • The Current Value field will display the last known value for the device/variable
  • Select either equal to/larger than/smaller than/not equal to
  • And give the Compare Value

This trigger will fire every time the temperature is measured and the condition is met.

The Compare value does not support only plain values. For the use of more advanced formulas, "Dev_X_Value_Y values" or global variables, use a Device Lastseen trigger in combination with a condition.

 

Device Lastseen

This trigger will fire whenever (one of the values of) a device is updated.

This is the type of trigger you likely want to use if you want to do something with the values of a device.

To test things you can create the trigger, use it as IF of an event and add a Write Log action that writes the value to the log. Then check the main log to see if the trigger triggers when you want it to trigger.

Multi-trigger

This trigger type can be used to trigger on a combination ("or") of conditions.

As input to the or you can use "cron entries", global variables and devices values including LastSeen, LastChanged and BatteryStatus.

See also Battery-status under Tricks.

Conditions

Conditions differ from triggers in the sense that they are never directly triggered. An event must always be first triggered before a condition is checked. If this is a problem, in most cases a trigger based on the same condition can be created or you create a condition that triggers every minute, 24x7, see above.

Conditions are evaluated as Boolean expressions meaning they should return True or False.

You can list the current defined conditions using the Conditions button under the main tab row or by pressing the drop down arrow in the Create/Edit Event window.

You can add a trigger using Events -> Add Condition or pressing the Create button when in the Event window.

  • The Name is a name for the condition and must be unique.
  • Description can be used to give a description for the condition
  • Under menus you can find lists of Variables, Devices (and device values), Functions, Operators, Actions and Macros that can be used in the Boolean expression. Once have have select an entry, use the Add button to add it to the Boolean expression.
  • Current values give the value for the (last) selected Variable or Device variable.
  • The Enter here a Boolean expression: box gives the actual Boolean expression
  • Press the Eval button to evaluate the current Boolean expression. It should give True or False and no error.
     

    Some examples:

Check device value

To check for example if the TV is turned off the power usage of the device need to be changed to a floating point ("CFloat") to check the value correctly:

CFloat(Dev_1_Value2) < 5

The CFloat() or Val() is needed as otherwise the value is interpreted as string meaning for example that "6.4" is higher then "16.4".

Time Range

To create a condition that is only valid within a time-range (06-22)

(Hour(Now()) < 22) AND (Hour(Now()) > 6)

Check if any device is down

For this you want to check if the device "lastseen" was longer than a certain timeout.
To check if device 67 was last seen more than 30 minutes ago:

DateDiff(Dev_67_LastSeen, Now(), gb.Minute) > 30

Device last changed in the last N minutes

To check if a device (84) was changed in the last 30 minutes and it´s current value is anything but "on" (useful for motion detection etc.):

(
  (
    Hour(Now()) = Hour(Dev_84_LastChanged) AND  Minute(Now()) > Minute(Dev_84_LastChanged) + 30
  ) OR (
    Hour(Now()) > Hour(Dev_84_LastChanged) AND (Minute(Now()) + 60 - Minute(Dev_84_LastChanged)) > 30)
  )
) AND (Dev_84_Value1 <> "On")

Alternatively, and much more concisely, try:

(Now() > Dateadd(Dev_84_LastChanged, gb.minute, 30)) AND (Dev_84_Value1 <> "On")

... and set it so the event doesn't trigger again in the next 30 minutes.

Switching before or after Sunrise/Sunset

Apart from the special Sunrise-and-Sunset you can also use a condition: make a Time-Now trigger that triggers every minute and add a condition that checks:

Var_Sunset = Format(hour(now()),"0#") & ":" & Format(minute(now()),"0#")

Var_Sunset is the Sunset global variable that is updated every day based on your location by the Astro module. Apart from Sunset there is also Sunrise, Sunrise_Twilight and Sunset_Twilight.

If Sunrise/Sunrise_Twilight and Sunset/Sunset_Twilight is not exactly the right time, you can offset things.
By adding (30 in example) minutes to minute(Now()) the event is raised sooner:

Var_Sunset = Format(hour(DateAdd(now(), gb.Minute, 30)),"0#") & ":" & Format(minute(DateAdd(now(), gb.Minute, 30)),"0#")

Or subtract time (15 min), it will be later:

Var_Sunset = Format(hour(DateAdd(now(), gb.Minute, -15)),"0#") & ":" & Format(minute(DateAdd(now(), gb.Minute, -15)),"0#")

Comparing device values

To set Device 15, Value 1 to "Off" when Device 7, Value 1 is greater than Device 18, Value 2 and otherwise "On":

Dev_15_Value1 = IIf(Val(Dev_7_Value1) <= Val(Dev_18_Value2), "On", "Off")

Actions

Actions make things happen, from switching a lamp on, sending an email or updating an variable to whatever you can think of.

You can list the current defined actions using the Actions button under the main tab row or by pressing the drop down arrow in the Create/Edit Event window.

You can add an action using Events -> Add Action or pressing the Create button when in the Event window.

  • The Name is a name for the action and must be unique.
  • Description can be used to give a description for the action
  • Action Type can a:
    • Device action: Set Device, Send IRTrans, AV Control, JSON
    • Set GlobalVar
    • Electronic notification: Send E-mail, Send Tweet, Send SMS, Desktop notify-send, Send Prowl, Send Notify My Android, Send Pushover
    • Other notification: Speak Text, Play Sound, Display LED
    • External action: Execute Commands
    • Script
    • Write Log action
    • Delay
       

Templates

For sending notifications you can insert templates inside action text, just like you can use templates in device values. The templates are replaced with their values upon executing.
Current implemented templates:

<%global var%>          - insert globalvar value
<$device id|field$>     - insert value field number 'field' from device with 'device id'

The field can be, 'value1' or just 1,'value2' or 2, 'value3' or 3,'value4' or 4, 'lastseen', 'lastchanged' or 'batterystatus'

See below Write Log action for an example.

Write Log action

This action can be handy to debug things. Just create a script to dump the values that you want to know, see also Events above.

  • <%Weather_Temp%> writes the temperature according to WeatherUnderground
  • <$70|1$> writes the temperature according to the sensor #70, value #1
     

Set device value

Setting a device value can be handy for virtual devices and to "override" other values.

For the value you can use templates.

 

Only Value1 is set, other values are updated.

The current implementation of DomotiGa is so that only Value1 is really set to the external device (Devices.SetDevice), for the other values the internal value is updated (Devices.ValueUpdate) but no command is send to the external device.

See RE: ArduinIO thread - A generic(ish) arduino IO module fo... for more detail including a code snippet.

Delay

The delay action can be used to add a delay between actions

  • The Name and Description are to identify the action
  • The Id is a internal number used by DomotiGa for the action
  • The Action Type should be set to Delay
  • Using the Randomize button you can select either a fixed or a random delay
    • For a fixed delay you just have to specify the delay
    • For a random delay you have to specify the range
       

GET/POST JSON

The json action can be used to get or post json to a given url.

  • The Name and Description are to identify the action
  • The Id is a internal number used by DomotiGa for the action
  • The Action Type should be set to JSON
  • The Device is a device that is modify by the get method or posted by the post method

When using the get method the flowing json expected to parse and update the device. Also is this format posted to the given url if you are using the post method.

{"values":[{"valuenum":1,"value":18.1},{"valuenum":2, "value": 21.2}, ....]}

 

Scripts

Actions are limited to one action only but in the event editor you can add multiple actions to one event.

An alternative approach is to add more commands to an "action script" or macro by doing this:

action1() &
action2() &
action3()

This action script/macro can then be called by from an action, set Action Type to Script and select the script.

You can add a script by creating an action with Action Type to Script and then pressing the Editor button right under or by selecting Events -> Edit Macro and pressing the Add button.

You can list and edit scripts/macros by selecting Events -> Edit Macro. If you select a macro, the contents of the macro will be displayed and if you press the Eval button, the macro will be executed and the result displayed.

Script contents

You can get a reasonable complete list of the things a script can consist of by opening the script editor. Open the Macro Editor (Events -> Edit Macro), select a Macro and press the Edit button:

Script testing

You can test your complete script by pressing the "Run" button and check the script result output. However if you want to debug your script you can also make a selection of a part of your script and press the "Run" button and only that portion of the script will be evaluated.

Script example actions

Some typical examples you can use in the script editor are:
  • Update a value of a device -- Devices.ValueUpdate(<DeviceId>, <ValueNum>, <Value>):
    Devices.ValueUpdate(40, 1, "Off")
  • Change the status of a device -- Devices.SetDevice(<DeviceId>, <Value>):
    Devices.SetDevice(23, "On")
  • A "conditional" action -- Devices.SetDevice(<DeviceId>,If(<Cond>, <TrueExpr>, <FalseExpr>)):
    Devices.SetDevice(12, If(Var_Dark, "On", "Off"))

    When this action is triggered it switches device 12 on when it is Dark else it switches the device off.
  • You can also call routines inside plugins if they are public
  • For example send a Twitter msg (using instance 1)
    Plugin.GetPluginObject("Twitter", 1).Interface.PostTweet("Just a test")
  • Publish a MQTT message
    Plugin.GetPluginObject("MQTT", 1).Interface.PublishMsg("my/topic", "message", True)

If Actions
Be careful using the If(<Cond>, <TrueExpr>, <FalseExpr>) with an "action" in the False or True Expression. When the If-function is used in the script editor it will actually evaluate both the True and False Expression of the If-statement irrespective of the Condition. So you should prevent using any "real actions" in the true/false expressions. As an example, contrary maybe to your initial expectation, the following piece of script will always result in a device 12 being first being turned "on" and then turned "off" as both true and false expression are evaluated:

If(Var_Dark, Devices.SetDevice(12, "On"), Devices.SetDevice(12, "Off")) <== !!! Don't do this !!!

See also the Gambas documentation on this and A "genuine" IF-statement for the Event Script Editor (onl... for an alternative way.

Tricks

Timer event

While there is (currently) no support for a timer event you can do timed events using the Delay action and alternatively using the Time Now trigger.

Suppose you have a controlled toilet light with switch that can control the light but people forget to put off the light and you want to automatically turn it off after 15 minutes.

The "problem" here is that there seems to be no way to trigger an event after 15 minutes the light was switched on.

One possible work-around is to have a time-now event triggering every 5 five minutes and checking if the light is (still) on and if the TimeNow - LastChanged for the switch is 15 minutes or longer and if so switch of the light. That will work but the drawback is that the time-now event will be triggering every five minutes also when it is not needed.

The better approach is to use a Delay action in the list of actions for a "switch on" event and have an action after the delay switching the light off.

If you also want to cover the situation that somebody goes to the toilet, switches the light off but after 14 minutes the light is switched on again you might want to add a condition to to check the TimeNow - LastChanged for the switch is 15 minutes or longer.

Counter/integrator

If you want to count pulses or to sum the samples you get from a device value you can use an unused value of the device (for example Value5) and have a formula like:

Val5[New] = Val5[Old] + Val1[New]

Implemented (for the device with id 17) using a script like:

Devices.ValueUpdate(17, 5, Dev_17_Value5 + Dev_17_Value1)

If you trigger this script every valueupdate of Dev_17_Value1, Value5 will give the summed/integrated value of Value1.

Send a "On" command even if the device is already "On"

Create a trigger like this

if [deviceNAME][LastSeen] <> " " 

Create two events for setting your device(s) "On" or "Off"

"On" uses the trigger above and a condition like Dev_XX_Value1="On" (where XX is your device ID that triggers the event)
"Off" uses the trigger above and a condition like Dev_XX_Value1="Off"

Battery status

You can have a script that mails the battery status for all devices using the "Action Script" with "Devices.MailBatteryStatus(["all"|"empty"])" in it which you can find under the script editor -> Actions -> Status:


    Updated by: jessekerkhoven, Updated over 1 year ago
    Access count: 49526 since 2014-08-02

    Attached Files

    Events_Menu.png (16.8 KB) danfos, 08/02/2014 12:08 PM

    Sidebar_Events.png (9.91 KB) danfos, 08/02/2014 06:04 PM

    Event_edit.png (54.1 KB) danfos, 08/02/2014 07:01 PM

    Event_options.png (30.7 KB) danfos, 08/02/2014 07:01 PM

    Trigger_edit.png (45.4 KB) danfos, 08/02/2014 07:32 PM

    Crontab.png (17.5 KB) danfos, 08/02/2014 07:42 PM

    Condition_edit.png (46.7 KB) danfos, 08/02/2014 08:01 PM

    Action_edit.png (40.5 KB) danfos, 08/02/2014 08:44 PM

    Edit_Script.png (34.1 KB) danfos, 08/09/2014 03:44 PM

    Action_Write_log.png (32 KB) danfos, 08/10/2014 10:39 AM

    Action_Set_Device_Value.png (34.6 KB) danfos, 08/10/2014 10:05 PM

    Delay_Action.png (38 KB) danfos, 09/06/2014 05:53 PM

    Trigger_device_status.png (12.8 KB) danfos, 11/18/2014 10:55 AM

    TimeIsSunset.png (25.6 KB) danfos, 01/02/2015 05:52 PM

    MailBatteryStatus.png (11.4 KB) danfos, 01/03/2015 10:24 AM

    Also available in: PDF HTML TXT