Scripting in Domoticz
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 contributed scripts and more details on using specific scripting languages with Domoticz, 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, 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.
In Domoticz two kinds of scripts are commonly used: Lua scripts and Bash shell scripts. 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.
Domoticz supports two different mechanisms for user-developed Lua scripts. Either or both can be used depending upon what you are trying to achieve.
Users that are finding Blockly too restrictive and want to extend Domoticz using Lua (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 (& 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 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.
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.
Bash scripts (and likewise Python, Perl) know nothing about the state of switches and sensors. This info needs to be 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:
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 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 &
You can now use the following syntax to call up the actual perl/python script as follows:
This way, control is immediately returned to Domoticz while your perl/python script runs in the background. It can still interact with Domoticz using JSON calls as per usual, it's just running quietly.
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
More on Perl
The use of Perl is well documented on this wiki page - Perl for Domoticz.
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.