Using Python plugins

Overview

Plugins are great! Since the ability to create Python plugins was added to Domoticz, it has seen an explosion of plugins.

- Check this list of plugins that have already been developed and where to find them. Brand new plugins are also shared on the forum.
- Would you like to create your own plugin? This page will get you started developing plugins to extend the functionality of Domoticz.

Required: install Python

If you want to use plugins you must have Python 3.4 until 3.9 installed. 3.10 is still under test but seems to work.

• Check menu Setup - About Domoticz if Python is already recognized on your system.
• install python3 runtime (see sections below) if needed (preinstalled on a lot of Linux distro's)
  • you may need to install python3 development libraries for now
• restart your Domoticz service or complete system
• check your logs about Python installation or check menu Setup - About Domoticz. python version should be shown.

Installing Python on Linux Debian (eg Raspberry Pi with Raspbian)

Key point: Your version of Linux will come with a default version of Python3, if it is above 3.4 then use it. You can ignore python2.7 if it is already installed, it will be ignored.

Domoticz actually uses a package called libpython and this can cause some confusion. Just because python3 works does not mean libpython is on your system.

Check you do actually have a version of Python3, it will tell you if it is installed already:

 sudo apt install python3

Check the version:

 python3 -V

Make sure that you have libpython installed, it needs to match the version you have. If you have Python 3.4.x then you make sure you have libpython3.4, if you have Python 3.5.x then you make sure you have libpython3.5 and so on. Use this command to check:

 dpkg --get-selections | grep libpython

If it is not there then use (where 'x' is the version from above: e,g libpython3.4 or libpython3.5 etc):

 sudo apt install libpython3.x

If you still do not see the python version in Domoticz menu Setup - About Domoticz please install python3-dev:

 sudo apt install python3-dev

Restart Domoticz.

Python plugins are supported in the current Domoticz stable version.

Installing Python for Windows

• If you are using the precompiled x86 version of Domoticz from https://www.domoticz.com/downloads/ , install the 32 bit Python version even if your Windows is 64 bit.
• Currently Python 3.7 to 3.11 is supported. Python 3.12 still under test (but seems to work).
• Do not install Python 3.8.0 as this will stop the plugin framework. Install 3.8.1 or higher!

Installing a plugin

Generally installing a plugin takes a few steps:

• Download the plugin and copy its folder into the domoticz/plugins directory. Each plugin at the very least consists of a plugin.py file. Downloading is normally done with a git clone command from the plugin repository.

NOTE: On Windows the domoticz/plugins directory has to be created manually. It is not created by the installation script.

• Give the plugin.py file execute permissions. Right click on the file to change its permissions, or use the terminal to navigate to the directory, and then type: sudo Chmod +x plugin.py
• Restart the Domoticz service (or reboot the entire server)
• In the Domoticz interface, navigate to the hardware page, menu Setup - Hardware. There you should now find the plugin name in the device types dropdown list for adding new hardware gateways.

Optionally, you may have to install extra software like drivers. Check the plugin documentation to find out.

Example for Raspberry Pi with Raspbian

Let's run through an example installation.

A lot of plugins store their code on Github, a website made for this purpose. If you run Domoticz on a Linux system, install Git to easily download the plugins through the terminal:

 sudo apt-get update
 sudo apt-get install git

Next, navigate to the plugin directory, and install the plugin straight from Github. In the documentation of most plugins you'll find the Git link you an use. Here we install the Smart Virtual Thermostat in a folder called 'SVT':

 cd domoticz/plugins
 git clone https://github.com/999LV/SmartVirtualThermostat.git SVT

So in this case the directory structure should now be: domoticz/plugins/SVT/plugin.py

Next, we restart Domoticz so that it will find the plugin:

 sudo systemctl restart domoticz.service

From here the plugin should be able to be set-up from the Domoticz interface. Go to the hardware page and look in the dropdown. Note: the plugin and directory name are often different.

If you run Linux and the plugin does not show up in the hardware list, you may have to make the plugin.py file executable. Let's enter the directory and issue the command:

 cd SmartVirtualThermostat
 chmod +x plugin.py

Restart Domoticz and it should now show up.

Troubleshooting

• check the log via the web interface (Setup / Log)
• you should see

PluginSystem: Started, Python version '3.x.y'

• if there is no mention at all of plugins
  • Check Setup > Settings > Other (tab) > EventSystem(LUA/Blockly/Scripts) > Enabled is ticked
  • check have set up plugins (see above)
• if you see

PluginSystem: Failed dynamic library load

• • have you installed the pyhton3 development libraries
  • check article [1]

To find which version is active (3.4 or 3.5), type this command:

 python3 -V

If you wamt to change versions, try something like this:

 sudo apt-get install python3.4 libpython3.4 python3.4-dev

Next, set 3.4 as the main version to use. You can change it back later if you want.

 update-alternatives --install /usr/bin/python python3 /usr/bin/python3.5 1
 update-alternatives --install /usr/bin/python python3 /usr/bin/python3.4 2

Now you can switch between them by issueing this command, and selecting your preference:

 update-alternatives --config python3

More details on telling linux which version of Python to use: https://linuxconfig.org/how-to-change-from-default-to-alternative-python-version-on-debian-linux

Installing Modules fails

In newer Linux OS's Python is defaulting to virtual python environments (venv). This can result in error message "error: externally-managed-environment" when installing Python modules with pip or pip3 The dirty way is to add --break-system-packages at the end of the pip3 install module or requirements command line.

For example

sudo pip3 install -r requirements.txt --break-system-packages

Importing Modules fails

If a module is not found the Plugin Framework will provide as much information as it gets from Python. For example, an attempt to import fakemodule in a plugin called 'Google Devices' will be reported like this in the Domoticz log:

 2019-03-23 17:17:44.483  Error: (GoogleDevs) failed to load 'plugin.py', Python Path used was '/home/domoticz/plugins/Domoticz-Google-Plugin/:/usr/lib/python36.zip:/usr/lib/python3.6:/usr/lib/python3.6:/usr/lib/python3.6/lib-dynload:/usr/local/lib/python3.6/dist-packages:/usr/lib/python3/dist-packages:/usr/lib/python3.6/dist-packages'.
 2019-03-23 17:17:44.483  Error: (Google Devices) Module Import failed, exception: 'ModuleNotFoundError'
 2019-03-23 17:17:44.483  Error: (Google Devices) Module Import failed: ' Name: fakemodule'
 2019-03-23 17:17:44.483  Error: (Google Devices) Error Line details not available.

The framework shows the directories it searches. Broadly these are: the plugin directory, the existing Python path as picked up when Domoticz started and the 'site' directories for system level modules installed with pip3. Local 'site' directories are not searched by defaul although plugin developers can add any directory the like to the path inside the plugin.

Pip3 installs packages in system directories when sudo is used on linux platforms. So if Importing fails try to install library with sudo pip3 "python module"

For Windows use python -m pip install "python module"