Configuration options with openHAB2

Hello everyone,
the topic was discussed in 2-3 threads on the side already but I still think there is some clarification needed.
With PaperUI we can discover things and these will be stored in a system-side database. I’m puzzled about the next step at this point.

Is the user supposed to manage all his items solely inside of PaperUI, a fresh and restrictive webapp?
Will there be any way to edit the items more directly in parallel to rules etc.? How are we able to manage items which are not discoverable (e.g. helper items)? What is the intended emergency strategy?

OH1 had the amazing key concept that all of the user-provided data got (defined and) stored in config files. Config files are clear and unambitious and can be backed up, versioned or mass-edited. They should be the corner stone of a nice graphical tool like PaperUI, not their predecessors.

Edit: After reconsideration, the important thing is not to restrict the user. Moving on from configuration files for items in favor of a more powerful system is acceptable under certain circumstances, please read my later comment about my opinion and ideas.

What are your thoughts, how do you think should the ideal setup look like?


There is absolutely no need to use PaperUI for managing your items/things.
If you have a look into openHAB2 conf folder, you will find subfolders called items, sitemaps and things, just like in openHAB1.

Every item discovered and showed through PaperUI can be definde in an .things config file. If you do so and watch PaperUI’s inbox, you will see the things disappearing, once you definded the in the .item file.

Therefore, every native openHAB2 Binding should contain a section in its documentary, how to define items on a textual basis.

As an example, have a look at the WeMo Binding:

Hey Hans-Jörg,
thanks for clarifying things.
Of course there is still a conf folder and yes you can still define files there as before. Restoring my OH1 config was the first thing I did after unpacking OH2. Eventually I even found the homematic OH2 readme on GitHub and was able to define a thing and a few items.

The actual problem I tried to describe is, that configuring OH2 is getting inconsistent. Elements added via PaperUI are only in the database and elements defined in a config file will be imported in the database, but not written back. In conclusion: config files are just a junk of the whole system and can be outdated by more recent changes in the database or via PaperUI.
Kai Kreuzer descussed this problem in a very informative way in a thread about backups (only found it now):

His argumentation totally makes sense. It seems the real problem is lack of a strong and feature rich UI (without wanting to insult anybody working towards that) and a lot of documentation carrying this vision and supporting users in the phase of transition.

Both problems combined create some serious trouble, have a look here for an example. That’s what happened to me more or less yesterday.
If there are configuration files, you expect them to be absolute. That’s what tech-savvy people know and like from systems like the linux /etc/ folder. Now on the other side, there is quite a lot of software storing it’s data (i.e. the openhab conf folder) in a database or other binary storage and making it accessible via GUI (one great example being GitLab). This has many benefits as Kai described in detail and of course can work and a GUI is the most feasible solution for the normal enduser.

@Kai’s vision is to switch over to a database driven storage. Following that idea everything should actually be done via GUI or Karaf console and the items, rules and sitemap folders should be abandoned right from the OH2 beginning. Things and items will be configured in the GUI and rules and sitemaps can be graphically or textually edited in an online editor. (The last two could stay file-only in the beginning) Solutions like this are actually out there: Habmin, Node-RED, IFTTT, Homematic-GUI, you name it. I chose OH1 because files are not the easiest solution, but the most powerful and open one. PaperUI will need to reach a whole different level of functional complexity to compete with that.

1 Like

No, I never said that and I still fully support them as I think for tech-savvy people it is the best option - for most things.
For the non-tech people, I think we have to provide a way to use openHAB without the need of such textual configuration files - and this is what the Paper UI and the database are about.

1 Like

Sorry if I cited you wrong there. What I got from the mentioned thread is that while configuration files for things and items are there for now, they should become obsolete in favor of the database at some point.
I want to cite you directly:

Here is my opinion on that: Talking only about items files for now, I was never a big fan of their structure. One line of item definition got quite long and you had a lot of repetition in them (due to the lack of “things”). To get some readability into the mess, most users build a table-like format into the file, the poor man’s database.

