I looked back at your first post here on this topic. Windows was not mentioned. The majority of developers & user have a UNIX-like OS like MacOS or Linux. That was the assumption without an OS mentioned.
you are correct. The fact is that every user assumes its system is the default. I did not think that the default of OH is Linux either.
In my view, purpose of documentation is helping people to get rid of assumptions to find solution.
Reading the documentation I just read obviously the page pertaining my OS and I did not understand that this introduction is meant only for Linux (is it?) -
I believe that the “curator” of any specific OS could easily add that piece of info, if relevant. Should be a piece of cake. You explain how to install, and how to uninstall. Comes together, usually. Especially when you don’t have an uninstall utility and you have no clue how settings work with java and the like.
Take my case for instance. I don’t know linux, I got Raspberry where, in the future, I’d like to run stuff including OH. But feels natural trying to understand OH on a OS like Windows I can easily navigate, first. Then, I will face Linux for Raspberry. It makes sense to me. And here I am.
1 Like
This tutorial here is designed to be system-independent.
For setting up OH3 on windows systems, this is the latest installation doc on GitHub: openhab-docs/installation/windows.md at main · openhab/openhab-docs · GitHub Feel free to create a new issue regarding information on how to uninstall OH3 for this page.
2 Likes
I thought I had a link to that section of the docs already. I’ll double check. Though I don’t know that we have a landing page for just “installation”. In which case which page would I link to, openHABian, Linux, Windows, QNAP?
I think that is something that belongs in the installation tutorials, not the Getting Started guide. The procedure is going to be different based on what platform and how OH was installed.
As I mentioned, it depends on how you installed it and on what platform. If on a Debian based Linux using apt, an apt-get purge openhab2 I think will get everything. If on another platform (e.g. Windows) deleting the folder you unzipped openHAB to would be sufficient I think. I don’t run Windows anymore so I don’t know how most users do that…
So, I agree unistallation probably needs to be covered somewhere but not in the Getting Started tutorial. It probably belongs in the installation instructions for the platform you are using because the procedures can be radically different between the platforms.
One thing you will find with openHAB is that only a relatively small minority of users run openHAB on anything but Linux. So almost all the advice provided is going to assume Linux unless you state otherwise in your original post. On Linux, especially if one uses openHABian where this stuff is preset up, Backup and restore can be as simple as a couple of commands. openHAB also comes with openhab-cli which offers backup and restore options, but just for openHAB, not the whole system.
Markus’s point though was that before making any major change to a system (e.g. installing or uninstalling software), creating a backup is a good idea.
The errors your are seeing are new to me. You might post about them in the OH 3 RC1 thread to see if this is a bug or something.
It’s mainly that no one has done it. I for one would welcome such a contribution.
The getting Started Tutorial is OS independent. And that’s why it doesn’t start with installation but instead asserts successful installation as a prerequisite. There are almost a dozen different platforms OH supports and we can’t cover them all in the Getting Started Tutorial.
But once installed, everything presented in the Getting Started Tutorial applies regardless of platform OH is installed on.
Also, it’s worth noting that when you create a new thread in the “Beginner’s” section of the forum, you are presented with a template asking for relevant information like what version of OH you are running and on what operating system and how it was installed.
I’m afraid you will find that there is no such curator most of the time. I don’t think anyone who actually runs OH on Windows has contributed much to the Windows Installation guide (I’d have to check to be sure).
I don’t think any one here is arguing that the information doesn’t belong in the docs. And I think we all agree it belongs in the installation page for Windows.
So, who’s going to go do it? That’s usually where everything breaks down. I’m currently booked trying to get this tutorial into the docs so I can’t do it right now. I’m hopeful that someone can step up and submit the content. It’s a great first PR really since the content is basically already written.
If anyone needs help navigating GitHub procedures I’m happy to help. It’s odd at first but pretty easy to get the hang of after a couple of times.
yes please. Not sure if I should fork, edit and submit some ways, never done that. I’m also fine interacting with someone who does that for me, in case that’s more polite to the doc team…
yes, absolutely. I actually was expecting an Introduction including a section about *where do you get the current info on how to set up the environment - *we might name it 0. Foundations. Commenting here because there is no 0 step, I looked for it in vain.
What I meant was at least providing a link to the active installation doc hub (found a lot of redundant sources and I have been quite confused which is the most udated: For instance the prerequisite section is repeated in the overview and the OS specific folder.
I understand there are multiple OS, but arranging a page bridging to OS specific instruction is not that hard.
restoring my laptop to a previous restore point is a process which -if there are no issues -takes 6 hours. And every app/setting you have installed after a restore point is zapped and need to be reinstalled afterwards. For windows users, it’s an emergency thing. Backup is easy/peasy for files, not for the registry
I understood what caused it. A bit long to explain - in short Zulu installation leaves the previous install folder untouched, so the JAVA_HOME points to a java installation no longer active. The documentation has still the old screenshots mentioning jre as path instead of zulu, so the documentation should be updated saying “be sure that the JAVA_PATH points to the same installation folder as the zulu instance you installed in prerequisites”. and change the screenshot. In bold. Maybe that’s silly, once you know it. I wasted nearly an hour to understand why.
Forgot to mention: in the page Windows | openHAB the whole second part and the screenshots in general are outdated and refer to OH2. I think it would be better placing a warning saying that in clear. Try putting yourself in the shoes of someone who has never had a peek on OH3 and cannot get that easily and has issues to fix.
Anyway - back to the topic of this specific Introduction: I understand conceptually the paragraph “An important decision: File-based vs UI-driven configuration” -
I just cannot understand where this tutorial branches - do I have to choose something in this phase or later or if it is referring to the YAML editor or the fact that somewhere (where?) you have to decide to handle things using an external editor like VScode+extension? This is interesting, important, but cryptic imho.
See How to file an Issue for some fist steps. It’s mostly focused on how to make small edits to the docs through the browser. But indeed, you will need to create a fork and you will probably want to create a new branch on your fork if the changes are involved. Once you commit your changes GitHub will show a button to create a PR.
If you run into trouble let me know.
One page, no. But we are talking about at least 9 pages.
And the Step 0 is intended to be covered by the prerequisites:
- You’ve read the concepts section of the docs
- You’ve installed OH
The Getting Started tutorial is not going to be the first things that users see when they look at the docs. In fact it’s going to be the last section under Concepts.
I already have it on my list to include a link to the concepts section and the Installation landing page. But I have no plans to include any installation or environment information in the Getting Started tutorial. It’s duplicative and will be just as confusing for new users to see all the instructions for all the supported platforms as it will be to not reproduce it here.
Sounds like a great first PR to submit. It’s short and relatively easy to implement.
It doesn’t branch. If you choose file based, as far as this tutorial is concerned, you are on your own. From that section:
In this tutorial targeting new users we’ll take a purely UI-driven approach. Review the reference documentation for details on the text based approach.
Further down just before the table of contents it also states (in the version that is checked in to GiHub right now):
This tutorial presents a series of steps that build upon one another so please review the tutorial in order. There may be concepts or steps that are presented earlier that are required to understand the parts of the tutorial presented later.
There is no branching in this tutorial. It gradually builds on the concepts presented earlier in the tutorial. It’s also not intended to be a reference. It’s not going to present everything. It’s just enough to get started.
This section exists though because:
- lots of existing users of OH mainly use file based configs and we need to tell those users that they will not be getting a Getting Started with File Based Configs from this tutorial
- it’s an important decision to make because switching between the two approaches is not easy; those users who are technically proficient enough to know out of the gate that they will not want to use the UI to create their configs need to know up front that it’s not easy to move to text based configs.
But most users should read the sentence above about how the tutorial is only going to present UI based configs and continue on.
got it. I assumed - at some point - it was possible to ask OH3 to show the textual files behind the scenes, save them and perform the switch. Do you mean that is not possible? And if that’s true, how is it possible to backup the config in case you have to reinstall/migrate to a new machine all your work? Would it be some weird form of binary export of something?
In the meanwhile there is nothing which can be done using VScode+extension then- do I get it right?
And where can I find the “reference documentation for details on the text based approach” - could a link be provided there? I think it would be useful.
You can see a textual representation of the stuff you do through the UI but not the textual representation. It’s a long complicated story but at a tl;dr:
- text based configs get loaded into openHAB’s memory as read only
- UI created stuff gets saved in a text based JSONDB file
- the UI will show you a YAML interpretation of the JSON for those elements that it supports doing so (click on the
codetab).
The third bullet point is all that is covered in this tutorial though. But that’s one technical reason why it’s so hard to move between text based configs and UI created configs.
Correct and that is what that section is supposed to be saying. You can go from text file based configs to the UI for Items. For all other text based configs you have to recreate them by hand through the UI. For anything done in the UI there is no way to export them to the text based config formats.
It’s all saved in userdata/jsondb. If you are backing things up you want all of the conf folder and most of the userdata folder. There is a backup.bat file (openhab-cli on Linux) that will grab the full config. Personally I check most of my userdata folder into git for version control. It’s all text.
If you want to configure openHAB through text based config files (.items, .things, .rules,.sitemaps, etc) then you really want to use VSCode with the OH extension. If you are following this tutorial than no, you don’t need it. It’s all done through MainUI (with one tiny exception).
It’s all unchanged from OH 2.5. So all the current docs cover it. There isn’t one link. Each file type has it’s one format and therefore it’s own set of pages in the docs.
1 Like
Thanks for your patience and help - got that clear now. Growing doubts OH3 is not the right version for me then 
Why?
Well, you see, I expect to have to spend a lot of time to set up my OH iot solution. The user interface is gorgeous, but brand new. It means for me that everything not implemented correctly by the SW team cannot be fixed easily working behind the scenes in text mode.
Moreover, as I will know more and more the system, I expect to take less time fixing a text file than browsing the UI. That’s the reason complex development environment like for instance the Visual studio suite do not bind you using only the UI.
Take this example today - I was trying to fix a chart adding multiple series, and I cannot get the gridindex working. Series not working simply disappear from the interface and you cannot recover them. Have to delete the whole chart and restart. YAML not helping. I’d like to see the underlying implementation to troubleshoot. not possible, I think.
Or, I need to add many copies of the same thing with minor changes (IDs etc) - a text interface is a winner.
I expected that, even if the underlying ‘engine’ has been moved to JSONDB, an utility to allow to ‘translate’ in and out to the old text language (with potential UI losses I understand, but that’s better than nothing) was provided or planned. If you are locked to the UI and the only chance to work in text is rebuild everything from scratch, well, obviously I don’t feel like getting bound to it.
Users who expect to link just few items and have a quick fix would obviously feel the opposite, I understand. It makes sense.
I am a bit surprised that a system that has Linux as the core target is switching to a full locked UI. Sounds more IOS to me. JMHO.
Now I just need to understand if there is some reason (additional functionalities etc) to run textual OH3 instead OH2.5. Let’s see when I found some documentation on that topic… People I have talked to, so far, tend to stick to 2.5 for this text thing, which I have now understood a bit better
I think, there is a misunderstaning. Yes, you can import your items into JSONDB via UI, but you can also stay at where you are, defining them in text files. This is not going to be removed. Therefore, there is no target to switching to a locked UI.
What might need to be changed though, you may need to add metadata to your items which are introduced with openHAB 3.0.
1 Like
mhh. so an hybrid system is possible? So the choice mentioned in this page is not really a choice…? Now I am confused 
Even openHAB 2 had some kind of a hybrid solution. PaperUI was for graphical config, while there was support for textual as well.
We had bid discussion here in the community, users being afraid of not being able to use textual config any more. This was never on focus.
With the new UI and config handling, we aim to make it simpler for new users, while still give the power users most felixibility with textual config.
1 Like
Many people here are successfully using text files with OH3. If you use text files you cannot manage those objects through the UI, same as in OH2.
If you wish to use the UI c=you can use scripts or other CLI methods to update things through the REST API, same as the UI does. The UI uses the REST API.
OH has used JSONDB for years. OH 2 uses JSONDB.
All developers here are volunteers. Feel free to propose something in GitHub.
1 Like
this makes very sense. I justhope to find some documentation somewhere, like the workflow of interactions text-ui - and markups.
That would be a VERY interesting documentation page to read, even before diving in the nitty gritty of the OH model.
Documentation updates are under review und we aim to publish them with the final relase.
It’s all serialized to the JSONDB. You can see the “actual” implementation there, if what you mean is how it’s actually stored. There will be at least one file that starts with “uicomponents_ui”. I think almost everything Pages related gets stored in there.
This is very well supported with Items. And there are discussions for how to handle the rest to do bulk edits. They won’t be ready before OH 3.0 release though.
But I should note that IDs are pretty much universally unchangable. It appears you can easily change IDs when using certain text config files but what is actually happening is everything defined by that file gets destroyed and then recreated anew when the text config is loaded. And even if you do that, stuff can become orphaned. For example, if you change the name of an Item, there are Links, Metadata, Rules, Pages, and Sitemaps that won’t necessarily get updated to use the new Item name.
There is nothing locked about it. Everything is stored as plain text for inspection and potential hand editing should you need to (just don’t edit the JSONDB by hand while OH is running or your changes might get overwritten). And if JSONDB’s a problem for you, there is still support for sitemaps in the UI.
For Things, there are limitations with .things files that do not exist when using the UI to manage Things. One big thing is certain bindings, such as the zwave binding, are not fully functional with .things files. In Zwave’s case, you cannot set parameters on end devices if your things are defined in .things files.
In addition, many of the developers and helpers on this forum (including me) will not provide support for .things files syntax. It’s a huge time sink which simply goes away when you use the UI. The syntax is never wrong when Things are automatically discovered or created through the UI.
As for the rest, they are supported pretty much the same as they were supported in OH 2. They get loaded into memory, overwriting anything that happened to be there before, every time OH starts or the file is changed.
Performance of loading and parsing the text configs has greatly improved in OH 3 but it’s still much faster when using JSONDB for storage.
The majority of people who stick to text configs (not all but most I think) tend to be quite conservative. They’ve been using text based configs for a long time so have a compelling reason not to change, and they tend to be slow to update OH. So just be aware of sample bias for something like this.
I’m not going to tell you one way or the other. But the Getting Started Tutorial isn’t going to help you much if you choose text based configs. And I don’t foresee someone writing such a tutorial anytime soon (I know Yannick and I are not and we’re the primary contributors to the tutorial so far) . So you will have to figure stuff out from the reference docs, the forum, and asking for help. Obviously it can be done and is pretty much how it’s always been done up to this point in OH 1.x and 2.x.
But I want to reemphasize one point. OH 3 does not eliminate any text config options that exists in OH 2.5. You can set up and configure OH 3 exactly the same way if desired.
Note, if something still seems to say OH 2 or be OH 2 focused, it doesn’t really matter because these configs and formats have not changed in OH 3 (except for the metadata stuff already mentioned which I think is mainly a concern for MainUI Pages which, if you are going for a 100% text based config with nothing in JSONDB you would not be using anyway). That just means we the docs contributors haven’t got to that page yet to change some of the references.
| File Type | Link | Notes |
|---|---|---|
| Things | Things | openHAB | You’ll need to look at the binding doc for specifics about that binding’s Thing’s options |
| Items | Items | openHAB | |
| Sitemaps | https://next.openhab.org/docs/configuration/sitemaps.html | |
| Persistence | Persistence | openHAB | This is still only supported through text configs in OH 3, but now each persistence add-on comes with a default policy. |
| Rules DSL | Textual Rules | openHAB | |
| Transformations | Transformations | openHAB | Each transformation will have it’s own syntax as well, see the add-ons docs for details. |
| Actions | Actions | openHAB | Certain Actions, like Ephemeris still have only a text based config available. |
| JSR223 | JSR223 Scripting | openHAB | If you want to get started with one of the other supported programming languages for rules. |
Notice how all I did to build that table was go to the “Configuration” part of the docs and copy the links on down the line one by one.
EDIT: I should have posted links to next.openhab.org instead of www.openhab.org
6 Likes
Nothing much to add after this great reply. You can go full JSON DB, or none at all, or partly.
Stuff defined in text files won’t be editable in the UI, because the UI will never touch your files. If you know relational databases, think of your files as SQL source files, you run them to bootstrap your tables and views etc. - openHAB actually runs them constantly, removing things and re-adding them as you change them, and the fundamental difference is that those are immutable - and changing things in the UI as making statements to alter a table when it’s live. When you do that, your database engine will not find your original SQL file that you used to bootstrap the database and change it.
With the JSON DB you have the convenience of being able to say whenever you’re on your couch “hey I wish that rule would set this to 30 instead of 40” and pull out your phone and (in many cases) being able to do just that, or, you could prefer to also have the convenience of a full-fledged text editor and have the configuration re-read when you save those source files. You can have a mix of both, you decide.
Ultimately the rule is, “whatever floats your boat”, if you don’t find the UI convenient I for one won’t be offended for sure, if your use case means it’s not the best way.
4 Likes
Just to share my experience in migrating my all text file based OH2 system to OH3 (both Dockers). With almost 400 Items and extensive DSL Rules, Sitemaps, HabPanel and Map files I can say that in my case there were only a few issues that needed to be worked around. As others have said, OH3 treats text files much the same as OH2. I did have to make changes to a few rules that used Joda.time ( thanks rlkoshak) and WOL in OH2 and recreate a few Items that for some reason, still unknown, have no way to link to Things but OH3 is still young. Further for the one binding that I use for which there is no OH3 update, I was able to use the Remote OpenHab binding to federate OH3 with an OH2 install that runs only this single binding. There is some added latency with this approach, but not terrible.
While everything is working fine, I’m still on the fence as to whether to make this my production system NOW, or to wait a bit longer before making the move permanent. In my case OH2 is as solid as a rock and OH3 offers no real benefit TODAY when using text files, sitemaps and HabPanel. However as things change, API’s are updated and Certificates need to be renewed, OH2 will be stranded with little to no support going forward. So from my perspective it really is not whether to migrate but when is the right time to migrate. I am continuing to run OH3 in test mode using text files exclusively and using HabPanel and Sitemaps as my user interface, but OH3 stability is looking better as each day passes. In the meantime I will continue to evaluate Pages as an alternative UI to Sitemaps and HabPanel.
6 Likes