Setting up openHAB2 from scratch



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

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 ( There you can always download the latest successfully built snapshot via this URL:

Do that now:

curl -O

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:
(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 script already has execute permisisons. If that isn’t the case: “chmod ug+x”)

cd /opt/openhab/current

This starts up openHAB2, your console should look like this:

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.


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:


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 :slight_smile: )

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

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

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


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


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

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 :slight_smile: ).

Rules are defined in the conf/rules directory. So we create the file default.rules there.


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"
  Item FragglesMobile changed from OFF to ON
  sendCommand(Wallplug, ON)

rule "Wallplug OFF"
  Item FragglesMobile changed from ON to OFF
  sendCommand(Wallplug, OFF)

The rule syntax in this example is very easy:

    rule "rule name (should be unique for logging purposes)"
        <TRIGGER CONDITION1> or 
        <TRIGGER_CONDITION2> or 

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

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

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:

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 (

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

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

# issue a commit even if the state did not change (optional, defaults to 'false')

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! :slight_smile:

Now you’re set up for persistence! Enjoy! if you want to know more about advanced persistence configuration, have a look here:



Hey Christian,
let me say this right away, even though you are still updating the article: Amazing work! :tada: 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 would love to move your tutorial as fast as possible over to the official documentation. The first part about a manual (cent os) installation can be integrated here and the rest can become the instant replacement of the Getting Started Tutorial. What do you think?

Again thanks for this great contribution :wink:

1 Like

Hi Thom, thanks a lot for your appreciation :slight_smile:

Of course, I would love to see this tutorial helping as many people as possible! What do you propose, should I finish the tutorial first? Or do you want to already copy over the main part and I’ll continue in the meantime?


I’ll second @ThomDietrich’s kudos. Well done!

Hi Thom, I think the main tutorial is finished now. I’ll add a part about persistence when I find the time, but feel free to use it for the official documentation right away! :slight_smile:

Regards, Christian

Hi Christian, that’s great to hear! I’d like to transfer the tutorial before the release of openHAB 2.0 GA/final on the 22nd of January (next weekend!). The ideal solution would be for you to create the needed Pull Request over at GitHub:
Do you have experience working with GitHub or other git project management systems? I could do the transfer for you but I believe it would be wiser if you did the needed adjustments, breaking it down to multiple pages (if desired) and so on. What do you think?

Could you check the Demo Setup, the Beginner tutorial and the currently hidden Advanced tutorial for content you might want to take over?

All the best, Thomas

Hi Thomas, no problem! I’ve got lots of experience with Git. I’ll have a
look tonight or maybe tomorrow!


1 Like

Really well done!
Maybe one thing is missing: the installation of the correct Java version. I don’t know which version is installed on CenOS 6 but openHAB has certain requirements (especially when you want to connect to the openHAB cloud) regarding the JDK version.


As if you were reading my mind :smiley: I’ve just created an issue on that topic:

For the tutorial I would actually propose to leave out the installation instructions completely and link to the “Installation” section of the docs.

@DocFraggle Related to that, please be sure to link other parts of as often as possible. We shouldn’t duplicate content and users should be shown how to learn more about details, if desired.

Ah, I forgot that, you’re right :slight_smile: I always use the Oracle JDK, so I’ll integrate that as well.

Hi Thomas, as a first step I updated the beginners tutorial. More to follow soon :slight_smile:


First no-guesswork, complete noob approach to understanding what the hell to do to REALLY get started in OpenHAB that I see… I had installed, created Items and Sitemap, but was still wondering how in the holy name of buddha did all come together… kept accessing the default sitemap… thanks, you brought me back from the brink of uninstallation…

1 Like

Many thanks! The step 5 to 7 is really what I was missing. Now I will give OH2 a second chance.

@DocFraggle: I’m really looking forward to the persistance description. May I propose to use rrd4 as example?

edit, just saw that the tutorial is already updated, removed obsolete comments

I was just reading your comments when you removed them ^^

The tutorial is now available here:

The fact that the tutorial is now updated does not mean that it is final. If you have any comments, feel free to give them here or in this ticket:

Hi Desh,

I will definitely write something about persistence, unfortunately I don’t have the time these days.

I myself use the mapdb persistence, as rrd4j supports storing numbers only:

@DocFraggle, thanks so much for putting this together it’s definitely explained a few things to someone who’s been sticking to what he knew with OH 1.x.

Again, something on persistence would be perfect! The PaperUI let’s me install the rrd4 option and even set it as the default but I’m not grasping how to setup the rest, I’m guessing it all has to be done in config files somewhere still?

Take a look under the directory …\conf\services\ for a file called rrd4.cfg

Okay… but I’m not finding much instruction on what to put in that file?

This is what would have been in my old “rrd4j.persist” file on OH 1.x…

// persistence strategies have a name and a definition and are referred to in the "Items" section
Strategies {
	// for rrd charts, we need a cron strategy
	everyMinute : "0 * * * * ?"

Items {
	// rrd4 database are good for short term storage so we store AllItems mainly for the restoreOnStartup feature.
	AllItems* : strategy = everyChange, everyMinute, restoreOnStartup

Thought I may as well try just copy my rrdj4.persist file from my OH1.x system… No luck though :slight_smile:

2017-01-26 15:10:32.645 [ERROR] [.eclipse.smarthome.model.persistence] - [org.eclipse.smarthome.model.persistence.manager(79)] The unsetModelRepository method has thrown an exception

Configuration and use of persistence in OH 2 is almost identical to how it worked in OH 1. The only differences are:

  • instead of putting configuration parameters for the persistence (e.g. URLs, logins, etc) into openhab.cfg one uses a separate config file (e.g. rrd4j.cfg).
  • setting the default persistence engine is done through PaperUI or in runtime.cfg

.persist files and calls in the rules are all identical to what you are used to. If you have made no customizations to the rrd4j configs in your openhab.cfg, you can ignore rrd4j.cfg.

What about the Strategies and Items we used to define in the old .persistence files?