So, do I want my things and items in a configuration file? No, not ideally/necessarily.
Would I prefer a database? Yes, if it is still open for all needed modifications.

In your answer you are clearly distinguishing between people solely working with the configuration files and people working with the database through PaperUI. Furthermore you made clear, that PaperUI will never update the config files. There is a rift between the two user groups: people working with configuration files can not use the UI with all it’s nice supporting features (because it will not write back) and UI users can not do more special things, possible via config files (because there are no powerful interfaces). However I as a tech-savvy user do not want to exclude the PaperUI from my workflow and stay with a junky manually created file forever, I am looking for the mentioned “middle path”.

I want to vote towards the database approach in combination with what I and others mentioned before:

  • Thing/item discovery and adoption through PaperUI
  • Thing/item handling and modification though PaperUI
  • Increase of UI functionality over time
  • While there are not all functions available in PaperUI, mainly for the tech-savvy user:
  • Direct database access through some existing frontend like phpmyadmin (not offered for mapdb? mapdb alternative an option?)
  • More powerful options on the karaf console (random example: smarthome:items 5 rename 'Bathlight')
  • RAW-view edit through PaperUI (compare -> “RAW”)
  • Export and import of all relevant data from the database to a human-readable file format like xml (as a last resort)

My proposal supports three things:

  1. A clear transition from not-ideal items files to a more suited and system-managed database
  2. Providing the right tools to aid the tech-savvy users to adopt to the new system while not being restricted to a UI
  3. Motivate tech-savvy users to use AND contribute towards a powerful PaperUI

Can’t agree more. Single source of truth is great.

I am new to OpenHAB.
I spent a week trying to get one Phillips HUE bulb working with OpenHAB2. Haven’t got it working yet.
At this stage it looks like the only way to get OpenHAB2 working is to use manually written config files. And that’s what every OpenHAB2 success story tells.
And since there is no manual/best practice/recommended way of doing thing in OH2 everyone’s setup is all over the place.

OH2 is in Beta now. For me Beta means working product. Some bugs are there but it works.
Can we get a single switch working without manual file editing?

Yes, same here, I was hoping for something more finished product in terms of gui , but even though paper ui does seems nice, it simply does not function well and lacking options when it does, I am not really sure it serves any purpose except being a distraction.
Apparently i have to go back to all my oh1 config files to enable my setup ( quite basic setup - zwave,mysensors,milight and sbmc ) none of which is actually configurable in the UI…

Please keep the option to do configuration in a format that is human readable and can be managed via version control. Having a GUI for non tech users is great but should not limit usage for tech users. I would hate if OH completely switched to a db only approach. Big trend in IT right now is “everything as code” from configuration to system management to deployment


Yes, we need to keep control and don’t have everything in binary files.


Can’t agree more, I can’t tell you how much I like being able to see and edit my configs with everything backed with git. Having only a db for configs would be a real show stopper for me.


This is an interesting thread for me. When I ventured over to OH2 a long time ago, I specifically ditched (with backups, of course) any config files that an OH2 native binding existed for. I did not do this because I don’t like flat files, or anything like that, but my thoughts were that for OH2 to truly be an evolution, then as a user I should not have to mess with config files. Most of the people here are tech heavy and can manage tweaking bindings, config files, or even the code OH2 runs on. We are the minority. These devices are appearing in everyone’s homes now, and very few people even realize it. A system that knows how to discover and organize these devices, present a common interface, and allow rules to be set up easily will win for the consumer. That system does not exist yet. Many are trying to do it, but most are hampered by funding, corporate direction, or other things that prevent it in whole or in part.

My view on this would be to support the central DB instead of shun it, but build the tools that allows one to actually tweak the DB itself. Doing so allows the tech folks to be able to back it up, tweak it, change it, break it and fix it again just as we have done with flat files. More importantly though, it allows OH2 to keep working towards the vision of truly being an open home automation bus whose value grows outside of just the tech community. Automatic device discovery is one example of empowering users across hundreds of different technology ecosystems. The central DB serves this purpose.

