Scripting in Domoticz
Introduction
Although Domoticz can be up and running in less than half an hour, the fun really starts when adding some intelligence to the home. A great deal of this functionality can be reached with the available program options like timers and notifications. However, when/if things get more complicated then scripting is the solution. This page will introduce the basics of creating scripts, the content of these scripts can be found elsewhere in this Wiki and in the Forum.
Note that the information here is basic Linux and Windows knowledge which can be found at many places on the web. It is brought together here to enable new Domoticz users to understand scripting and start creating scripts themselves quickly.
For example scripts see this wiki page: Scripts.
Kinds of scripts
A script is a text file which contains a number of commands which will be interpreted when the script is executed. To be able to be interpreted the system will need to have the appropriate software installed which understands the specific language used. Examples of scripting languages are Bash, Lua, DzVents, DOS Batchfiles, Python, Perl, Java, and PHP, just to name a few. They all have in common that the commands are read, interpreted and executed at the moment the script is invoked.
It's important to realise that a script can be completely external to Domoticz and even run on a remote machine that does not have its own Domoticz instance installed locally. For some examples of how to do this, visit the Domoticz API/JSON URL's wiki entry.
With Domoticz, three kinds of scripts are very commonly used: Lua scripts, DzVents and Bash shell scripts. DzVents is a scripting language specific for Domoticz developed as an extension to lua. The Lua interpreter is integrated by the Domoticz developers (and so is also available in Domoticz on Windows) and the interpreter for the Bash shell scripts is built in to the Linux OS. Information on what to put in the scripts (i.e. the language) can be found here for Lua and here for Bash.
Python, Lua and DzVents scripts
Domoticz supports two different mechanisms for user-developed Python, Lua and DzVents scripts. Either or both can be used depending upon what you are trying to achieve. DzVents is developed specifically for Domoticz and provides an easy to use interface to all information from Domoticz.
Database Based
Users that are finding Blockly too restrictive and want to extend Domoticz using Python, Lua and/or DzVents (with the added convenience of having their scripts integrated into the Backup & Restore functionality) can use the built-in editor on the Events page.
The built in Ace editorunderstands Lua and by extension DzVents (& Python if Domoticz is built with support turned on) so it provides context-sensitive auto-complete functionality and will flag a number of coding errors within the editor itself.
New Lua and DzVent scripts can be created from standard templates depending on the type of events that the script will handle.
Because database scripts are maintained within a Domoticz web-browser session they are operating-system independent.
With User Variables you can store custom values to be managed in scripts
Continue with the info at Events in this Wiki.
File System Based
For technical users that want to write complicated scripts and include additional Lua modules and scripts, Domoticz also supports file-based scripts. These are not included in the Domoticz standard Backup & Restore functions and are not versioned so this needs to be done manually.
File-system based Lua scripts should be placed in the /home/pi/domoticz/scripts/lua directory. Since Lua is integrated in Domoticz it knows about the status of switches and sensors (the commandArray variable) which makes it easy to interact.
In the scripts directory you will find a Lua directory. The Lua scripts are named "script_device_demo.lua" and "script_time_demo.lua". By copying these examples and changing demo into a sensible identifier like script_device_light2.lua the script will become active. Device scripts will be run at every device state-change and time-scripts will be run every minute.
Domoticz does not provide tools to access or edit these scripts but will execute them if they exist.
Continue with the info at Events in this Wiki.
Windows vs Linux
From here on down this HowTo specifically covers scripting for Domoticz on the Raspberry Pi and uses a Windows PC to get access to the Raspberry Pi.
Prepare your tools to get access
Get a copy of WinSCP here and PuTTY from here. WinSCP can be used to browse through the filesystem and contains an editor to edit the scripts. PuTTY, which can be launched from WinSCP, is a plain terminal where commands can be sent to the Linux Operating System. If you downloaded the Domoticz image the username will be "pi" and the password "raspberry". Both WinSCP and PuTTY will need these.
After launching WinSCP for the first time create a new Stored Session. Use File protocol "SCP", enter your Raspberry Pi's IP address in the Host name field, leave the port value at 22, enter username and password, and press Save, give it a sensible name like MyPi and check the Save Password checkbox. With MyPi selected click login.
In Options|Preferences|Integration|Applications provide the path to where you stored PuTTY.exe after installation.
Non-Lua Scripts
Bash scripts (and likewise Python, Perl) run 'outside' Domoticz and therefore have no 'internal' access to state of switches and sensors the way Lua scripts do. However, such state-information can be easily retrieved by calling the JSON API. Then again, it is easier to extend the possibilities of the non-Lua scripts by importing functions written by others.
The first line of the non-Lua script will identify the interpreter to be used, such as:
#!/usr/bin/bash
or
#!/usr/bin/perl
or
#!/usr/bin/python
Run as On- or Off switch action
You can run a perl, python, bash etc. script from the 'On Action:' or 'Off Action:' parameter of a switch. As an example:
script://coolscript.pl (or .py / .sh)
where coolscript.pl is a perl file in the /home/pi/domoticz/scripts folder
Be aware, however, that Domoticz will wait for this script to finish executing before it continues. This means that if there are any long loops with e.g. sleep statements in your script then your Domoticz event queue will be severely delayed. A simple way to get around this is to wrap the call to the perl/python script inside a bash script that uses the '&' notation to spawn off a subprocess to run the script and return immediately (with bash you can do this directly with " > /dev/null 2>&1 &" at the end of your call so there's no need for an intermediate bash script).
In your domoticz/scripts directory, create a file called exec.sh with the following content:
#! /bin/sh /usr/bin/perl /home/pi/domoticz/scripts/$1.pl $2 $3 > /dev/null 2>&1 &
or, for python
#! /bin/sh /usr/bin/python /home/pi/domoticz/scripts/$1.py $2 $3 > /dev/null 2>&1 &
Newly created bash scripts need to be executable. To make exec.sh executable type
sudo chmod +x exec.sh
You can now use the following syntax to call up the actual perl/python script as follows:
script://exec.sh coolscript
This way, control is immediately returned to Domoticz while your perl/python script coolscript runs in the background. It can still interact with Domoticz using JSON calls as per usual, it's just running quietly.
Remote script execution from within Domoticz
It's also possible to have the perl script execute on a remote machine in your network, with the execution kicked off from within Domoticz. This is done using ssh -i within that exec.sh bash pre-script, which is still in the /scripts directory on the local machine running Domoticz, but with the perl/python script now of course located on the remote machine (in the example here, in a directory called /home/pi/remotedir):
#! /bin/sh ssh -i ~/.ssh/privatekey 192.168.zzz.yyy /usr/bin/perl /home/pi/remotedir/$1.pl $2 $3 > /dev/null 2>&1 &
Here 192.168.zzz.yyy is the IP address of the remote machine that the perl script will actually run on, privatekey is the keyfile in the local ~/.ssh directory allowing ssh login to the remote machine without specifying a password, and remotedir is the directory your perl scripts are stored in on that remote machine.
If you haven't already set up ssh for non-interactive login on the target/remote machine, use the command ssh-keygen -t rsa to generate the two files with public/private keys and put the public key in the ~/.ssh directory on the target/remote machine and the private key in ~/.ssh on the local machine where Domoticz is running. You will also have to do a chmod 700 on the ~/.ssh directory itself and chmod 600 on the key files themselves or it won't work.
More on Bash scripts
Bash scripts are great to perform tasks which consist of a sequence of OS commands, like creating a backup of the Domoticz database and storing it at a safe location every night. Let's have a look at a Bash shell script. After the login WinSCP takes us to the Domoticz home directory /home/pi/domoticz. Move to the scripts directory. Here a number of general Bash shell scripts are included. Double click 'restart_domoticz' and an editor opens which shows this script's content:
#!/bin/sh
sudo service domoticz.sh stop
echo "please standby... (waiting 8 seconds)"
sleep 8
sudo service domoticz.sh start
Here you see (and can change!) the commands executed when the command 'restart_domoticz' would be typed at the command prompt.
Newly created bash scripts need to be executable. To make yourscript.sh executable type
sudo chmod +x yourscript.sh
and exectute it from the script's directory by
./yourscript.sh
More on Perl
The use of Perl is well documented on this wiki page - Perl for Domoticz. There are also numerous examples in the wiki on Logitech Media Server
Examples
Go to the Scripts page to see examples for Bash/python/perl scripts
crontab
In the example of the nightly-backup it would be nice if this could be automated. Linux has a scheduler for that: crontab. To configure this use PuTTY to get to the command prompt by clicking Ctrl-P in WinSCP. Log in with pi and raspberry. You now arrive in the /home/pi directory. Type "crontab -e" at the prompt and the nano editor will open with a file. All lines starting with # are comments and can be ignored. The lines with * and numbers define when to execute a command. This can be as often as once a minute or once a year at 10u42 on your day of birth. As an example this command
0 4 * * * sudo ~/domoticz/scripts/domoticz_backup.sh
will execute the domoticz_backup.sh script as a Super User (hence the sudo) daily at 04:00. More info on the cron possibilities can be found here.
Continue to the next page of the introduction