OpenHab 2: GPIO Binding

GPIO Binding


Product Links:

Hey guys Matt here from and in this video I am going to show you how to use the OpenHAB 2 GPIO Binding.
The GPIO Binding allows us to interact with the onboard gpio pins of the raspberry pi. When I say interact I mean be able to turn the GPIO pins on and off as well as read the status of the input on a GPIO pin.
First up let's go over the parts I am going to use to demonstrate the GPIO binding. I am going to use a white LED, 5 volt 4 Channel relay board, Momentary button and a door sensor. For tools we are just going to need female dupont jumper cables. The links to all the materials, tools and parts are over on my website, the link is in the description.
To make this guide easier I am going to be using my testing raspberry pi running a fresh installation of openhabian. I have a complete guide on my channel showing how to install and setup openhabian. The raspberry pi is sitting in a clear plastic enclosure with a built in fan which is cooling the heat sinks I have installed. I have a kit for the raspberry pi on my shop over at
Now take the components and connect them to the raspberry pi using the female dupont jumper cables and according to this picture. If you have any questions on the wiring ask it down in the comments below and I will try to answer it. Here is a clip of my wiring.
Next we have to setup the GPIO binding. I will not be doing two separate videos for mac and PC because the only difference is the software used to SSH, on mac you use terminal and on windows you use PUTTY.
1. To install the binding go to your openhab web user interface and click on paper ui.
2. Then go to add-ons. After that click on bindings and in the search type in GPIO and install the one that says GPIO binding.
3. If you want to configure some other settings for the GPIO binding you can go to the configuration tab and then the bindings sub tab.
4. After that you can click the configure button in the GPIO binding.
Personally I didn’t touch any of the settings. The binding is installed, now let’s use it.
5. SSH into the raspberry pi using the program based on your operating system.
I recommend having my website open so you can just copy and paste commands. For this guide, I am going to assume that you have an item's file and a sitemap file. If you do not, then check out my video where I cover the configuration files.
6. Anyway the first thing we are going to do is create the items in the items file.
7. Type in sudo nano /etc/openhab2/items/home.items and press enter.
You may need to type in the sudo password.
8. Now type in:
Switch LED "LED" { gpio="pin:21" }
Switch channel1 "Channel 1" { gpio="pin:26 activelow:yes initialValue:high" }
Switch channel2 "Channel 2" { gpio="pin:19 activelow:yes initialValue:low" }
Switch channel3 "Channel 3" { gpio="pin:13 activelow:yes"}
Switch channel4 "Channel 4" { gpio="pin:6 activelow:no"}
Contact DoorSensor "Door Sensor [%s]" { gpio="pin:16 debounce:10 activelow:yes" }
Contact Button "Button [%s]" { gpio="pin:24 activelow:yes" }
What we did is create the items that control as well as read the status of the various things we connected. Let me explain what each item does and what each part means. The first item is the one that controls the LED. The first part is the item type and since this will turn the LED ON and OFF we will use the switch type. The next part is the item name and I just called it LED. After that is the label text and this is what shows up in the user interface, again I just wrote LED. The next part after that is the binding config. I assigned this item to GPIO 21 because that is where I plugged in on the raspberry pi. The next set of items are for the relay board and since it is a 4 channel board I created 4 items. Each item is almost the same except for the binding config. I am going to show you a couple different ways you can configure this binding, but for this relay board the item config you should be using for every channel is the one on channel 1. The first part of the binding config is the pin to connect to and for this one is pin 26, the next part is activelow which is set to yes. Active low means that when the switch is off there will be no voltage applied to the gpio pin and when the switch is on there will be voltage applied. After that is initialValue and what this does is tell openhab what to set the initial value of the item during initialization. This one is set to high because I want the switch to be off during initialization. The next item is channel 2 and for this one I set activelow to yes and initialValue to low. So, this one will be like channel 1 except during initialization the switch will be on during initialization. The binding config for channel 3 and 4 are a littile bit different because they do not have the initialValue so instead they will use the default value of high. Also these two items have different values in activelow. You will be able to see how the different items work later when I show you a demo of everything working.
Next up is the gpio pins that act as inputs. First is the door sensor and since the door sensor has two states open and closed we will use contact for the item type. For the label text I just wrote Door Sensor and format of the input as %s. In the binding config I mapped it to GPIO pin 16, and set debounce to 10. Debounce means the time it waits before reading the input on a pin in milliseconds. After that is again activelow and this is set to yes because the way the button works is it applies voltage which trip the pin high. The button item is basically the same except it does not have a debounce parameter in the binding config.
9. That is it for the items file, now press control x, then y and enter to save.
10. Now we are going to put the items into the sitemap file so type in sudo nano /etc/openhab2/sitemaps/home.sitemap and press enter.
11. Then paste the following into a bracket:
       Switch item=LED
       Switch item=channel1
       Switch item=channel2
       Switch item=channel3
       Switch item=channel4
       Text item=Button
       Text item=DoorSensor
And press enter.
All we did is import the items into the sitemap.
12. To save press control x then y and enter to save. Let’s test everything out.
Go to your web user interface and then basic ui, I am going to do it on a tablet. Before we play with the buttons lets take a look at the status of everything, The led is of and so is its switch, channel 1 is off so is its switch, channel 2 is on and so is its switch, chanel 3 is on and so is its switch, channel 4 is on but its switch is not on. Now lets look at the input devices, the button is not pressed and on the interface it says open, and the door sensor is closed and on the interface it is also closed.
Alright now let’s play with everything, when I turn the LED switch on the LED turns on. To determine whether a relay is On just look at the leds on the relay board. When I turn on channel 1 the channel 1 relay turns on, When I turn off the channel 2 switch the relay turns off, when I turn off channel 3 the relay turns off. But when I turn on channel 4 the relay turns off. Now let’s test out the input devices, when I press the button it goes to the closed state and when I separate the door sensor contacts it goes to the open state. That is it for the GPIO Binding!      
If you need any of the parts shown in the video you can buy a kit, the PCB or 3D printed parts to make this device as well as other devices at the link in the video description. Alright thank you for watching and If you have any questions leave them in the comments section below or head over to Good Bye!