OpenHAB 2 beginners / n00b guide?

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

Same with me, BUT: you can’t change configuration parameters of your zwave devices with text files, you have to use an external program. And the best one - and only one which is integrated into openHAB - is Habmin.

Actually it is a kind of extended PaperUI with some additional features, mainly zwave features…

No, because that definition is for openHAB1, with openHAB2 you have to use “channel” definition.

That is correct, where did you find that other example? Hopefully not in the openHAB docs :grinning:

Your item and sitemap definition for denStripEnergy is correct, if something else is displayed take a look if you have channels linked to things. Look in PaperUI under “Configuration” “Things” or in Habmin under the same tab. There should be no channels linked to things. If yes I guess you did not set “Simple Mode” to off. If it is set to on (default) links and item are created automatically for things (and therefore for zwave).
See here:

Maybe what you see in your sitemap is something autocreated and not what you have configured through your text files.

I did find it in the openhab doc,, about 2/3rds down the page under heading “Formatting”. I just noticed a different example near the beginning (heading “Real life example”) that has the unit inside bracket.

This fixed it, thanks! Many options to figure out what they do …

Okay, changed it to the correct syntax.

Hi, so i have to hijack this thread and ask my questions as they are all beginners questions.

First of all, I’m quite familiar with OH1 and now switched to OH2 using the openhabian Image which is really a great starting point. I’ve read a lot of so called guides and tutorials but many questions remain unanswered.

So let’s begin:

  1. Is paperUI supposed to be the “single source of truth” regarding configuration? background: I’m trying to setup my own sitemap (as everyone else i think ;)) so I create item files. Do I have to create “thing”-files too, or is this obsolete when the “thing” is discovered in paperUI? It’s very bulky to switch between Smarthome Designer and paperUI.
  2. Where are items located that were created through paperUI? Is there any item-file or edit them just through paperUI?
  3. What am I doing wrong when I get 2 entries for the same item in events.log. This item (hu_sk_di_speiss) is configured in an item-file but will also output the cryptic item created by paperUI. See sample below.
2016-11-15 13:58:33.494 [ItemStateChangedEvent     ] - hu_sk_di_speiss changed from 0 to 100
2016-11-15 13:58:33.505 [ItemStateChangedEvent     ] - hue_0100_00178823bb93_11_brightness changed from 0 to 100

ok as I’m writing this I found out that i had a manually created item that was linked to the same thing. does this mean i have to unlink every channel that i don’t want to use, to not spam the events.log?

I have a lot of other questions, but let’s start with this…


at least with homegear, you don’t have to unlink the automated linked thing. just put your own definition in your item file and refer to the the thing created by OH2 by copiing the text bfrom the Thing:
configuration --> things --> yourThing

oh my, im glad i found this thread. I’ve been really struggling! I’ve found the docs a nightmare to work through, a muddled mixture of openHAB 1 and 2, sometimes no way of knowing which is which, trying things which clearly dont work, then not knowing if I’ve done something wrong or if its just for the wrong version. I still can’t get any binding to work properly.

I have no real knowledge of linux systems, and the amount of unexplained parts of various documents is amazing. I know its mainly people who are familiar with the basics who set this up, but is very difficult for a beginner. Its riddled with 'type this line, then type this line, then in the background, solve the grand unified theory, but obviously you know how to do that bit, then type this line, then everything works!

Sorry if this is a bit of a rant, hopefully i’ll get the measure of it and it’ll all seem easy once it works…


Then you should try:

if you are using a Raspberry.