---------------------------------------
---------------------------------------
THIS TUTORIAL IS NOW ONLINE AT http://docs.openhab.org/tutorials/beginner/index.html
---------------------------------------
---------------------------------------
Hello,
this is a tutorial about how to set up openHAB2 from scratch, starting up, adding some bindings, discovering and configuring things for the first time and finally creating a sitemap and some basic rules.
This tutorial is based on the snapshot Build #710 (Jan 9, 2017 4:56:47 PM), running on CentOS 6. There are some tutorials about how to set up openHAB2 via apt repository on different operating systems. You can follow these and return for step 3 
Step 1 - choosing a directory and downloading the latest snapshot
For my setup, I created the user “openhab”:
useradd openhab
and a designated directory
mkdir /opt/openhab
Give the user “openhab” the appropriate permisisons:
chown openhab. /opt/openhab
(the “.” means the user’s primary group).
Now switch to the user
su - openhab
and change the directory
cd /opt/openhab
Now download the latest snapshot release. Currently, the releases are build by Jenkins in the CloudBees network (https://openhab.ci.cloudbees.com/job/openHAB-Distribution/). There you can always download the latest successfully built snapshot via this URL: https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab/target/openhab-2.0.0-SNAPSHOT.tar.gz
Do that now:
curl -O https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab/target/openhab-2.0.0-SNAPSHOT.tar.gz
For update reasons I always create a folder containing the current date in it’s name and extract the archive there:
mkdir openhab_`date +%F`
tar xvzf openhab-2.0.0-SNAPSHOT.tar.gz -C openhab_`date +%F` && rm -f openhab-2.0.0-SNAPSHOT.tar.gz
This will extract the archive to the previously created directory (i.e. “openhab_2017-01-11”), and delete the archive after successful extraction.
Because I’m using a lot of scripts, of course I don’t want to always change the path after a snapshot update, so I create a soft-link for the current release. This also makes updates much easier and gives you the possibility to revert to an older snapshot in the blink of an eye if something’s wrong with the latest release by simply switching back the link to the old release.
Creating the link for the first time:
ln -s openhab_`date +%F` current
This is what it looks afterwards:
ls -la
lrwxrwxrwx 1 openhab openhab 18 Jan 11 19:28 current -> openhab_2017-01-11
drwxrwxr-x 6 openhab openhab 4096 Jan 11 19:19 openhab_2017-01-11
If you want to update your openHAB2 application, you have to remove the link first and recreate it:
ls -la
lrwxrwxrwx 1 openhab openhab 18 Jan 09 18:49 current -> openhab_2017-01-09
drwxrwxr-x 6 openhab openhab 4096 Jan 09 18:46 openhab_2017-01-09
drwxrwxr-x 6 openhab openhab 4096 Jan 11 19:19 openhab_2017-01-11
unlink current
ln -s openhab_`date +%F` current
ls -la
lrwxrwxrwx 1 openhab openhab 18 Jan 11 19:21 current -> openhab_2017-01-11
drwxrwxr-x 6 openhab openhab 4096 Jan 09 18:46 openhab_2017-01-09
drwxrwxr-x 6 openhab openhab 4096 Jan 11 19:19 openhab_2017-01-11
This way you don’t lose your old release files.
Step 2 - Installing the Oracle Java Development Kit (JDK)
CentOS comes with it’s own JDK, the OpenJDK. In order to meet the openHAB 2 requirements, we’re going to install the latest Oracle JDK.
You can find the binary distribution (RPM) here:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
(this is the current link as of 16th of January 2017. It may differ in the future!)
After you click the “Accept license agreement” radio button, you’re able to download the latest RPM version.
Note: you have to chose the version (x86/x64) depending on your CentOS installation. As of CentOS7, there is only a x64 version available.
As soon as you downloaded the file onto your CentOS system, install it via yum:
yum localinstall jdk-8u112-linux-x64.rpm
You could of course install it via rpm, but this way the yum database of installed packages keeps up to date.
The package will be installed to the /usr/java/jdk1.8.0_112 directory, and the installer will create a symlink /usr/java/latest pointing to the latest Oracle JDK.
To actually use the Oracle JDK automatically, you have to add some environment variables in you /etc/bashrc file to be loaded when you log into your system. So use your editor of choice to edit the /etc/bashrc file and add these lines to the end of the file:
export JAVA_HOME=/usr/java/latest
export PATH=/usr/java/latest/bin:$PATH
I suggest logging out and in again in order to load the environment variables before continuing.
Step 3 - starting up openHAB2
Now that everything’s ready we can start up openHAB2 for the first time:
(Normally the start.sh script already has execute permisisons. If that isn’t the case: “chmod ug+x start.sh”)
cd /opt/openhab/current
./start.sh
This starts up openHAB2, your console should look like this:
>./start.sh
Launching the openHAB runtime...
__ _____ ____
____ ____ ___ ____ / / / / | / __ )
/ __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __ |
/ /_/ / /_/ / __/ / / / __ / ___ |/ /_/ /
\____/ .___/\___/_/ /_/_/ /_/_/ |_/_____/
/_/ 2.0.0-SNAPSHOT
Build #710
Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown openHAB.
openhab>
This is the so called Karaf console You can have a look at the logs with this command:
openhab> log:tail
19:42:41.927 [INFO ] [.dashboard.internal.DashboardService] - Started dashboard at /start
Step 4 - first time setup
When you start openHAB2 for the first time, it only starts the dashboard (as you can see in the log entry above). So let’s have a look at it: open a browser and browse to you openHAB2 dashboard:
http://IP-of-your-machine:8080
As you can see, you can choose between different options. For starters, I recommend the “Standard” package. This will install the “Paper UI” (here you can install add-ons, discover and configure things etc), the “Basic UI” (here you can have a look at your created sitemaps - I’ll get back to this later), and the Habpanel (here you can create dynamic dashboards for your things). After clicking in “Standard”, openHAB2 will install the packages and afterwards take you to the start page.
Step 5 - configuring openHAB2 and installing add-ons
Click on the “PAPER UI” link and you will be taken to the “INBOX”. The INBOX is the place where you can discover/add new “things” (i.e. Zwave devices, Hue lamps, network devices and so on).
In order to be able to add new things, at first we must install the corresponding binding for that type of thing.
I.e. if you want to control your Zwave devices, you have to install the Zwave binding. If you want to control your Hue lamps, you have to install the Hue binding etc.
The installation is done on the “Add-ons” page in the left menu.
You can scroll down and have a look at lots of bindings available for openHAB2!
In this tutorial I will use the Zwave, Network and Astro binding as an example (I just don’t use other bindings currently )
Let’s start with the “Network Binding”, as this binding can be used in every setup from the start and will show you the basic configuration possibilities. With the network binding, you can define some of your network devices as things in order to use them in a rule for example, or just to see if they are online or offline and for how long.
Scroll down or use the “Search” field to find the “Network Binding”. Click on install, the binding will be downloaded and installed automatically.
Now that the binding is installed, switch back to the “Inbox”. If you click the “+”-button, you now are able to choose the binding which you want to use for discovering new things. Because we only installed the network binding so far, it’s the only binding to choose.
As soon as you click on “Network Binding”, the binding will start an automatic discovery of all (reachable) network devices in the same subnet as your openHAB2 installation resides in via ICMP (ping).
The discovered “things” are now displayed in the inbox, and you can decide what to do next:
- add the device as a thing by clicking the check icon
- ignore the device by clicking the crossed-out-eye icon
- delete the device by clicking the trashcan icon
The difference between ignoring and deleting discovered things is as follows:
- if you ignore a thing, it disappears from the visible inbox. If you decide to add it at a later time, you can do so by scrolling to the bottom of the inbox and click the “SHOW IGNORED” button.
- if you delete the thing, it won’t be visible in the inbox any more. But if you start a new discovery process later, the thing will reappear
In this example, I click on the check icon of the thing with the IP address 192.168.1.103. Let’s assume this is my mobile phone, so I change the (automatically added during the discovery) name of the thing on the next page to “Fraggles mobile” and click on the “ADD AS THING” button.
Before we proceed, I propose to change one of the default system settings of openHAB2 to ease up the following processes. You will see why in a moment.
Go to “Configuration → System” via the menu on the left. Here you can find the basic system properties of your openHAB2 installation. Scroll down to “Item linking”, activate the “Simple Mode” slider and click the “SAVE” button which appears afterwards. You will notice afterwards that the “Items” menu item will be gone
Now back to your recently added thing. Go to the “Configuration → Things” page, there you will find your network device thing, including the name “Fraggles mobile” which we defined above.
You can already see the status, “ONLINE”, of the thing, so it’s currently reachable by openHAB2. If you click on the name, you’ll get to the next page showing the available channels of the thing. Channels represent the different functions the items provide. In this case you can see two channels: “Online” and “Time”, the description below it says it all
What is very important: the channels are not “linked” after the thing discovery. Linking means to create an openHAB2 “item” which represents the state of a channel of a thing. Because we activated the “Simple Mode” before, this can be done automatically by clicking the corresponding radio button left to the channel. Otherwise you have to define the name of the item yourself.
So we’ll link both channels of the “Fraggles mobile” thing now by clicking the radio buttons.
For most of the bindings each thing can be configured further by clicking the pen-icon. There you can edit the name again, chose a location (this is important for the “Control” menu item later) and, of course, change binding realted options. With the network binding for example, you can also change the IP address, the timeout, the refresh interval etc.
You can save changed values by clicking the check icon at the top.
Now that we linked the two channels in the previous step, we can have a look at the “Control” menu item at the top left. On the “Control” page you can see all your linked items. So far we added only one thing (“Fraggles mobile”) and linked it’s two channels, so that’s all we see:
Items which are linked to channels of the same thing are displayed together, represented by the thing’s name. Here you can see the state of the “Online” and the “Time” channel. My mobile is online, and the ping time is 11ms. As you can see in the screenshot with the configuration parameters of the thing above, the refresh interval is set to 60000ms by default. This means that openHAB pings the device every 60 seconds. If you want to set a lower value there, feel free.
These are the basics to configure openHAB2 via Paper UI, meaning that the process is pretty much the same with other bindings.
To demonstrate that, I’ll proceed and install the Zwave binding in order to add my Zwave things to openHAB2. The installation is just like the example with the network binding above, so I’ll skip this here and go directly to the “Inbox”.
There, I click the “+” icon again and can now choose between the “Network Binding” and the “Zwave Binding”.
The difference to the network binding is, that I have to configure the Zwave controller first. So I’m taken directly to the Zwave controller config page after clicking on the"Zwave Binding" link. here I configure the port and basic settings and click the check icon afterwards.
openHAB2 immediately starts discovering my Zwave things via the Zwave controller and shows them in the inbox.
In my case, I already included all the devices, so this may differ from a complete fresh installation where you didn’t include any device yet. Pleas understand that I don’t want to ex- and include all my devices for this tutorial 
Just today I bought a new wallplug and included it, so I know it’s “Node 30”. For a simple sitemap and rule example I’ll configure this thing now:
So basically I gave the thing a name and linked the “Switch” channel. Now I can see the wallplug (and the Zwave controller) on the “Control” page, too. It’s switch is currently turned off:
If you activate the slider of the wallplug, it will start routing power You first action with openHAB2!
Step 6 - Creating a sitemap for Basic UI
Controlling your things via Paper UI is nice, but currently you can sort them only by editing the “Location” in the thing configuration. If you want to create your own view you can use a so called “sitemap” which can be displayed in the Basic UI (you remember, it was automatically installed at the beginning).
But before that, you have to create an items file. Both the items and the sitemap file are edited in your editor of choice. The file location is as follows (the openHAB2 root directory is /opt/openhab/current in my example and may of course differ from your installation!):
/opt/openhab/current/conf/items <-- *.items files
/opt/openhab/current/conf/sitemaps <-- *.sitemap files
After a fresh installation these directories are empty (except for the readme files), so you have to create a file there. I’ll use “default.items” as the items file and “default.sitemap” as the sitemap file in this tutorial. So I created the files:
/opt/openhab/current/conf/items/default.items
/opt/openhab/current/conf/sitemaps/default.sitemap
Let’s start small.
Open the default.items file and define your first item:
Switch FragglesMobile "Fraggles mobile" <network> { channel="network:device:192_168_1_103:online" }
The syntax is as follows:
ItemType ItemName "ItemDescription" <ItemIcon> { ItemToThingChannelLink }
You can find an overview of the different item types here: Explanation of items · openhab/openhab1-addons Wiki · GitHub
In this example I use “Switch” as the item’s type. This results in a slider which is either turned on or turned off.
Important: the item’s name has to be unique!
Feel free to choose an appropriate description for your item.
The available icons can bee seen here: smarthome/extensions/ui/iconset/org.eclipse.smarthome.ui.iconset.classic/icons at master · eclipse-archived/smarthome · GitHub
If you click one one of them in GitHub you can see what it’s looking like.
Now to the item-to-thing-channel link: the channel id is always visible in Paper UI when you edit a thing. As you can see in the screenshot from above where I linked the two channels of the network thing, I used the channel id of the “Online” channel in the definition above:
network:device:192_168_1_103:online
Again, for most of the bindings this is the way of adding an item in the .items file:
browse to your Paper UI, go to “Configuration → Things”, click on the thing you want to add, find the channel of the thing you want to add, copy the channel id and use it in your .items file
To see the status of my wallplug, I have to add it to default.items too. First I look for the channel id in Paper UI:
Then I add the item to default.items, this is what it looks like afterwards:
Switch FragglesMobile "Fraggles mobile" <network> { channel="network:device:192_168_1_103:online" }
Switch Wallplug "My wallplug" <poweroutlet> { channel="zwave:device:bb4d2b80:node30:switch_binary" }
This means that I’ll get a slider for the wallplug, indicating if it’s turned on or off, with the poweroutlet icon.
To be able to actually see it in the “Basic UI” we have to create a sitemap. The sitemap basically defines the layout of the UI page. The syntax is quite easy, here is a simple setup of the previously created default.sitemap file:
sitemap default label="My first sitemap"
{
Switch item=FragglesMobile label="Fraggles mobile"
Switch item=Wallplug label="My wallplug"
}
A sitemap file always starts with “sitemap”, followed by the sitemap’s internal name (if your sitemap file is “default.sitemap”, the sitemap name has to be “default”! Otherwise openHAB2 will complain in the log). The “label” is the title of the sitemap, it’s shown in your browser’s titlebar/tab and on the sitemap page itself.
Next comes the block with the actual items you want to show on your sitemap. Here you can see the two items I added to the default.items file earlier.
The syntax is again pretty straight:
ItemType item=ItemName label="Description of the item shown on the webpage"
where ItemType and ItemName must be the same as defined in default.items
One last thing to do is setting the default sitemap for the “Basic UI” via “Paper UI”. Browse to “Configuration → Services” in Paper UI and click the “Configure” button of Paper UI
Now set the default sitemap to “default”, which is the sitemap name we defined earlier in default.sitemap and click the “SAVE” button.
To finally see the result, browse to the initial openHAB2 start page (http://IP-of-your-machine:8080) and click on the “Basic UI” link
Enjoy your first sitemap
Step 7 - a simple rule
Now that we have the two items - “Fraggles mobile” and “My wallplug” - we can create a simple rule.
Let’s assume you want to turn on the wallplug (and give some juice to the potentially connected lamp) as soon as your mobile comes online, turn it off again when the mobile went offline (this would be a very basic “presence” rule ).
Rules are defined in the conf/rules directory. So we create the file default.rules there.
/opt/openhab/current/conf/rules/default.rules
You can create as many .rules files as you want - this eases the overview of different rules/situations. For example:
- presence.rules for the presence detection
- alarm.rules for your alarm actions
- tv.rules for rules specific for your SmartTV
- and so on
The same principle applies to .items and .sitemap files as well!
For now, we edit the default.rules
rule "Wallplug ON"
when
Item FragglesMobile changed from OFF to ON
then
sendCommand(Wallplug, ON)
end
rule "Wallplug OFF"
when
Item FragglesMobile changed from ON to OFF
then
sendCommand(Wallplug, OFF)
end
The rule syntax in this example is very easy:
rule "rule name (should be unique for logging purposes)"
when
<TRIGGER CONDITION1> or
<TRIGGER_CONDITION2> or
<TRIGGER_CONDITION3>
...
then
<EXECUTION_BLOCK>
end
The trigger conditions can be one of the following:
- Item triggers - just like in the example above. If the state of an item changes, do something
- Time triggers - do something at a specified time
- System triggers - do something after a system event happened, i.e. openHAB2 was started or is shut down
The execution block in the example only consists of the “sendCommand” command, which sets the state of the named item.
sendCommand(ItemName, STATE)
If you want to know more about rules, see some sample rules and further examples, have a look at
Rules · openhab/openhab1-addons Wiki · GitHub
Samples Rules · openhab/openhab1-addons Wiki · GitHub
or browse this forum!
Back to the two rules we just created: once the mobile comes online, the wallplug will turn on, As soon as it goes offline, it will turn off. Just as simple as that
Step 8 - Persistence
Let’s assume that we didn’t activate the above rules and you have to control the wallplug manually. You can turn it on or off.
If you restart openHAB, the system has to determine the current state of the wallplug, but this process can take some time. Some devices have a defined wakeup cycle every 7200 seconds (like many battery powered devices to save energy), network devices have to be pinged to get their online state, and so on.
This is where the persistence comes into play. The persistence service will store the current states of your items and restores the values upon starting up openHAB.
There are many different persistence services. you can find them all on the openHAB documentation site: http://docs.openhab.org/addons/persistence.html
There are database persistence services available for the most common databases. If you have an up and running MySQL database, you could use the MySQL persistence service. The main benefit of database persistence services are that they store the state values for as long as you like, so you could use them for creating availability reports.
If you just want to restore the state values after restarting openHAB, you can use file based persistence services like rrd4j or mapdb.
I started with the rrd4j persistence and always wondered why the states of my door contacts weren’t restored after startup, until I found the explanation on the wiki site (rrd4j Persistence · openhab/openhab1-addons Wiki · GitHub):
NOTE: rrd4j is for storing numbers only. Attempting to use rrd4j to store complex datatypes (eg. for restore-on-startup) will not work.
So I switched to the mapdb persistence. It creates a simple key-value store on your drive and you don’t need to set up a database with all it’s overhead
Now for the installation: go to the “Add-Ons” page, switch to the “Persistence” tab and install the “MapDB Persistence”.
Now, set the MapDB Persistence as the default persistence service in your system configuration (you have to click the SAVE button to the right afterwards!:
Next, you have to configure the two config files needed for the persistence service:
conf/services/mapdb.cfg - the main service configuration file
# the commit interval in seconds (optional, default to '5')
commitinterval=5
# issue a commit even if the state did not change (optional, defaults to 'false')
commitsamestate=true
conf/persistence/mapdb.persist - in this file you define the settings of your persistence (file has to be created!)
// persistence strategies have a name and a definition and are referred to in the "Items" section
Strategies {
// if no strategy is specified for an item entry below, the default list will be used
everyMinute : "0 * * * * ?"
every5Minutes : "0 */5 * * * ?"
everyHour : "0 0 * * * ?"
everyDay : "0 0 0 * * ?"
default = everyChange
}
/*
* Each line in this section defines for which item(s) which strategy(ies) should be applied.
* You can list single items, use "*" for all items or "groupitem*" for all members of a group
* item (excl. the group item itself).
*/
Items {
// persist all items on every change and every minute and restore them from the db at startup
* : strategy = everyChange, everyMinute, restoreOnStartup
}
The different strategies follow the Quartz scheduler syntax, the default is saving the value with every change of the item’s state.
In the “Items” definition you can assign different strategies to different item groups. I just don’t care and store the values on every change, every minute and - the most important setting of all - restore the values during startup!
Now you’re set up for persistence! Enjoy! if you want to know more about advanced persistence configuration, have a look here: Persistence · openhab/openhab1-addons Wiki · GitHub
TO BE CONTINUED!
This looks like a great and thoroughly thought through tutorial. I was planning to write something similar before the openHAB 2.0 final release but was already afraid to not make it in time.
I’ve just created an issue on that topic: 