OpenHAB 2 beginners / n00b guide?


I’ve just installed OpenHab2 Beta stream (online) on my Raspberry Pi 2 but I’m really struggling where to begin thereafter. Is there any easy user documentation showing some SIMPLE examples step by step? I searched for hours now, but found only bits and pices. Most of it quite detailed, leading to more questions, instead of solving the initial ones (e.g. “you need to add this …to karaf file” - where do I find this file).

The concepts I understand and used for my OpenHAB 1 test and found some very usefull beginner guides, but nothing like that for OpenHAB 2.

Have you seen the OH2 documentation page? Still a work in progress but helpful.

OH2 Documentation

If you are already familiar with openHAB1 you should read

Basically all your items, rules, sitemaps etc. work the same in openHAB2.

Hi, thanks for the quick replies. It helped a bit, but what is anoying, that with paper ui the configuration is stored in a data base (first I did set-up a sitemap as in OH1, etc. but it did not show up). This is just not clearly mentioned in OH2 documentation - how should a beginner know this? Do not get me wrong: I think this is the right way to do it in the end, but how can I set up my home there? Is there some kind of youtube video showing this, or for habmin2?

I have the feeling that you all worked with that al long time and have now a lot of knowledge and just used to how things work. The documentation is more or less for guys like you, for a beginner it is not very useful I have to say. The OH2 documentation just stops when it gets interesting.

Hmmm, did you read ?
It’s a quick start guide and works right out of the box.

Apologies, but I am stymied also, despite reading the documentation! I followed the instructions to setup openhab2 for linux (I use an rpi3) with apt-get. The web interface (Paper UI etc) did come up, and I did find the configuration in /etc/openhab2.

But where is the rest of the files, e.g. the log?
I found /var/lib/openhab2/log, but this folder is empty.
How do I get a “Karaf” console?

sudo su -s /bin/bash -c ‘/opt/openhab2/’ openhab
does not work, since apt-get does not install openhab2 into /opt.

Suggestions are most appreciated!

Hi @Bernhard_Boser,

The /var/log/openhab2 folder should contain the openhab.log file (based on an apt-get installation).

To get a Karaf Console, check this section of the docs:

For more advanced logging options, check: & Taming openHAB 2 Logging


Many thanks, this got me a lot farther! I can read the log, the demo is up etc.

Now I want to edit the configuration and ran into an issue with permissions. I’ve downloaded the openHAB designer on my Mac (openHAB itself runs on an rpi), and mounted /etc/openhab2 from the rpi on the Mac using Samba.

Problem: since openhab owns /etc/openhab2 but is not a “real user” - I don’t know how to setup write permissions on the Mac. Even on the rpi I can edit the configuration only with sudo.

What’s the best way to edit the openHAB configuration?

A few things that tripped me up here.

Whenever you make a new .items, .rules, .sitemap, .persist file you need to change ownership. On the Pi use

sudo chown -hR openhab:openhab /etc/openhab2
sudo chown -hR openhab:openhab /usr/share/openhab2

Also, not sure if the same as Mac as on Windows, in Designer when you load the files, make sure you load the mounted drive (My Computer) and not the shared folder (Network). When you make a new file on the Pi, you’ll need to reload Designer again before you see them.


User “openhab” is a “real user” in linux on the RPi (the username is listed in the /etc/passwd file).

If you would like (not really necessary):
You can modify his shell (from /bin/false to /bin/bash in the /etc/passwd file)
set the password by issuing the password command: sudo passwd openhab.
Then, you can use this user to login: su - openhab (or to ssh directly to the system using the openhab user).

This will not affect the openhab2 installation.

You could use the openhab username in your Samba configuration permissions and on the way that you mount the samba share in your Mac to allow read/write access to the files and directories that the openhab user owns. I won’t go into the details of how you configure the Samba shares. I assume that you can handle this :slight_smile:

Personally, I edit my openhab config files using text editing tools (vim, nano, etc) as root under a bash shell.

I login to my RPi3 system using ssh using the pi username, switch to root (sudo su) and do all my edits etc in the /etc/openhab2 configuration folders.


