Getting started when knowing nothing

I’ve just discovered OpenHAB, and have installed v2 on my Synology NAS, and it works fine.

I’ve discovered the hardware (wemo link & bulbs) on my network using PaperUI, and they’re presented to me in Basic & Classic UI.

However, I’d like something more fancy, similar to the demo sitemap. I can load the demo sitemap but it doesn’t have my things there. What do I do now? I have no idea.

Am I just meant to edit the conf/demo.[type] files, to have my things, items, etc within them, or can I create a sitemap with a new name (but then how does that know which things, items, etc, file(s) that needs to work with)?

Welocme Neil :slight_smile:

Maybe you might want to have a look at as a starting point.

thanks, but been there and done that, and it’s not a subject that’s covered in the docs. These are the sorts of issues I’ve been having. :wink:

Do I create a duplicate set of files from the demo conf files, with the same name for all, or should I work with the demo files?

For the first steps I recommend to work in the demo files. Later on you can split the files (e.g. I have files for spcific topics/technologies like sonos, weather, …).

Thanks, but I asked a question, that presumably there’s an answer for…?

I’d like to understand what’s what, and as the config is the central user part, surely someone is able to tell me how the naming/loading of the config files works so that they properly interact with each other?

Sitemaps are the same as in openHAB1. You can find the documentation in the Wiki.


It’s not a simple question. OH2 is different to OH1 so what I say doesn’t necessarily apply, nor should you take it as gospel.

You should use/tinker with the demo files to figure out how the conf folder contents interact.

Inside the items files you create the items that can appear on your sitemap. Look at the wiki under each different binding to determine what items you can create to work with the respective binding. The items files can be amalgamated into one file if you like, but having them separate is significantly easier to manage. eg. heating.items, sensor.items, and so on. This is where the majority of the work goes at the beginning.

Bindings are installed through PaperUI (mostly) and allow the items files you’ve made to talk to the physical items (wemo, hue, daikin etc etc).

Rules, scripts, persistence, sevices are as per the wiki. Read about them, there. This is the majority of the work once you have your items set up and you want to start automating your physical connected gadgets.

Things are supplementary to the items files and seem to primarily exist to (sometimes) integrate with the PaperUI configured items. Not all items will need a thing though. I’m still learning the specifics of OH1/2 so don’t ask me more here or i’ll have to go learn it first…

For most people OH is not a pick-up-and-get-it-figured-out-in-an-evening kind of project. If you hunt around the forums you’ll find some other configurations files which are far more advanced than the demo, but helped me determine some less well documented features. I started with OH with next to no experience with Linux OS’s (I now have OH setup on a Pi3 with Raspbian) And very little experience with any meaningful code aside from basics of arduino. I’m now 9 months in, and more proficient with those aspects than I ever thought I would be.

1 Like

I fully agree; as sad as it is; it is a drag for any newcomer to make sense of the inner workings. I call it a monster, because it does not rally follow the usual procedural or object-oriented programming approach. It took me many days to get my head around it – just to get started…
But then, like the Doctors say: everybody is different; you may pick it up in day… however, no matter who you are I don’t think so.
What I also need to say: Once you’ve got it all working, it is very powerful, and does things, no other system is capable of. – Why I am still tinkering with it… to the point that I either use OH, or no home automation at all.

Good luck :slight_smile:

Hello Neil,

Best thing to start, as mentioned by Joerg and Paul, is tio use the demo files and add the items of your choice. To see the items within the sitemap you have also to specify them within the sitemap.

If you are on the advanced way, you can split things to more files to have your project more structured (files with many hundred lines of code aren’t clearly).
These files can be named as you like it. And there is no link between any file by ist name. Items in a file “zwave.items” can be used in a file “rollershutter.rules”.
Openhab reads all files at Startup. That means, after startup all items defined in all your items files are loaded an processed. The same for the rules files: all rules files are loaded and processed.
A Problem, which occured under OH1 (I am not using OH2) is, that you cannot guarantee the order of loading the files. In some cases a rule is processed, but not all items needed by your rule are yet loaded.

Give it a try. Play with some items / bindings and get more used to OH.


Thanks Andreas, and to the others for the more comprehensive answers.

Hey Neil,
as I understood it you already have OH2 up and running and you got all your things and items defined by adding them in PaperUI. Good so far :wink:

I would recommend to start off with an empty configuration folder (addons.cfg: package = standard). You should still hold on to the demo files and possibly have a lookout for other configuration examples. Here you can find my configuration.

Start out with a small sitemap called default.sitemap. Follow the instructions in the wiki on how to build a sitemap.
You should quickly see some nice results in BasicUI/ClassicUI or in your smartphone app.

If you are not sure about names and datatypes of your items, the karaf console is your friend. Use the commands smarthome:things and smarthome:items to get more information about all registered things and items.

Additionally it’s a good idea to look into the events.log file to get a better understanding of which data is stored in which item at certain events. On Linux do the following (path may differ):
tail -n 100 -f /opt/openhab2/userdata/logs/events.log

After you got the basics of your sitemap content covered, you might want to think about “transformations”, “persistence”, helper items (to display summarized information or similar) or rules… Check out the very good wiki and docs articles on these topics (most information in the openHAB1 wiki is still valid for openHAB2). My recommendation is to have one sitemap but many small configuration files for rules and such. Have a look at my config for examples in the items or rules folders.

You might also want to work with more bindings. Be sure to read up on them in the documentation (either in the new or if needed in the old wiki) - in the beginning restrict yourself to OH2 bindings with an existing docs article if possible.

If you run into problems with things and items added via PaperUI, you may want to define all of them in config files. I found peace in that as it bears a few positive side effects. You will however need some time to do so (example).

Good luck!


Thank you Thom.

I finally feel like I’m making progress, and now have a nice sitemap with all of my items in the right place, and working as I’d expect them to be.

And thanks for the links. Rules is where I’m going next. :slight_smile: