OH3 - Textual configuration still supported?

At the moment I’m building my whole home setup with OH 2.5 and textual configuration files. (using KNX, Hue etc.) That works pretty nicely and I love to have my whole setup (things, items, sitemaps etc.) in textual configuration files that can be versioned (Git) nicely. For a software developer thats the only viable way of working on projects.

After reading through different OH3 topics I’m not quite sure if that textual configuration is still supported. Or if it gets dropped completely. I’m afraid that we get a mixture of both worlds. (e.g. things in ui and items in text)

Could someone shed a bit of light on that topic? I can’t believe and I hope that we don’t go back to slow and error prone UI configuration.
If that is the case why does the configuration process gets changed on every major OH version? It takes weeks to configure a whole KNX installation etc in OpenHab. It would be great to have a concept that we stick to.


My best guess is there were deficiencies in OH1 that could only be resolved by breaking compatibility.

There are deficiencies in OH2 that the developers believe could only be resolved by breaking compatibility.

Yes textual configuration will supported in OH 3. There are no plans to remove it.

openHAB 1 bindings will not be supported in openHAB 3.The reason is, there is a large piece of code to keep openHAB 1 bindings compatible with openHAB 2, which no one wants to maintain and makes it more difficult to improve other code. Also due to the change of openHAB core from Eclipse smart home back to openHAB the Eclipse namespace must be removed for legal reasons. And this also would result in difficulties because the old openHAB 1 contains a number of classes with similar implementations in Eclipse smart home that would conflict due to them getting the same namespace. The namespace change will technically make all older bindings incompatible, unless changed to the new namespace (which will be done for all maintained openHAB 2 bindings). The namespace change has no effect on your configuration, but might affect rules if you explicitly imported openHAB code on the Eclipse namespace. But that would be easy to change.


Thank you very much. That sounds nice. It is perfectly OK to drop the support for OH1 bindings.

1 Like

At least if there is a replacement… :wink:


And for those that there isn’t, it’s possible to federate an OH 2.5 instance to an OH 3 instance and run the 1.x binding in 2.5.

I’ve got this working and documented using MQTT and Rules DSL and Jython. I’m working on a JavaScript/JSON version that can be imported as a rule template using the REST API and just got a big boost on that front from Yannick on another thread.


One more question regarding that topic. Is the textual configuration a first class citizen in OpenHAB or something to be removed in the future? I’m a bit worried since it seems to be a one or the other approach in OH3.

You get to choose which way and the pros and cons are listed here.

1 Like

To see what openHAB 1 bindings are supported in openHAB 2/3 see the list that tracks this:

So if you see a binding you use and that is not yet being worked on this is your chance or start a campaign :smile:

1 Like

Haha :rofl:

Well, I’m sorry I don’t have the needed skills to write a binding, and there is no open issue for vdr nor asterisk. :cry: but there will be workarounds. At least for asterisk I’m using agi2mqtt for call signaling.

Re-upping this issue…
Is there some experience from the ones testing OH3 longer than me, has the UI-approach more benefits or is it better to use text configuration files? Right now, I’m pretty confident in my text files and have no issues with them. But as I’m in for some refactoring of my 4year old installation, I’m inclined to changing to UI, if it’s more stable/future-ready/… ?

The pros and cons that matt1 linked above are still valid - and AFAIK there are no plans to remove the textual configuration part for OH.

So for me -and this is just a personal thing- I’m still a big fan of the textual configuration and using it for all my configurations because I’ve the feeling to get a better understanding of what exactly is happening “under the hood”.

But be aware, that some bindings (e.g. the new tr064-binding for OH3) are more UI-focused regarding the configuration steps described in the wiki (and their nature of automatic discovery for (sub)devices). It’ s still possible to configure them via text files but you might have to invest some more effort/research.

1 Like

That’s my thoughts right now, as I’m struggling to understand the concept of the MQTT2.x binding configuration (no textual examples given in docs… :wink: )

That bugs me too - try these examples from GitHub:


You can also split the topic things from the broker thing, which you will find even less examples of:

