GPIO Binding

Documentation of the GPIO binding bundle

Introduction

Binding for local GPIO subsystem, currently only this exposed to user space by Linux GPIO framework is implemented. Being based on kernel implementation it's hardware agnostic and works on different boards without modification (this is on theory only, not all existing boards can be tested). The difference from other bindings dealing with GPIOs is that it works with GPIO subsystem on the board on which openHAB runs and don't require third-party programs/daemons running. The binding consists of two components: base module (org.openhab.io.gpio) which implements low-level GPIO access and provides API for high-level modules (can be used by other bindings needing to interact directly with GPIOs) and the binding itself (org.openhab.binding.gpio) which introduces hardware GPIO pins as full feature openHAB items capable of generating events or receiving commands depending of their type (input or output).

Prerequisites

1. Linux-based OS with GPIO driver loaded (check whether exists directory /sys/class/gpio), usually it's compiled into the kernel for all recent boards which exposes GPIOs
2. Mounted sysfs pseudo file system, the mount point can be:

• Automatically determined if procfs is mounted under path /proc, this is the default path in almost all configurations
• Manually set in openHAB configuration file, key gpio:sysfs

3. Installed package for native JNA library, e.g. for debian-based OS use apt-get install libjna-java. If version 3.2.7 is used, then if the library isn't in system library path (which is true for most of the cases) you need to add a parameter in command line which starts openHAB and specify the path to JNA library, e.g. edit the last line in "start.sh" and append -Djna.boot.library.path=/usr/lib/jni right after java. If version 4 or upwards is used, the directory /usr/lib/jni won't exist, and it appears we need to do nothing (mine just worked) Since 1.9.0 jna-4.2.2.jar is used which contains the native libraries inside the jar. So no additional installs are needed. See https://github.com/java-native-access/jna for supported platforms
4. Root privileges, openHAB should be run under "root" account.
   Alternatively you can add the user "openhab" to the usergroup "gpio", if your distribution (like rasbian) does have such group.
   sudo adduser openhab gpio

NOTE: Some boards may need additional pin configuration prior using them, for example OMAP-based processors are using pin multiplexing which require changing the mode for some of the pins. Please refer to board's System Reference Manual for more information whether preliminary configuration is needed and how to do it.

Installation

Automatic installation using apt-repo:

apt-get install openhab-addon-binding-gpio

This will install all required modules.

Some manual configuration may be needed. The following edit to /etc/default/openhab may be necessary (see discussion above in Prerequisites section). If needed, set:

JAVA_ARGS=-Djna.boot.library.path=/usr/lib/jni

The JAVA_ARGS edit may not be necessary, and could cause OpenHAB to crash. If it does, simply undo the edit and restart OpenHAB.

If you chose above to add the openhab user to the gpio group, then you shouldn't make the changes below to run as root. If you did not add openhab to the gpio group, make a further edit to /etc/default/openhab:

USER_AND_GROUP=root:root

And then edit /usr/lib/systemd/system/openhab.service and set the following:

 User=root
 Group=root

Manual installation without using apt-repo:

Extract openhab-runtime archive to /opt/openhab (recommended) if not done yet, copy following JARs from openhab-addons archive to /opt/openhab/addons folder:

org.openhab.io.gpio
org.openhab.binding.gpio

Install native JNA library version 3.2.7, modify /opt/openhab/start.sh and append -Djna.boot.library.path=/usr/lib/jni right after java on the last line of the file as change /usr/lib/jni with the path to JNA library's parent directory.

Global Binding Configuration

gpio:sysfs - optional directory path where sysfs pseudo file system is mounted. If isn't specified it will be determined automatically (if procfs is mounted under /proc).
gpio:debounce - optional time interval in milliseconds in which pin interrupts for input pins will be ignored to prevent bounce effect seen mainly on buttons. Global option for all pins, can be customized per pin in item configuration. Default value if isn't specified - 0 (zero).

Examples:

gpio:sysfs=/sys
gpio:debounce=10

NOTE: While change in these global options is allowed at runtime it's not advisable to do that. This is because only newly created pins will use the new values while currently existing pins will use the old one.

NOTE: These options are optional, in most circumstances you don't have to specify them.

Item Binding Configuration

Allowed item types are Contact and Switch. Type Contact is used for input pins, Switch - for output pins. The configuration string is following:

gpio="pin:PIN_NUMBER [debounce:DEBOUNCE_INTERVAL] [activelow:yes|no] [force:yes|no]"

Key-value pairs are separated by space, their order isn't important. Character's case is also insignificant. Key-value pair pin is mandatory, debounce and activelow are optional. If omitted activelow is set to no, debounce - to global option in openHAB configuration file (gpio:debounce) or 0 (zero) if neither is specified. PIN_NUMBER is the number of the GPIO pin as seen by the kernel (not necessarily the same as the physical pin number). DEBOUNCE_INTERVAL is the time interval in milliseconds in which pin interrupts for input pins will be ignored to prevent bounce effect seen mainly on buttons. Note that underlying OS isn't real time nor the application is, so debounce implementation isn't something on which you can rely on 100%, you may need to experiment with this value. When activelow is set to no (or omitted) the pins behaves normally: output pins will be set high on ON command and low on OFF, input pins will generate OPEN event when they are high and CLOSED when are low. However, if activelow is set to yes the logic is inverted: when ON command is sent to output pin it will be set to low, on OFF command - to high. Input pins will generate OPEN event when they are low and CLOSED event on high. The "force" option can be used to forcefully get hold of the configured pin even if it is currently in use, so it automatically gets unexported and exported again.

Examples:

Switch LED "LED" { gpio="pin:1" }
Switch NormallyClosedRelay "Normally Closed Relay" { gpio="pin:2 activelow:yes" }
Contact NormallyOpenPushButton "Normally Open Push Button" { gpio="pin:3 debounce:10" }
Contact PIR "PIR" { gpio="pin:4 activelow:yes" }
Contact NormallyClosedPushButton "Normally Closed Push Button" { gpio="pin:5 debounce:10 activelow:yes" }
Contact ForcePin "Force access to pin" { gpio="pin:6 force:yes" }

automatic unexport when using init.d script

When using the init.d startup script from this wiki (link) and you try to stop openhab it will not unexport your gpio pins. You can do this manually or edit the startup script like bellow. First find the stop section: Look for the do_stop() function and insert your unexports:

Init.d script:

do_stop()
{
# 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 $PIDFILE $
#unexport all gpio's
echo 22 > /sys/class/gpio/unexport
echo 23 > /sys/class/gpio/unexport
echo 24 > /sys/class/gpio/unexport
echo 10 > /sys/class/gpio/unexport
echo 9 > /sys/class/gpio/unexport
echo 25 > /sys/class/gpio/unexport
echo 11 > /sys/class/gpio/unexport
echo 8 > /sys/class/gpio/unexport
RETVAL="$?"
[ "$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 $DAEMON
[ "$?" = 2 ] && return 2
# Many daemons don't delete their pidfiles when they exit.
rm -f $PIDFILE
return "$RETVAL"
}

Naturally edit the number after the echo to the gpio pin you use and insert or remove lines matchin the number off gpio's in use.

Now you can stop and start openhab without your GPIO pins getting blocked!