By the way, since you are using OH2, make sure that you work with the Eclipse SmartHome Designer (download it from here:

Read more here:

This is a great starting point with some good tutorials

Hi Dimitris & Matt,

Thanks for the suggestions.
After fighting with samba permissions, I switched to netatalk and added /etc/openhab2 to /etc/netatalk/AppleVolumes.default.

Now I can edit the configuration on the Mac with Eclipse SmartHome Designer.


1 Like

Stuck again …

I successfully installed the z-wave binding from the UI (at least the binding shows up in the UI now).

To configure it, I follow the instructions at which ask to edit the file

  openhab.cfg file (in the folder '${openhab_home}/configurations')

I cannot find openhab.cfg anywhere on my setup.

Those are for openHAB1, you are using openHAB2, install habmin2 through addons.cfg or via PaperUI and follow the instructions for openHAB2:

I now have zWave working, albeit unreliably (sometimes values update, but only e.g. going to a different page on the sitemap breaks this). Perhaps I am specifying items incorrectly, like so (I test with an Aeon powerstrip):

Number denPower1  "Den Strip Power 1 [%.1f W]" <energy>  { channel = "zwave:device:157cc1f584a:node3:meter_watts1" }

Elsewhere I have seen definitions like

Number  MB_SmartStrip_pwr1 "Strip A Current Usage [%.2f W]" { zwave="21:1:command=METER,meter_scale=E_W,refresh_interval=60" }

I tried playing with the 21:1 in the above command (e.g. 3:1) but got no results.

This is how I installed wave:

  1. Installed z-wave binding from paper UI
  2. created zwave.cfg with port
  3. paired z-wave devices with Aeon stick, while stick was not inserted into the rpi (per instructions that came with the Aeon stick).
  4. added the z-wave devices at “things” in the paper UI.
  5. created items with “channels” from info displayed in the paper UI.

Did I again miss the right documentation?

No, looks fine (if the channel name as been copied from habmin or PaperUI)

Only needed vor zwave binding version 1, not needed for zwave binding version 2 (if I remember correctly. At least it does not state that step in the openHAB2 docs)

No, looks all great up to now. I would have added the devices trough habmin instead through the stick directly, you will definitely need habmin when using zwave devices with openHAB.

Do you have battery devices or also some main powered devices? If all of them are battery powered sometimes the network needs to settle a while before everything works.
If that is not the case after lets say 24 hours of continuous operation you should switch openHAB to debug mode and post the log here to see whats going on.

Have fun.

Thanks for your response and patience!

  1. The z-wave device I am testing with is an Aeon multi-outlet strip, wired, and close (~ 1 meter) to the controller. So I should not have communication issues (though with z-wave everything is possible).

  2. How do I start openhab in debug mode? My installation is on a rpi, sudo service stop does not work. I did find /usr/share/openhab2/, but how do I stop it first? Won’t I get 2 instances if I start when it’s already running (it does start on boot). Related: how do I restart openhab? So far I’ve rebooted, but that’s a bit crummy.

  3. “you will definitely need habmin when using zwave devices with openHAB” - really and why? I thought I could do everything with configuration files (/etc/openhab2/items, sitemap, etc)? Related: where does habmin store configuration information? Apparently not in /etc/openhab2. (I prefer file based configuration, with gui’s I can often not remember how I did something before if I got it working once).

Many thanks!

Not with my experience: I have mixed devices, battery and mains, and all is working perfectly. Although I did not yet migrate my zwave to openHAB2, still using it with openHAB1.

It’s all in the docs: :grinning:

No need to stop, just restart openHAB
Answer to your next question in advance: How do I restart openHAB2? Again, it’s in the docs:
sudo systemctl restart openhab2.service

That’s also the way to start and stop openHAB (exchange restart with start or stop)

If you want to change the configuration of your zwave devices it’s the easiest way:

Note that this is a screenshot from openHAB1, but habmin in openHAB2 works the same way …

Thanks to the pointers on restarting openhab and configuring the log!

Good to know! I currently use an ISY. There z-wave (locks and lights) is also working fine, but to get there I had to carry the ISY next to all locks (big pain, as not all of them are close to an ethernet plug). I plan to switch in the hopes that openhab is more flexible.

Regarding habmin - I’ve used it so far to load add ons and find the zwave channels. Perhaps I’ll warm up to other parts of the GUI, but usually I find configuration files easier to deal with.

BTW: I found that zwave=… in the item definitions does not work (at least I have not found a case where it does); the channel notation sometimes does, but still not for all channels of my DSC11 multi outlet strip. The weird channel names that go into channel=… I get from habmin or Paper UI.

Incidentally - when should I use habmin and when Paper UI?

And finally (and not super critically right now, but still puzzling): how are Number items display in the sitemap?

E.g. at, the example

Number    MyTemperature  "Temperature [%.1f] °C"          { someBinding:somevalue }

does not work for me as expected. After replacing the binding with a working channel, I find I need to (1) put the °C inside the [] bracket, and (2), the text Temperature is usually ignored and replaced with something else. For example, I declare my power strip with

Number denStripEnergy "Strip Energy [%.1f kWh]"  	<energy>    { channel = "zwave:device:157cc1f584a:node3:meter_kwh" }

and in the sitemap file

Text item=denStripEnergy

What’s displayed on the website is this

    Electric meter (kWh) entire strip 0.4 kWh