Starting using OH3

  • Platform information: HP - Vmware ESXI
    • Hardware: INTEL/8GB/100GB
    • OS: Ubuntu 20.04 LTS
    • Java Runtime Environment: Zulu 11
    • openHAB version: 3.1.0
  • Issue of the topic: using text configuration

Hi All,
i just installed openhab 3 and i’m playing around with it a bit.
Currently I still use OH1 because I never liked OH2 much and also because I wrote several hundred lines of code that are not easily transportable.
OH3 looks much improved (at least in my opinion), but I would like to have some opinions from you.
I have read the documentation and also a lot of posts about the community and I apologize in advance if I’ asking for the obvious or things that I missed.
I have installed OH3 in manual mode in the dir / opt / openhab.
I was able to set up a test environment with the Main UI without problems and I really appreciated the work that has been done to simplify the creation of the house project, however I would prefer to continue using the text mode, as I have seen that many users in the forum they are aimed at the same goal and are concerned that in the future this mode may no longer be available.
This for 3 main reasons:

  1. The configuration backup can be done simply by copying the text files;
  2. It is much easier for me to edit text files (especially for copying similar code blocks) than to use the Main UI;
  3. It appears (from the documentation) that persistence and visibility are not supported in the Main UI.

I read in the documentation that it is also possible to use a mix of the 2 possibilities, although not recommended, especially for Items.
What I would like to do, and ask if you think this is correct, is to use the Main UI for the discovery of Things and then write everything else in text format.
For now, however, I still haven’t figured out how I can put Items, Rules and Sitemaps inside directories and make them work. I tried, but none of the files I insert are seen by openhab. The documentation only explains the use of the system through the graphical interface (which works perfectly) but, while making some examples with the code, it does not explain how to activate the text files instead of the Main UI or at least I did not understand it .
Thanks in advance

Start here for file locations

Overall not a bad approch for someone of your experience with OH
Using Main UI to create things saves you have to figure out the complex thing syntax which never has been well documented and varies with bindings
Problem with text files is they are what are considered ‘unmanaged’ in Main UI, meaning you can’t edit items and rules in Main UI that live in a text file
Mixing the two approchs is largely uncharted territory and you may have problems no one will be able to help with, but I’ve seen no horror stories, just odd glitches eventually resolved (and a few bugs shook out)

Don’t read any posts from before OH3 was released. There was lots of noise about this, even though it was clearly stated that text-based configuration wasn’t going away in OH3. It’s not like the devs are going to suddenly remove text-based config in a minor OH3 update, and no one should be worrying about what happens in OH4. Besides, you managed to hang onto OH1 for this long.

If I’m reading you correctly, this is what I’ve been doing since I started using OH. In OH2, I used PaperUI to discover things and then created items in text files. For the most part, I’ve carried on with that approach in OH3. The only text-based things I have now are mqtt, because I saw no reason to move my working MQTT config into Main UI.

Where are you putting your files? OH3 still generates folders for items/rules/etc. (see the link provided by @Andrew_Rowe), and if you put your files there then they should automatically be found and updated.

There is no plan to remove text based configurations. However, support here on the forum is slowly degrading as some long time users move to the UI for everything and new users never use text based configs in the first place.

There are some things that cannot be done through text based configs as well such as Page Widgets for MainUI.

Literally everything that is done through the UIs is stored in text files. Backup is the same with the only difference being which text files you back up. One should use the backups script that comes with OH to backup and restore and everything, whether they are stored in conf or stored in userdata will be backed up.

The code tabs in MainUI support this use case too. Create your Thing or Rule or Widget or whatever in the normal way. Click on the Code tab and copy the YAML presented there. Create a new whatever, click the code tab and paste and edit. The one place this doesn’t work well is Items as there is no code tab for them (yet?).

.persist files are not supported in MainUI yet (there is no REST API end point implemented). However, in OH 3 all persistence engines come with a default set of persistence strategies so for many they never have to create a .persist file in the first place.

