Python Events

Work in Progress

See wiki page Events for more information of the Domoticz build in scripting event system. This python event system has limited functionality, it can only switch devices On/Off, no other update parameters are available.

Please check the other scripting languages with more functionality (dzVents, Lua).

Currently Python is only an option if Domoticz is built from source with Python enabled (but enabled as default)

Introduction

The Python editor is context sensitive and will prompt with auto-complete options and show common errors to help with debugging. The editor theme can be changed by pressing the control and comma keys at the same time. Domoticz will save the scheme when events are saved.

To create a new Python event:

1. Set the Interpreter drop down to Python
2. Set the Event Type drop down to the type of event. Controls what events events will cause Domoticz to execute the script. Drop down values:
   1. All - Will run whenever anything happens that triggers the event system to run a script
   2. Device - Will run whenever ANY device state/value change
   3. Security - Will run whenever there is a security event
   4. Time - Will run once per minute. Scripts are executed one at a time.
   5. User Variable - Will run when User Variables are updated
3. Press the 'New' button.

A template script will be shown that shows one way of processing that type of event.

Domoticz passes information to python scripts through global variables and the domoticz python module

The global variables in the script are:

* changed_device: the current device that changed (object of Device)
* changed_device_name: name of current device (same as changed_device.name)
* is_daytime: boolean, true when it is is daytime
* is_nighttime: same for the night
* sunrise_in_minutes: integer
* sunset_in_minutes: integer
* user_variables: dictionary from string to value

A Device has a number of attributes and methods.

The attributes are:

* id
* name
* type
* sub_type
* switch_type
* n_value
* n_value_string
* s_value
* last_update_string
* last_update: datetime object

The methods are:

* def last_update_was_ago(self, **kwargs):
   Arguments can be: days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]
* def is_on(self):
   returns True when device is On
* def is_off(self):
   returns True when device is Off
* def on(self, after=None, reflect=False):
	  turns device on, after is optional and are the number of seconds after which to turn the device on.
   If reflect is True, a next call to is_on will return True, while normally domoticz will first have to go through possible script before turning it on
* def off(self, after=None, reflect=False):
		simular to on()

uservariables and uservariables_lastupdate are arrays for all user variables:

uservariables['yourvariablename'] = 'Test Value'
uservariables_lastupdate['yourvariablename'] = '2015-12-27 11:19:22'

other useful details are contained in the following global variables:

* is_daytime
* is_nighttime
* sunrise_in_minutes
* sunset_in_minutes
* (TODO) security

Compare to Lua, instead of filling a commandArray, you change the status of a device by calling device.on() or device.off()

TODO: setting variables

Calling Python's print function will not print to the domoticz console.

Examples:

Device triggered script

Also to be found in scripts/python/script_device_demo.py

import DomoticzEvents as DE

DE.Log("Python: Changed: " + DE.changed_device.Describe())

if DE.changed_device_name == "Test":
    if DE.Devices["Test_Target"].n_value_string == "On":
        DE.Command("Test_Target", "Off")

    if DE.Devices["Test_Target"].n_value_string == "Off":
        DE.Command("Test_Target", "On")

DE.Log("Python: Number of user_variables: " + str(len(DE.user_variables)))

# All user_variables are treated as strings, convert as necessary
for key, value in DE.user_variables.items():
    DE.Log("Python: User-variable '{0}' has value: {1}".format(key, value))

# Description of Device_object should go here...

Time triggered script

Also to be found in scripts/python/script_time_demo.py

import DomoticzEvents as DE

if DE.is_daytime:
    DE.Log("Python: It's daytime!")

if DE.is_nighttime:
    DE.Log("Python: It's nighttime!")

DE.Log("Python: Sunrise in minutes: " + str(DE.sunrise_in_minutes))
DE.Log("Python: Sunset in minutes: " + str(DE.sunset_in_minutes))
DE.Log("Python: Minutes since midnight: " + str(DE.minutes_since_midnight))