openHAB 2.4: Confused about when to configure via UI vs Files

Hi there,

I’ve been learning openHAB for the last month or so and have successfully got my own ESP8266 hardware/software working with MQTT and the embedded broker as well as reflashing some Sonoff devices with Tasmota.

Most of this was done via PaperUI to start with and then I started experimenting with things and sitemap files to get something working in BasicUI. So far all good apart from some issues with the Sonoff state beiing uninitialised on starting openHAB.

What I am unsure about is whether I should be using PaperUI at all; should I remove everything and stick to config files? A lot of the examples note an MQTT bridge in the items file but my install is working well without it.

Thank you and looking forward to contributing as I learn.

openHAB 1 was file based and because of that history all examples are also file based.

But I’m already thinking to remove .items and .things file examples from all mqtt bindings as they suggest that file configuration is the preferred way. It’s not :slight_smile:

1 Like

OK that’s fine. But for now, we still need to keep using the files in some form because that’s what BasicUI needs, correct? I note I misread this response as “don’ use PaperUI” when what was meant was PaperUI will be replaced with something better.


I have been using openhab since V1 days so perhaps I am biased but it is up to you how you wish to work, but be aware that for Openhab 3 it is being discussed that the file based methods are going to be discontinued.

I use PaperUI to install and setup bindings and from then on I use file based for everything else (things,items,sitemap), mostly not because it is better, but because PaperUI is lacking abilities and hence it is slower to use. I also have other issues with paperUI, but dont have the time to spare to explain them when it would not be helpful…

As an example why I prefer it, I’ll propose a race which you can try to see which is faster and what you prefer… Try setting up 30 light globes with Paperui, all using the same binding with a few conditions. They will have no stupid random number names and will be named useful things like “HallLight” and have nice easy to remember and short strings. My guess is that by the time I have created all 30 lights with text files (which is as easy as cutting, pasting and minor editing), someone with PaperUI is probably still working on adding light number 2 or 3 and possibly can not create nice human friendly text in all fields.

Now say you run into trouble and need help here on the forum? Probably the first thing people will ask you to do is paste the contents of your item and thing files.

I really feel for new comers to Openhab right now. Why bother learning the ‘better’ method when it will soon be thrown in the bin? Getting confused by recommendations to use PaperUI when it too is going to get thrown in the bin!

I look forward to seeing what @David_Graeff creates as he is making a PaperUI replacement. Hopefully these things are at some stage added if they are possible…

  1. A spread sheet style page or something similar that allows all your things and items to be renamed and extra lines added with cut and paste ability. The ability to see at least everything that uses the same binding at the same time. Something to make the speed of adding multiple items with similar linkages much faster than what is currently possible. This is by far the biggest issue I have, that it is painfully slow compared to textual setup.

  2. A way to list everything in the database that is not fully linked correctly with the ability to delete all, or only some of them quickly. A cleanup function.

  3. A way to import/export for either sharing your setup with others or for asking for help. An example is setting up Kodi which has around 10 channels to link up. Currently it is as easy as cutting and pasting the example from the documentation and editing 1-2 lines and you are done in 30 seconds and have a fully working setup including a basic sitemap to play with and test. Perhaps it may be as simple as taking a screen shot to post on the forum if a feature like point 1 existed.

1 Like

Partly correct. You only need to create a sitemap file, the rest could be done with PaperUI if you wish. If you use Habpanel instead of BasicUI it is possible to do everything with a mouse without creating text files. But once again creating a sitemap and using BasicUI is at least 10 times faster once you have learnt it.

Habpanel creates great looking user interfaces.
BasicUI is exactly that basic looking but fast to create.

What you wish to do depends on your concept of a smart home. I prefer no UI as much as possible and for things to just happen magically based on triggers. BasicUI and google home voice control is more for things which are not yet at that ability, so I don’t care what the UI looks like as I hope to eliminate it at some stage.

As for rule files which is probably your next question, I believe it is possible to setup NodeRed and create rules graphically with drag and drop. Also there is the new generation rule engine which is experimental at the moment. Never used nodered but it may be worth checking it out as yes the rules language is also being discussed at being dropped for Openhab 3.

Hi @DavidT,

I wanted to give you my take on things. I’ve been using openHAB since about two years now. So since version 2.x. Which means I’m fairly late to the party.

With openHAB being so … “open” … :slight_smile: there cannot be one “true” way of doing things. I still want to tell you what I think is a good approach now(!) as we speak. Doesn’t mean that’s true and doesn’t mean there are better ways now or in the future. But I have had my share of good and bad experiences as a newcomer. You are asking the right questions because the UI vs. text files part is what’s most confusing. From experience advice like “you could do that or that” doesn’t help in the beginning. So I’m being black and white now, but on purpose.

Use Paper UI for binding and thing maintenance and forget about all other UIs

