Quick note: The Tutorials & Examples section is for posting your own complete tutorials or demonstrations. I’ve moved this to a more appropriate category.
To answer your question: nearly all binding docs contained specific examples for the textural configuration of the associated Things and Items. This is necessary because the requirements can be very binding specific in certain cases. Beyond that there’s not much “tutorial” required for text-based configuration beyond knowing the basic syntax which is found in the Configuration Guide section of the docs:
When the getting started tutorial says “you can always come back” the meaning is return to the help docs in general, not necessarily the getting started tutorial specifically.
I think there is need for a “tutorial”, cause I feel I have to go through the UI way of doing things first, cause I don’t even know where the configuration files are, how to reload it, how to do simple tests, etc.
I’m sure we would welcome a tutorial to be written. I myself have given up supporting text based configs. I’m tired of helping people solve syntax errors that are impossible to make when using the UI. Way more time is wasted with that than any time saved by using the files in the first place.
But as @JustinG points out, all the text configs are documented.
For example, want to know how to choose what add-ons to install through text configs? Looking at the “Installation of Add-Ons” page you’ll find Installation of Add-ons | openHAB which covers both the location and the format of the config file.
The same is true for all OH concepts that can be configured from files (anything having to do with MainUI or the Marketplace will have minimal support through text configs).
So any text based config tutorial would almost certainly be mostly links to the already existing docs which cover this because of the OH Docs policy of DRY (Do not Repeat Yourself). We don’t have the man power to maintain docs that duplicate what’s already covered elsewhere in the docs.
That’s not a bad idea anyway because text based configs are really hard if you don’t understand the basic concepts of how OH works.
For reference, I’m still using text-based rules, because my system hasn’t needed any major changes over the past few years (if it ain’t broke, don’t fix it). My plan has been to move to UI rules with OH4…but admittedly I keep putting that plan off.
I recently added motorized blinds and window sensors, so I stuck with text-based rules to keep everything in one place. Oof. It’s been so long that I can’t remember any of the syntax, so I wasted a ton of time fixing dumb errors. Instead of thinking about the processes I’m building, I’m thinking about typos.
Anecdotally, I would say that the number of “help me fix this item/rule” questions we get from beginners has dropped dramatically since OH3 was released. There were so many syntax-error questions before with OH2, and that just doesn’t happen with UI configuration.
I thought I’d never move away from text configs. I had gotten so proficient and had my setup so well optimized for text configs, that it only made sense to continue forever. When OH3 came out I loaded up a trial system just to get used to the new interface. After just a few days of exploration, I ended up porting my entire system over to UI managed Things/Items/Rules and haven’t looked back. For me there is no advantage anymore for text configs (some would argue batch editing is still easier with text, but you really shouldn’t have to do that very often, if at all) and there are the disadvantages that have been mentioned above. Now with the OH4 and the addition of transforms to the UI, I think I have 3 text config files total: 1 persistence config, one custom ephemeris file, and one custom runtime.cfg.
It’s still a bit of a change coming from OH2, but if you just might find that little bit of effort more than pays for itself in the long run.
There is a discussion issue where even that has been talked about supporting in MainUI, at least for stuff like Items and Things where the need is most.At this point I doubt anything will happen before 4.0 release but perhaps someday even that will be nearly if not just as easy to do through MainUI.
But I agree, the last time I wish I had a decent batch editing was when I initially set up OH 3 from scratch and was porting over my MQTT Things. And even then, the Code tab was more than sufficient for my needs.
There is some work to support persistence through MainUI but I don’t think it will be done before 4.0 release. There is talk for how to support custom ephemeris in MainUI but I don’t think there has been any work on it yet. It probably has to wait for the replacement of the back end library first anyway (the upstream library we are using is no longer supported but someone forked it and has continued development).
What custom settings have you made in your runtime.cfg?
I have sonos speakers, so I’ve had to adjust the upnp threads settings and I have a couple of custom additions to the MainUI “Other Apps” panel for quick access. That’s it. The later should, in my opinion, be something that MainUI eventually can handle in its own settings, and the former is a patch for something that isn’t fully OH’s fault (as I understand it).
I’m using the UI on my development test system and text files on my production system. Just for the sake of comparison/full picture, these are among the reasons why I still prefer text files:
Versioning. All my text files are in a Git repository and I can try things before committing something, or revert undesired changes. I can also go back to any previous version, for example older rules if I want to bring them back, or perhaps just some parts.
Flexibility. When doing major changes, for example recently Netatmo and in 4.0 possibly Hue, I can work on two versions and switch between them by simply renaming the files. I could also easily create the new configuration in a text editor based on the old configuration with macros, etc.
Refactoring. Sometimes I regret naming of things and items, and can easily adapt. The same goes for renumbering in some cases, etc. Simply being able to continuously change naming and also have readable and consistent names everywhere without any generated uid’s.
No caching issues, always correct state after restarting openHAB. Even with the thing migration improvements in 4.0 there are still some inconsistencies, for example changes in localized channel labels/descriptions and channel labels/description overriding channel type labels/descriptions, which is not fully handled by the upgrade mechanism. Of course it will be much better with 4.0, but it’s still something behaving differently. Update instructions can also be wrong, which will cause no issues for text files.
These are just my personal reasons/preferences, I fully understand that most people probably prefer managed configurations created from the UI.
When copying item definitions from the binding documentation, one thing to be aware of as of 4.0 M3 …
All the binding item definitions in the binding documentation (maybe not all, but certainly almost all) do not contain unit metadata tags, so when copying item definitions that have a dimension (e.g. Number:Temperature), it would be advisable to add the metadata tags at that time.
I always change the UIDs at the point of creation to something meaningful and recommend the same for everyone. Note, even in text based configs you are not actually renaming so much as removing and creating anew. Every time you unload a text based config, everything in that file is destroyed. Every time you load the file they are created new.
There is work being done in MainUI to support this sort of thing better. But it’s also a rare case.
This may need more description and perhaps an issue or two. I’ve not experienced nor seen this discussed on the forum so it might be problem that few know about.
Some of the things one gives up with text based configs:
lost time to fighting syntax errors
some bindings do not support everything in .things files; for example Zwave cannot set device parameters when using .things files
some bindings require a restart of OH to pick up small changes to .things files (I don’t think this has been fixed)
if you plan on using MainUI, .items files quickly become unruly with all the metadata to define units, state description, default widgets, etc.
with breaking changes (e.g. like the introduction of the unit metadata) Items and Things can be automatically upgraded where as text based configs must be manually updated
Obviously, do what works for you, but except for the last item, managed supports the same degree of versioning, flexibility is possible, and refactoring is getting better and in practice, at lest for me) occurs infrequently enough to not give up the advantages of managed configs.
Yeah, there are certainly some efficiencies with text configs (and there probably always will be). I would like to point out a few things though:
This is accomplished with equal ease with the managed jsondb files. I do it, and I know several others do as well. In early OH3 releases it didn’t quite work, but that was resolved long ago and this doesn’t really count as a difference between text and UI anymore.
Yeah, these both fall under my no very technical heading of batch editing. For those of you that do this a lot, there’s no substitute for text configs and I doubt there ever will be. I don’t do it enough for the time time saved to outweigh the other time lost to text configs.
I can see this, but again it comes up once in a blue moon for me. Z-Wave on rare occasions and once had to delete and reload my SONOS things. But, bulk delete of things in the UI and auto discovery meant that it was less than 3 minutes work to reload all the SONOS things. You’re right having it happen by default is faster, but the cost is still pretty small.
Okay, it sounds like I should have a closer look then. I’m managing things and items in text files as well, and here I can usually work on separate topics without having to manage branches and stashes, because different topics go into different files. If the jsondb files are also separated and easy to diff, then I agree there’s no advantage here.
This brings me to another concern I have, but forgot to mention: In case of jsondb corruption, is it easy to fix either by hand or using tools? With text files being line-based and human-readable, I feel insured that I can always fix things. I can also always upgrade as well as downgrade selectively (by hand), since it’s a simple matter of modifying some lines and Git history is easy to utilize because of the line-based format.
In case of Netatmo (and soon Hue), I’m only talking about things and items, since my rules didn’t change. But all channels were replaced. So I could basically copy my netatmo.things and netatmo.items files and make all the changes on the side, then swap the binding version and the corresponding files back and forth. This made it easy to test the new version in production, but quickly revert back. I’m not sure, but with UI, you could also swap two things by disabling/enabling, but wouldn’t you have to manually re-link all items each time? I have 50+ items for both Netatmo and Hue, so this flexibility with the way of managing such transitions makes a difference to me.
The same goes for the upcoming need to apply unit to a lot of items. which I have already done for all my items.
Exactly. I’m really fine with this, because it makes it possible to accomplish what I want. Even after using openHAB for years, I still find myself refactoring from time to time and renaming stuff (destroying and re-creating ). For example, I got started with deCONZ in 2021 or 2022, but as I added more and more stuff (mostly relays, dimmers, power outlets) I needed to slightly reconsider my original naming convention.
Well, there is:
and:
and (minor/cosmetic):
This sounds like a bug in the particular bindings. There was also this bug fixed in 4.0:
However, this could be worked around by renaming (e.g. things/miele.things → things/miele.things_ → things/miele.things). Annoying bug - very true!
Well, almost, but hopefully you are right when 4.0 is ready. Currently state descriptions are only picked up from the items, not from their corresponding channel types. So, for example, if you have a Number:Dimensionless channel representing a percentage as defined in the channel type (e.g. system.atmospheric-humidity), then it will not automatically be upgraded. But as said, hopefully this will be fixed. Nevertheless, you are right, for text based configs I had to do this by myself. But at least I was in full control, and could find all lines needing attention using this command:
grep "Number:" items/*.items | grep -v "unit="
Fully agreed. I knew there was a risk of getting into a long discussion over this, since this seems like a religion to some. I really just wanted to state the reasons why I personally (still) prefer files, and you made some valid points about its disadvantages that I’m also well aware of. I would not recommend files to anyone I don’t know quite well, but as a software developer I believe at least some of my points made about its current advantages are valid (i.e. with code in main branch right now).
You cannot separate them into separate files. But there is tagging for everything, order of entries are maintained, and it’s all text so it’s easy to compare with previous versions, merge, etc.
Every change made through the API results in a backup being automatically generated first. You can configure how may backups to save. Recovery is usually best handled through restoring the most recent backup.
In practice, for years now I’ve only ever seen a JSONDB file corrupted when a machine loses power while it happens to be in the middle of writing the file. But because it always takes a backup first it’s easily recoverable.
If you wanted to fix it by hand you could. Order of entries is maintained so when you make a change, just that change will appear in the diff.
Things can be enabled and disabled too. Items not so much but they don’t usually interfere with each other.
You could also work on separate branches that you swap back and forth with. I’ve done that before and it worked quite well.
Not necessarily. It depends on how you do it and set it up. If you were not going to take advantage of source control branching some options I could see include:
separate Items for each Thing (generating Items from a Thing is pretty easy in the UI)
link both channels to the same Item
Personally, I’d adjust to approach the problem in smaller pieces but I don’t know specifically what you are doing.
Except in certain cases, the Things get automatically discovered and created. There’d be no reason to have two copies of them in those cases. But, for bindings like KNX, Modbus, MQTT, HTTP, etc. where manually created Things are a thing, I could see how that might be the case.
I just looked it up and both the Netamo and Hue bindings autodiscover and create the Things. So I would argue you probably wouldn’t have two copies of these Things anyway.
And don’t discount the “create equipment from thing” option. That gives you one page, prepopulated with defaults where you can create all the Items linked to all the channels of a Thing (or a subset), situated in the semantic model all in one go. You can create a bunch of Items very fast this way.
With 50+ Items, I’m not sure I wouldn’t just delete them and recreate them if I were working with two different copies of a Thing.
The upgrade tool does this automatically for managed Items based on the State Description metadata.
That’s one of those breaking changes that can be fixed for you as part of the upgrade process when your Items and Things are managed already.
One thing I’ve discovered since moving to managed everything is that the UIDs often don’t matter. On the Things page, you see the Thing Name which you can change without impacting anything. On the Items’s page you see the Item’s Label, which can also be changed without impacting anything. In all the selection lists you see the Thing Name and Item Label as well.
About the only place where the Thing UID and Item Name matter is inside rules. And that’s a pretty important place to worry about them. But if your rules are written in a generic manner, most of the time your rules won’t have hard coded names/UIDs anyway. So even there it could be a rare case.
The point I’m making is that maybe having a slightly inconsistent or less than ideal UID/Item naming scheme isn’t the worst thing in the world. Functionally the impact is relatively minor in the UI.
The Developer Sidebar includes searching inside Item metadata in OH 4.
Indeed. I have a consistent naming scheme for all my items. But, two and a half years ago, I screwed up the name of my kitchen light with an extra caps letter. I’ve never bothered to go back and fix it because it doesn’t negatively impact anything at all.
Just to be sure: Wouldn’t that be with default auto-generated item names? All things and items are generated with names and labels very far from the naming I would normally use, especially for localized bindings, since I use English (and conventions) for my naming. Example:
This is really awful, but perhaps I’m missing some options where this behavior can be configured? I would name that item Indego_TextualState and leave the label as suggested.
See my previous reply, this won’t fully work. But to be fair, the process is partially automated for managed items and fully manual for unmanaged. For managed items you could also add unit metadata in advance to have a smooth upgrade to 4.0.
Can it also find all items of type Number:<dimension>without unit metadata, like my command?
You can override all the settings for each Item individually if the defaults don’t work for you. Even in cases where I override everything, I find that page to be about as fast as defining them in text files.
Notice I said “create equipment from thing”. This part is important because this also creates the Equipment Group and the default names of the Items come from the name of that Group plus the Channel name.
So if you touch nothing, the name of the Equipment will be the same as the name of the Thing. But this is easily overrideable.
The names of the Items are generated from the name of the Equipment and the name of the Thing’s Channel it’s linked to.
Then change the name of the Equipment to “Indego”. If the use of “_” instead of camel case, you’ll have to edit the Item’s name to remove it.
If you use “add points to model” instead of creating the Equipment you can choose the already existing Equipment or Location. And then again, the Item name will be based on the selected Equipment’s or Location’s name and the Channel name.
In my experience, if you are going to use the semantic model at all, this is the only way to populate it with Items. It’s actually easier to recreate all your Items this way than it is to retrofit the semantic model to an existing set of Items either through text based configs or the UI.
I don’t know. I don’t know if the search is just a String or a regex. But you can search inside the JSONDB metadata file. This feature is brand new in OH 4 so I would expect it to get better over time. There is no reason why it can’t be made to support a search like that.
I’m not arguing that managed stuff is going to do everything better or the same as text based configs. Clearly there will be some things that are better in text and others that are better in managed. However, I do find that far too often those who advocate for text only, often out of ignorance, under appreciate what can be done through managed Items, Things, and Rules.
Far too often I see statements like “I use text configs because they can be checked into git and backed up.” Well, managed can too.
Or “I can separate my stuff into different files for better organization.” Indeed you can’t do that with the UI but you can tag stuff and use the search on the Things, Rules, and Items page to show only those with a given tag. You can use the developer sidebar to pin those Things, Rules, and Items that are related to what you are working on so you don’t have to go back and search for them again or have a dozen tabs open on your window. If you are working with MainUI, having separate files for this stuff is irrelevant.
Using managed stuff does take a change in how you approach organization and configuration. That may not be worth it for some users and that’s fine. I don’t really care whether people use text based configs or not and I will defend that choice if it’s an informed choice (I don’t help with syntax errors in text based configs on the forum any more though, I’d rather spend my time solving home automation problems, not syntax errors).
But I do care if people are making that decision based on false information about what can be done with managed entities and the UI. Users like @JustinG, @hmerk, most of the developers, and myself would not be using managed if there were not some advantages and the drawbacks were too severe. MainUI is not PaperUI (which was barely usable).
And again, I’m not trying to convince you personally to use managed anything. But I want to make sure you and more importantly future readers of this thread understand what MainUI is and is not capable of as of this writing so that it’s an informed choice instead of based on false assumptions.
). For example, I got started with deCONZ in 2021 or 2022, but as I added more and more stuff (mostly relays, dimmers, power outlets) I needed to slightly reconsider my original naming convention.
I really just wanted to state the reasons why I personally (still) prefer files, and you made some valid points about its disadvantages that I’m also well aware of. I would not recommend files to anyone I don’t know quite well, but as a software developer I believe at least some of my points made about its current advantages are valid (i.e. with code in main branch right now).