Hey, for everyone bullheaded towards configuration files: please keep in mind that when I opened this thread, I was not necessarily rooting for configuration files as the one true solution. In order to evolve into a great product for tech-savvy and normal consumers alike, a powerful GUI (with a flexible data structure behind it) is needed. However a lot of work is needed in order to provide all the tools, both for the consumer and the fiddler. For me (with some experience in requirements engineering and usability) the critical part of that path seems to be the provision of one or two mighty tools as soon as possible, in order to ease the adoption and enhancement process, instead of putting of the power users (which instead should be part of the process).
As you can read in my second posting, I already proposed some ideas on how that could be accomplished. Currently I am actually waiting for some comments on that.

I would be willing to take on some part of that work, but we would have to discuss the details and agree on a common goal.

I’m a bit sad that this thread is not receiving more attention, I was hoping for some feedback/insight/thought on this topic from the main developers. Judging by the comments here and in some other threads, the question of where and how the userdata is handled is of concern to a lot of people and would be worth some discussion.

I’m in fond of having all configuration paramaters stored in a database which can than easily be backuped. But indeed this requires a gui that allows all configurations done using the gui.

I successfully migrated my Nikobus bin ding to Openhab2 and still tens of bindings to do. A few questions I have regarding configuration:

  • Is there a way to adapt the default homepage with items defined in static files (ie Nikobus), thus doing a mix with PaperUI things and static files items?
  • I have a lot configured in PaperUI (10 bindings approximately) Is there a way to generate text file items from them so I could move to text file items/sitemaps only?
  • What is the recommended way to migrate all Openhab2 configurations from a test raspberry Pi to a production version one?
  • Just a remark: since I use Openhab 1 intensively from all over the world to control my home, authentication and https are a must before using Openhab2 in a production environment. I’m really looking forward to have the authentication possibility integrated!

Openhab2 beta3 is a great product with a lot of possibilities! Great work and big thanks to Kai and all other contributers!


Is there any more official progress with this?

I am a new user to OH2 and one of the biggest confusing things has been whether to use the many UIs available or the raw text files, there does not seem to be any official documentation covering this.

I created things in the UIs and then wondered why the text files were not updated…

But creating text files seems to be reflected in the UI…

No consistency.

My thought is, if you want to present both options to users, is that you must ensure changes in the UI are written back to text files otherwise it can get very confusing and indeed with me has caused lots of strange errors and issues.

Much has happened since the discussion here. Let’s summarize:

  • The connection between config files and the database is sorted out. In fact I’m at the verge of writing an documentation article on that:
  • The internal database is now based on jsondb. In comparison to the previously used mapdb it is far more flexible, can be touched with a text editor, part of a backup or even version controlled with e.g. git
  • The effect of configuration files was improved. Now you can expect configuration files to always take precedence as you would expect it from every other linux system
  • As expected from other Linux systems, settings done through a GUI are not written to /etc/openhab2 config files as these are user only files. Settings are however written to userdata (/var/lib/openhab2), feel free to check file contents there.
  • PaperUI evolved a lot over the last couple of months and is now a great tool to discover and manage things and items.
  • Only discomfort for me: It is currently not possible to transfer PaperUI generated things and items to .things and .items files. That would be great to utilize autodiscovery while still working with file based.

Nice work, the JSONDB in particular moved me from periodic tinkerer to motivated to construct a production platform.
My only problem now is having tinkered with the PaperUI, BasicUI and HABMin while still trying to get comfortable with the basics of the relationship of between entries in the various files, i might have to set it aside for a few days and re-start from the beginning.

I’ve actually stayed with a files only configuration for now and can recommend that approach to everyone.

You use zwave with text files? Have issues finding examples of .things. Any plans to be able to convert json to .things?

I’m not using zwave :wink: But yes, that’s exactly what I thought, jsondb to things/items files. Shouldn’t be that hard to implement ***