Paper UI is my only graphical admin interface for bindings and things. It is the most mature and I think it is safe to say that is the current de-facto standard. Use Paper UI to create all your things. I only create things textually in very rare cases. In most of those cases it is because I’m forced to declare the items manually because the (exotic or new) binding doesn’t support auto-discovery.

Forget about sitemaps

This might be very controversial. But I truly believe that sitemaps are an unnecessary extra effort. I experimented with those years ago because due to the way the documentation is written one gets the feeling that having a sitemap is mandatory. It is not. Sitemaps are the basis for all automated UIs like the iOS app. They are no doubt useful. But if you do not want to use any of those, you don’t need a sitemap. Give your items english IDs and meaningful display names in your native language. Use groups extensively to order them.

Use HABPanel as your primary UI

HABPanel is an incredibly useful, mature, flexible and stable UI-designer / UI-runtime. It is both editor and dashboard in one app. You can start editing on your iPad and continue on your Laptop and switch between editing mode and “live” mode on the fly. All changes are synced. I have only good things to say about HABPanel. My advice would be to put everything you want to see or control manually on a HABPanel. It is ideal for tablets and works on a mobile phone as well. Although not as nicely, due to limited screen real estate. Combine that dashboard approach with voice control assistants like Siri or Alexa and you have covered 99% of all daily use cases. In fact, again, a sitemap would be of no use here: The mapping for voice assistants has to be done separately.

Create your items textually and put them in one file. Group all items.

I have one .items file where I keep all of my items. Having more than one file leads to smaller files (obviously), but there is a problem: Groups. You can only assign items to groups that have been declared in the same file. This doesn’t work in practice because you loose the ability to use groups as dimensions. For example I have one “catch all” group called “House” where all items are assigned to (directly or indirectly). This is not possible if you scatter your items across files. You should use groups because they can be used in rules and for the simple reason that the current de-facto standard UI for all text file editing (Visual Studio Code) uses groups to build a tree view of your items. You can assign an item to various groups. A groups does not need to be used for controlling multiple items at once. It can exist solely to semantically group items. This is very, very handy. Which leads me to…

Use Visual Studio Code for editing items and rules

VSCode is fast, cross-platform and as it currently stands it is the most mature openHAB text file editor. Not only has it syntax highlighting, auto completion capabilities and (limited) refactoring capabilities. But it also has a sidebar where it shows the current values(!) of your items in a tree view by group. I even use it if I do not want to do any editing just to get an overview of my item’s current states. Compared to a sitemap (that gets outdated and has to be maintained) this overview is “live” and always contains all items.

Make sure you have quick and easy access to the log files at all times

This is especially true once you start writing your own rules. On a Raspberry Pi there is the log viewer which is accessible via web browser. It depends on other platforms. I’m on Mac OSX, so I just share the log file folder over the network and open the files with the text editor of my choice (capable of auto-refreshing).

Again: This is my personal best practice. It is in no way the right thing to do.

Hope that helps!



I also tried a lot. My first setup was completely done in PaperUI. Due to some limitations in PaperUI (like Expire Binding) I started to learn the textual files. So I made a fresh installation with a mixture of PaperUI and Textual files. This was also not the best solution for me because some bindings are getting very often updates like the ip camera binding from matt1 (which is perfect) and therefore I made another fresh installation and doing all in textual files. Only when bindings are very complicated, I use the PaperUI for thing.

I also made some OH2 - Installations for my friends and neighbours. Therefore text files are also easier to handle. If the wish some changes, they send me an E-Mail with there files, I do the changes and send them back. Just simple to do.

Next big point for me is the possibility to make comments. If a need some Items only e.g. in Christmas vacation, I comment them out or in a few clicks and they are only visible when I need them. No Idea whether this is also possible in PaperUI or not. I know I could to it with rules, but I prefer the easier way.

For me text files are the way to go. Easy to create, copy&paste possibility, easy to share in E-Mails, easier to find in individual files (Switch.items, Contact.items, Temp.items, …).

I hope the textual method will not do in OH3. I can understand David_Graeff who prefers PaperUI because PaperUI is great and easy for beginners, but I think if you will do more with OH, textual is the better way. Hopefully both will be included in OH3.

Wow thank you everyone for such comprehensive replies; it gives me a lot to consider.

Most of this came about because I noticed on OH startup that my Tasmota light switch didn’t have any default values until I toggled it manually. That led me to checking config file examples and noting some used “channel” while others used “mqtt”. So that’s this morning’s investigation.

And yep, totally intend using HABPanel but I’m very conscious of walking before running.

1 Like

Just found out the expire binding… I have a bunch of mqtt items defined in PaperUI, is there really no way to link them to the expire binding? I have right now a bunch of rules to do the same but wouldn’t mind replacing that with expire binding…

No. The same limitation applies if you use any version 1.x binding.

There is an alternate implementation of ‘expire’ functionality using new rules