Using Python plugins

From Domoticz
Jump to: navigation, search

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 or above installed:

  • Optional: some plugins require beta versions for newer features if so, upgrade to the beta version
  • install python3 runtime
    • you may need to install python3 development libraries for now - see this issue thread
  • restart your Domoticz service
  • check your logs

Installing Python for Windows

PythonInstallImage.jpg


Installing Python on Raspberry Pi with Raspbian (should work on any Debian system)

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

Some users believe that Domoticz Beta versions since V3.6129 require Python3-dev. Unconfirmed, only install if you are having issues:

 sudo apt install python3-dev

Update to the latest beta version

 cd ~/domoticz
 ./updatebeta

Restart the service

 sudo systemctl restart domoticz.service

Now check the logs to make sure there are no errors.

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.
  • 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:
  • Restart the Domoticz service (or reboot the entire server)
  • In the Domoticz interface, navigate to the hardware page. There you should now find the plugin name in the device types dropdown list.

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, if you run Linux, we have to make the plugin.py file executable. Let's enter the directory and issue the command:

 cd SVT
 chmod +x 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.

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 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