I’m not arguing against your decision. But every time I see a post about all the reasons they don’t use the UI for things, most of them tend to be misleading or exaggerated at best or flat out wrong at worst. Please by all means use text based configs if that works best for you. There are plenty of good reasons to do so and there is nothing wrong with doing that. But don’t spread FUD about the UI based configs in the process as it scares away users who would rather use the UI but are afraid that they can’t because the configs are not text based or can’t be checked into git or something like that.

Note: one of the biggest problems with using git with the JSONDB files , the fact that at times the entries are reordered, currently has a PR submitted to avoid that. When/if that’s accepted and merged then the argument that you can’t check the configs into git and compare histories will go away too.

The recommendation is to avoid mixing text and UI based configs for a given entity type (e.g. Things, Items, Rules, etc.). However, it’s reasonable to do all the Things through the UI and all the Rules through text files. There are certain limitations with rules in the UI that make this approach very attractive in fact.

This hasn’t changed since OH 1.x. .rules files go in the conf/rules folder. Sitemaps go in conf/sitemaps. Items go in conf/items, and so on. There is nothing special you need to do to activate them. If the files are there OH will load them and either generate an error if there is a problem or you’ll see a log entry showing it loaded the model from that file.

Note sub directories are not supported, just like it was with OH 1.

They won’t be transportable to OH 3 either. You should go through the OH 1 to OH 2 tutorial to see what to change, and then look at the breaking changes for OH 3 to see additional things that need to be changed.

Anecdotally, I’ve observed that there are fewer “how do I make this simple item/rule” questions since OH3 was released. I’d like to believe that this is due to the UI rules making it easier for people to accomplish simple tasks without having to worry about syntax (as intended). However, it could just be that they’re getting drowned out by “how do I get __ working in OH3” questions as we go through the transition.

I generally focus more on the philosophical/practical/simple questions that better suit my skill level, and feel like those are fewer and farther between (which has led to me posting less frequently).

If you are asking how to use main ui with text files like you did with sitemap files, the answer is you can’t but you can use yaml to create it if you wish but it is stored in the database.
As for creating items with text files you can do this however you will be spending more and more time creating them. It is a side effect of it getting easier via the UI. As more people use the ui less will post examples in the forum, less binding devs will include them in the docs so it will be up to you to figure it out.

This is why I have changed from being all text files and now being all UI based but still have a sitemap file for backwards compat reasons that will be replaced over time. If some has to be in the database, why not place it all in there? Openhab 3 is very new and is only at the beginning, it will be improved a lot over the next few years and it will only get easier to do things in the UI and this will make textual harder by comparison. An example is that most likely doing the semantic tags will be automatic via the UI in openhab 3.2 where for textual use you have to work out what tags you want to add in the items files.

Thanks everyone for the valuable answers!
Now everything is much clear.
I believe that, since I will have to do almost everything from scratch, I will try to use only the UI, limiting the use of the text files to the rules.

Sounds like a good idea. This video may be of interest as it explains the changes openHAB has made and why from V1 to V3.

Hi All,
I realized that, unfortunately, I can’t limit myself to just using text files for the rules, but I have to use text files for sitemaps as well.
This is because I use the visibility tag a lot and as I understand reading the forum it is not (yet) supported by the UI.
Is that correct, or something changed?

I have not played with this as I don’t use a tablet on the wall (yet), and these settings can really eat up your time implementing. My philosophy/goal is to use real automations and not have to reach for a glorified remote control and I use speech controls when an automation does not cover the use case.

There is a post you should read that probably answers this…

Discussion on ontology improvement · Issue #1791 · openhab/openhab-core (

Last post at the moment is by @rlkoshak and in particular read his 4th bullet point.

As an example you can hide Battery levels so they don’t clutter up your MAIN UI and only show them when they are warning you the level is getting low.

This thread will also show you what is possible with the new UI that sitemaps are lacking.

Example Custom List Widgets - Add-ons / UIs - openHAB Community

Thank you very much for the reply!
I’ll try it!