From Domoticz
Jump to: navigation, search


Support for the standard GPIO is available in Domoticz.

What is GPIO?

IT stands for "general purpose input output". Many small computers like the Raspberry Pi nowadays have a double row of pins that you can control. You can listen to input on them, or you can send signals to other devices.

- Not all of the pins can be controlled. Any standard Raspberry Pi features 17 digital In/Out (or even 21 on revision 2 boards) that can now be managed by Domoticz.

- The pins can only handle on-off signals. Meaning "on" (3.3v) or "off" (0v)

- You can damage your pi if you put a 5v input on one of these pins. You could buy a PiFace board, which has the advantage of giving a bit of protection to the inputs and of conveniently packing the relays and solderless terminal blocks on a clean board. This is also supported in Domoticz.

- GPIO pin numbers are different from the physical pin number. For example, physical pin 11 is PGIO pin 16. This can be confusing.

- GPIO pins have to be 'exported' by a root user if you want them to be accessible to non-root users. This is done by calling specialized commands which we will get into.

Two options

Domoticz currently supports two ways of accessing the pins:

1. The CLASSIC way is to install a driver, like WiringPi or PiGPIO.
2. A newer way is to use SYSFS GPIO. This is a standardised way of connecting to pins that is used on a lot of devices, and can be used without a driver. It is the prefered method.

This page explains how you can use both.

Option 1 - SYSFS

SysFS exposes the pins as if they were files on your harddrive. by writing to these files you can send signals. By reading the files you can listen to signals.

You don't have to install any additional software for SYSFS to work. But you will have to setup the pins for your use.

Using to GPIO map here RPI GPIO Maps choose the desired I/O

Example :

    1. Find which GPIO pin you want to use. Figure out the GPIO number of the physical pin by looking at the maps here : RPI GPIO Maps
    2. Export the GPIO pin (number 4 in this example) by calling this command:
    3.  echo 4 > /sys/class/gpio/export  
    4. Decide if the pin should be input or output:
    5.  echo out > /sys/class/gpio/gpio4/direction  
    6. You can manually set the output pins on or off using this command. One is on, zero is off.
    7.  echo 1 > /sys/class/gpio/gpio4/value
       echo 0 > /sys/class/gpio/gpio4/value
      TIP: You have to give these commands every time you start linux, so it's smart to add these commands to a file like /etc/rc.local which gets called when the Pi boots. ("sudo nano /etc/rc.local"), or to the file which gets called every time Domoticz starts.
    8. set the interrupt if needed choice : rising / falling / both / none
    9.  echo none > /sys/class/gpio/gpio4/edge
    10. Now, go to Domoticz' hardware page and install the Generic SYSFS GPIO hardware.
    11. select auto configure device, the exported GPIO will appread in the device section ;-)
      1. first way : Go to the "switches page" and add a new manual switch.
        Select SYSFS as the option in the type dropdown.
        You can set a unique number for the pin inside domoticz using the many dropdowns here. You can try just keeping them all at 0 for your first ever pin.
        The SYSFS dropdown should show the pin you exported earlier. Select it.
      2. second way : Go to "Device"
        all exported GPIO are listed here

Enjoy ;-)

Option 2 - CLASSIC

The classis way of using GPIO pins in Domoticz requires you to

1. Install a driver
2. Export the pins.


  • The GPIO driver is based on the wiringPi library by Gordon Henderson. Install it like so;
 sudo apt-get install wiringPi

and test the installation with;

 gpio readall

If that doesn't work; try this this procedure

GPIO pins

First, you need to get familiar with the GPIO pins and select which pins are suitable for the goal you want to achieve. I could not explain it better than Gordon, so please refer to those two pages: general considerations and special pin functions. Then you can select which pins you are going to use and configure them.


Before starting Domoticz