Bridge mqtt:broker:myUnsecureBroker [ host="", secure=false ]
Thing mqtt:topic:mything "My Thing" (mqtt:broker:myUnsecureBroker) {
        Type switch : lamp "Kitchen Lamp" [ stateTopic="lamp/enabled", commandTopic="lamp/enabled/set" ]
        Type switch : fancylamp "Fancy Lamp" [ stateTopic="fancy/lamp/state", commandTopic="fancy/lamp/command", on="i-am-on", off="i-am-off" ]
        Type string : alarmpanel "Alarm system" [ stateTopic="alarm/panel/state", commandTopic="alarm/panel/set", allowedStates="ARMED_HOME,ARMED_AWAY,UNARMED" ]
        Type color : lampcolor "Kitchen Lamp color" [ stateTopic="lamp/color", commandTopic="lamp/color/set", rgb=true ]
        Type dimmer : blind "Blind" [ stateTopic="blind/state", commandTopic="blind/set", min=0, max=5, step=1 ]

to leave off-topic here:

please, if someone knows the answer, please go over there! :wink:

1 Like

Textual config is still supported. However, disc errors do not occur when creating Things and Items through the Ui. That alone degrees a ton of debugging and time specify on support on this forum. All of the options are self evident and reasonably documented in the UI as well.

Those who are motivated to do it all through text files can certainly do so. But ultimately it becomes a big time sink for both then and those of us who offer support on the forum.

There are some bugs as well that only occur with text based configs and there are some minor things mostly to do with rules, that are only possible with JSONDB configs. JSONDB configs tend to be faster as well

The improvements in the ui have largely addressed a lot of the things that drive people to using text configs. For anything that is missing, please file issues. Or continue to use text configs, but I suspect it will become more and more nitch and therefore more and more difficult to get support over time.

I’m not so sure that this is a valid feeling. The text based configs are at least one step, maybe even two steps removed from what is going on under the hood. The JSONDB fingers are actually much closer to what is going on under the hood and it much more closely represents how this information is actually represented in the data structure in memory. Given that, the forns present in the ui and the rest api itself is as close or close to what’s going on under the hood as the text configs.

the developer if there binding, with good reason I think, decided it wasn’t his job to document that. The .things done syntax is not defined but controlled by the binding developer. And when created through the UI the syntax is always right. It’s actually a significant imposition on the binding developers to document the. things done syntax and I completely understand why done may not want to do it. Especially for binding’s that support automatic discovery.

Personally, I’ve spent enough time trying to help people with. things files and won’t do it any more. It’s a huge time sink and both my time and the users time would be better spent solving home automation problems instead of syntax errors.


I know what you mean and I’m sure that digging a bit deeper into the system would reveal me a whole new world of complexity.

It may be related to my starting point with OH1 where only text based config was available and I was forced to understand how it all works (even if it was/is ‘only’ some markup language far away from the real core-system) - but tbh I love(d) to invest my spare time digging into each single item, understanding what it does and smiled like a baby if I got even the smallest thing visibly working.

And this is one of the main ‘downsides’ (and the reason why I still using only textual config) of a fancy automated UI for me (and I normaly love UI stuff as you may have noticed :stuck_out_tongue: )… You stop appreciating the little things. One click brings up hundreds of items, so you easily get overwhelmed by possibilites and the understanding for the effort, someone took to create these.

For me personally, it helped me a lot (especially in the beginning, with no clue how complex home automation could be) to understand the basic mechanics of OH but I also fully understand and appreciate the way that OH developed in that way.

There might come the time, where I have to say goodybe to textual configuration and have to begin understanding the UI config and JSONDB stuff (especially when you say that it might be faster) but until then, I’m happy to annoy myself with my *.items and *.things files - even if I might be alone with this mindset. :slight_smile:

yes, I got that feeling playing around with OH3 also. And after some learnings and stuff I found out that you also can use the “textual configuration” for loads of stuff mostly. For my part, if I have to configure things, which aren’t on “auto-discovery”, you can use “code” to duplicate items way faster than clicking around and the built-in checks do the job WAY better than any IDE would be! :wink:

This wasn’t meant as it may sounded, I didn’t want to impose work on top of somebody’s free time, I just wanted to point out, I did the RTFM thingy! :wink: And yes, PaperUI is not the best solution but the OH3-UI is much more like it.

So I guess, I’ll switch to UI-based configuration and backup the JSONDB then! :wink:

a short q.e.d. just now:

just a misspelled seperator instead of separator and boom: ~2+ hours from my side and I guess a few from others in a stupid thing configuration! :wink: