Getting Started with OH3: rewriting the tutorial - 1. Introduction

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 code tab).

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 :slight_smile:

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 :slight_smile:

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 :woozy_face:

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 https://next.openhab.org/docs/configuration/things.html You’ll need to look at the binding doc for specifics about that binding’s Thing’s options
Items https://next.openhab.org/docs/configuration/items.html
Sitemaps https://next.openhab.org/docs/configuration/sitemaps.html
Persistence https://next.openhab.org/docs/configuration/persistence.html This is still only supported through text configs in OH 3, but now each persistence add-on comes with a default policy.
Rules DSL https://next.openhab.org/docs/configuration/rules-dsl.html
Transformations https://next.openhab.org/docs/configuration/transformations.html Each transformation will have it’s own syntax as well, see the add-ons docs for details.
Actions https://next.openhab.org/docs/configuration/actions.html Certain Actions, like Ephemeris still have only a text based config available.
JSR223 https://next.openhab.org/docs/configuration/jsr223.html 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

really, hope I have not offended anyone, the UI is great and I know how hard must be developing it. I am just writing as a newbie who needs to understand how to get around and troubleshoot.

Back on the topic with a live example, not sure if this issue OH3 how view textual definition of an Item is linked to that. Integration of the charts in the UI with items: is it supported only if the item is created through the UI for instance?

No, it should be supported either way. I don’t think the UI sees those any differently except that it has to know that Items defined in .items files are read only in the UI. But otherwise two identically configured Items (except with different names of course) should behave the same in the UI including appearance in the automatically generated parts of the Overview Page, appearance in the model, and charting.

Yes you are correct. It looks like there is a known bug which hampers charting for some hours for items created manully - and/or after installing a new persistence (?!) see here for additional insight. Writing for newbies stuck with the same issue trying to follow the tutorial

1 Like

It might be helpful as well to look at the Persistence Page (https://www.openhab.org/docs/configuration/persistence.html) I wrote as part of the tutorial that is not part of this wiki series.

1 Like

4 posts were split to a new topic: Question on widgets