The pins you intend to use must be made available to unpriviledged processes (as Domoticz should not run with root priviledges). To do so, you need to run a few commands before starting Domoticz. Note that their effect is not permanent, so they should be performed upon each boot before Domoticz starts. Probably the best place is in /etc/rc.local or in the script. The commands are as follows: (Note: the <BCM PIN #> below refers to the corresponding column on this page)

For outputs

gpio export <BCM PIN #> out


gpio export 17 out

For inputs

gpio export <BCM PIN #> in
gpio edge <BCM PIN #> both


gpio export 18 in
gpio edge 18 both


Once it's done, you can check the configuration with the following command:

gpio exports

This should return something like:

GPIO Pins exported:
  17: out  0  none
  18: in   0  both

Configure at startup

Because the command is not permanently, you likely want to configure the GPIO settings at startup automatically.
You can do so by adding the lines you would like to use to the 'rc.local'.
Type: sudo nano /etc/init.d/ to edit the file Go to the end of the file, and just add after ':' place your commands.
In my case the /etc/init.d/ looks like this:

#! /bin/sh
# Provides:          domoticz
# Required-Start:    $network $remote_fs $syslog
# Required-Stop:     $network $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Home Automation System
# Description:       This daemon will start the Domoticz Home Automation System

# Do NOT "set -e"

DESC="Domoticz Home Automation System"
#DAEMON_ARGS="-daemon -www 8080 -sslwww 443 -log /tmp/domoticz.txt"
#DAEMON_ARGS="-daemon -www 8080 -sslwww 443 -syslog"
DAEMON_ARGS="-daemon -www 8080 -sslwww 443"

# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0

# Load the VERBOSE setting and other rcS variables
. /lib/init/

# Define LSB log_* functions.
# Depend on lsb-base (>= 3.2-14) to ensure that this file is present
# and status_of_proc is working.
. /lib/lsb/init-functions

# Function that starts the daemon/service
        # Return
        #   0 if daemon has been started
        #   1 if daemon was already running
        #   2 if daemon could not be started
        start-stop-daemon --chuid $USERNAME --start --quiet --pidfile $PIDFILE $
                || return 1
        start-stop-daemon --start --quiet --pidfile $PIDFILE --exec $DAEMON -- \
                $DAEMON_ARGS \
                || return 2

# Function that stops the daemon/service
        # Return
        #   0 if daemon has been stopped
        #   1 if daemon was already stopped
        #   2 if daemon could not be stopped
        #   other if a failure occurred
        start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDF$
        [ "$RETVAL" = 2 ] && return 2
        # Wait for children to finish too if this is a daemon that forks
        # and if the daemon is only ever run from this initscript.
        # If the above conditions are not satisfied then add some other code
        # that waits for the process to drop all resources that could be
        # needed by services started subsequently.  A last resort is to
        # sleep for some time.
        start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 --exec $D$
        [ "$?" = 2 ] && return 2
        # Many daemons don't delete their pidfiles when they exit.
        rm -f $PIDFILE
        return "$RETVAL"

case "$1" in
        [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"
        case "$?" in
                0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
                2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"
        case "$?" in
                0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
                2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        status_of_proc "$DAEMON" "$NAME" && exit 0 || exit $?
        log_daemon_msg "Restarting $DESC" "$NAME"
        case "$?" in
                case "$?" in
                        0) log_end_msg 0 ;;
                        1) log_end_msg 1 ;; # Old process is still running
                        *) log_end_msg 1 ;; # Failed to start
                # Failed to stop
                log_end_msg 1
        echo "Usage: $SCRIPTNAME {start|stop|status|restart}" >&2
        exit 3

#Run export GPIO Raspberry

/usr/bin/gpio export 17 out
/usr/bin/gpio export 27 in
/usr/bin/gpio edge 27 both
/usr/bin/gpio export 22 in
/usr/bin/gpio edge 22 both

Active low relays

If you are using a relay board, some of them are active low. This means that writing a 0 will turn the relay on instead of off, so in Domoticz you will see the light bulb off instead of on and vice versa. To solve this we have to add this line at the end of /etc/init.d/ (after the exports)

sudo sh -c "echo '1' >> /sys/class/gpio/gpio17/active_low"

Copy this for all the relay outputs, and change the bcm pin number (17 in the example) for the pin you are actually using.

Now issue a reboot (sudo shutdown -r now)

Inside Domoticz

You need first to declare the GPIO port in Domoticz. To do so, go to the "Hardware" tab, type in a name like "GPIO Port" and select "Raspberry's GPIO Port" as type, then click add.
Next, go to the "Switches" tab, and for each GPIO pin, click "Manual Light/Switch" and proceed as follows:

For outputs

Select the GPIO port hardware you just configured, give it a name, select the "On/Off" switch type and a "GPIO" type. You can now select the pin in the list. Obviously, the ones you configured above should not start with the "! NON EXPORTED" mention. You can test the output if you like (the "Test" button will just set the output to HI), and then click "Add Device".

For inputs

Select the GPIO port hardware you just configured, give it a name, select the "Contact" switch type and a "GPIO" type. You can now select the pin in the list. Obviously, the ones you configured above should not start with the "! NON EXPORTED" mention. Then click "Add Device". The mention "open/closed" corresponds to a switch connected between the pin and the ground, with the pin also connected to a pull-up (as you have read on the wiringPi website, some GPIO have an internal permanent pull-up.


You should now be able to click on the light bulb to toggle the outputs, and you should see the contact status change when you connect the pin to GND or VCC.

Have fun!