Generic vs descriptive UI configuration

[sven1234 (Sven)]

Some time ago I filed an enhancement request to offer more input fields in the UI in order to ease users entering data.

E.g. for knx channels one has to use

1/1/20+<1/2/20

The first address is the actual GA to e.g. switch an actor. The second is the status GA. How would a new user know this syntax? Only by reading the docs. It is not intuitive although it could be.

IMHO it would be a lot easier for users if the UI would show more input fields with meaningful titles. E.g.

Group address: 1/1/20
Group address status: 1/2/20 or Plus separated list of GAs to listen to:
[ ] pull status information in startup phase

No reading of the docs needed because it is intuitive or rather descriptive.

However, I was told that this kind of UI is unlikely to happen because it is not possible since the UI configuration is built in a generic fashion. So to me this sounds like for the openhab project it is impossible to strive for a more user-friendly UI.

While for me this is something which just adds some searching and reading - for many other users this means that they will never get access to openhab and give up because it is too complicated for them. Since I like the openhab project, somehow I wish that more people start using it. So everytime I come across “generic UI” issues, like the one decribed above, I ask myself whether it is really that bad to make openhab easier to use.

A bit exaggerated maybe, but to me it seems like there are aspects of a RTFM philosophy (which I tend to promote myself) even for situations that could easily be more descriptive/intuitive.

So could somebody please explain to me why openhab must not strive to make the configuration UI as descriptive as possible?

[hmerk (Hans-Jörg Merk)]

I would not name this a general UI issues, but rather a KNX specific one.
Have a look at the bindings available, where many are really easy to setup, providing auto discovery and automatic channel creation.

[JustinG]

@sven1234

So could somebody please explain to me why openhab must not strive to make the configuration UI as descriptive as possible?

I really don’t see this issue as being quite so black and white. We all benefit from increased adoption of openHAB and all want to see more smart home users. I totally agree a big step there is making the UI appealing to as many people as possible. But, off the top of my head I’d say there are some things that need to be balanced when considering this particular point.

Who would populate this additional information? Binding creators already make the binding and create the help docs, are we expecting them to duplicate some of that effort just to put info from the docs directly in the UI? We want to encourage binding creation not make it more onerous.

Where’s the line between input description and help doc? As hmerk said, there are a lot of bindings out there where the setup is beginner friendly and nearly fully automated. I don’t use knx, but from what I’ve seen over the years it is not really a beginner kind of system and if you are gong to use that you had better be the kind of person that’s going to read the docs. If you don’t want to read the docs and understand the syntax, then maybe you need to pick a different system. I’m not saying that help with configs should be completely forbidden. Everyone here knows the complaint that smart home systems just aren’t user friendly enough for beginners, but isn’t that a really misleading oversimplification? Some smart-home systems are nearly one-button simple for setup and 90% fool-proof, some systems are…well, not. I’m not sure it’s the domain of OH UI maintainers, or the forum users, or even the binding authors to hold someone’s hand if they want to jump in at the deep end without swimming lessons.

Maybe there’s some compromise that works. For example, is it possible to have a context aware help button on the channel config page that takes you directly to the correct binding help doc? That requires nothing on the part of the binding authors, allows people quick, intuitive access to the information they need, and (perhaps best of all) begins to habituate new users to checking out the help docs.

[mstormi (Markus Storm)]

As well commented, there’s a thin but important line between what the system (and its UI) provide and what the user must bring in to the game.
I don’t use KNX either but ZWave. A zwave thing in current UI is a good example of what you can do in OH and its UI today, it has a device specific help description below every parameter input field.
BUT this requires a TREMENDOUS amount of preparatory works and maintenance. The database of ZWave devices to contain all of these descriptions is filled by users, kept outside the OH project and has matured in years of use. There’s no KNX community in sight to provide the same and no interest among KNX vendors to support OH so it won’t happen.

Yes there’s always room for possible improvements such as @JustinG ‘compromise’ suggestion to have a link into the binding docs or to have some such extended help text below a field to explain its syntax like with zwave, but short of that, the default remains to be a) understand the technology you’re dealing with and b) RTFM to understand what you have to enter in a field.
For some technologies that’s either not needed because that system is so simple or there’s advanced in-tech features available like autodiscovery, but for complex tech and tech that doesn’t provide these capabilities like KNX, user education is the only way and it remains to be the user’s duty: you can well be and so you are expected to read and understand the docs. No help text, feature or developer can and will do that for you.

[rlkoshak (Rich Koshak)]

I want to approach this from a slightly different angle because I don’t really have anything more to add over what’s been said from the current angle. To some extent, some technologies are going to take more RTFM than others due to the very nature of the technologies. If you’re gonna use KNX, modbus, MQTT, HTTP, Serial, Exec, and other low level bindings, you will not be successful without referring to the manual. There might be some things that could be done in the UI to make using them slightly easier but ultimately you can’t get away without an understanding of how the technology works and how OH interacts with the technology which requires reading the docs. But these types of bindings make up a small minority of OH bindings. Most don’t require any configuration at all. Just install the binding and discover the Things. That brings me to my point.

Please don’t discount how much has already been accomplished in making OH easier to use.

We’ve gone from a situation where everything had to be manually configured using arcane text based configs (each binding had their own specific and often inconsistent syntax) split between two or more separate text files (openhab.cfg and the .items files) to the ability to simply scan and discover new devices and have them added and configured for use in OH with a few button clicks.

Even for those bindings that do require a good deal of manual config because discovery is not possible, the overall approach to configuration is the same across all bindings. And most of the time not only is the information to be entered for the config usually pretty intuitive there is usually a good set of inline docs further explaining each field. I know of only two bindings (KNX and modbus) where, due to the nature of the technology, that a lot of specific knowledge about individual devices is absolutely required.

We’ve gone from basically no UI based configuration what-so-ever to a unified UI for both admin and end use. A UI capable of managing almost anything that can be configured in OH (the few exceptions are being actively worked).

We’ve gone from absolutely no reuse to having a Marketplace where you can just download and use not just bindings, but rule templates, Blockly libraries, and MainUI widgets.

We’ve gone from one main rules language with limited support for common programming concepts like functions and libraries to support for more than half a dozen different “modern” programming languages, including Blockly which is a graphical programming environment often used to teach children how to code (hard to get easier than that).

So I push back strongly against the notion that the developers of OH don’t care about making OH easier to use. They have and they continue to develop and refine OH to make it more capable and easier to configure and use with each new release.

It just seems in this one particular case though that the developers have pushed back against the amount of time, effort, and disruption required to make 1 or two out of >350 bindings easier to use. Especially since, based on what I can gather from the original post, the KNX binding author could probably do a whole lot on their own to make the UI easier for end users to use without requiring changes to core that will impact all the other bindings in the process.

There is nothing preventing the binding author from breaking that channel config string into multiple fields with meaningful names and informative descriptions (to merge it back into the string KNX needs internally). I don’t think the UI and/or the binding would support “pulling the status information in startup phase” but that doesn’t mean nothing can be done to make it easier. While the UI is built in a generic fashion using XML files, those XML files that create the forms are written by the binding authors.

[sven1234 (Sven)]

@JustinG

I don’t use knx, but from what I’ve seen over the years it is not really a beginner kind of system and if you are gong to use that you had better be the kind of person that’s going to read the docs. If you don’t want to read the docs and understand the syntax, then maybe you need to pick a different system.

I think this mixes two separate aspects. KNX might be a bit more complicated to set-up (the ETS part) - but creating a GUI for a once set-up system should not be. openhab is not used to set-up KNX but to represent the system and add some extra intelligence.

On the other hand, you are right that I did not have a look at a lot of bindings and they might be a lot more intuitive to connect to an existing system. But to get this discussion off the knx binding: Why do users have to learn something like:

=(items.yourItem.state == "ON") ? "green" : "red"

instead of a colour picker for each state?

Why do users have to know the icon names (or try every letter, or search for the list in the docs) instead of getting a pop-up and being able to browse the available icons, e.g. in the item config or the cell config.

Don’t get me wrong, I am not demanding that anyone invests his spare time in generating that functionality. I just feel that it is not wanted, even if somebody would do so. Probably a wrong impression.

@JustinG

Who would populate this additional information? Binding creators already make the binding and create the help docs, are we expecting them to duplicate some of that effort just to put info from the docs directly in the UI? We want to encourage binding creation not make it more onerous.

Ideally no docs are needed because an UI is intuitive. Not sure whether there are actually docs for the most widespread apps on Android or iphone, or even Android or iOS themselves. So I would turn this argument around and say: docs are only needed if the GUI fails to be sufficiently descriptive and intuitive. Save the time invested in docs and invest it in usability. Concentrate the docs effort on those topics where the GUI cannot be made more descriptive/intuitive.

@rlkoshak

There is nothing preventing the binding author from breaking that channel config string into multiple fields with meaningful names and informative descriptions (to merge it back into the string KNX needs internally). I don’t think the UI and/or the binding would support “pulling the status information in startup phase” but that doesn’t mean nothing can be done to make it easier. While the UI is built in a generic fashion using XML files, those XML files that create the forms are written by the binding authors.

That is what I thought but the impressio I got from the anwers to the enhancement request was that improving would need some changes to OH core and not just the binding.

Getting an UI from the semantic model and having an UI to configure instead of the text definitions is definitely a huge step towards including a lot more potential users - which are interested in tech but not willing to use text but an UI. In fact the latter reminds me of my experience with Windows vs. Linux users. While the latter feel comfortable using the console, the former are as interested in learning but not in using any text-based tools. Having to enter =(items.yourItem.state == “ON”) ? “green” : “red” is equal to having to use a console or text based definition/config. Even the registry in Windows is edited with an UI. Maybe a bit too black and white but I hope you get what I mean.

So thanks to everyone for the insights. While I do not agree with everything, you can be sure that I do appreciate the work and effort put into OH. And I will take the UX enhancement requests to the knx binding since I understood that even without changing OH core functionality there is still a lot of room for improving on the config dialogues.

[rlkoshak (Rich Koshak)]

@sven1234

That is what I thought but the impressio I got from the anwers to the enhancement request was that improving would need some changes to OH core and not just the binding.

Just be careful what you’ve asked for and what they replied to. If you’ve asked for some way for the binding to somehow query for all the devices so you can get a drop down list to choose from when configuring the Things, well that’s not going to be supportable without lots of changes to OH core.

But if you just want something easier to enter in the configuration form, perhaps by splitting that X/Y/Z type string up into separate fields, that is something that should be doable.

But it’s of the utmost importance to understand that OH is 100% volunteer effort. Nothing gets done unless someone volunteers their time and effort to implement it. You can have the best idea in the world but if no one volunteers to implement it nothing is going to happen.

[mstormi (Markus Storm)]

@sven1234

Some time ago I filed an enhancement request to offer more input fields in the UI in order to ease users entering data.

I didn’t find that on Github. Please refer us to that.

[sven1234 (Sven)]

Sure: [knx] add dedicated input field for status GA · Issue #11784 · openhab/openhab-addons · GitHub

[mstormi (Markus Storm)]

That was not on UI but on the KNX binding and Kai asked you to open an issue against the UI.
Since you only pointed us here I assume you did not do that.

@sven1234

Don’t get me wrong, I am not demanding that anyone invests his spare time in generating that functionality. I just feel that it is not wanted, even if somebody would do so. Probably a wrong impression.

Github issues are not a wish list for end users.
As @rlkoshak commented, be careful what you’re asking for.
As Kai explained, your primary request was on something that was in conflict with how OH works in principle. Asking to change that for (mostly) the benefit of people too lazy to read the docs on some tech that you really should be knowing before you use it in OH has … well, a very bad effort-to-benefit ratio, plus a number of drawbacks. That’s not convincing.
Kai also said AFAIK links to docs cannot be done in the UI so it does not mean it cannot be done. So if you went ahead and contributed code that does not violate the OH architecture such as the XML idea @JustinG and @rlkoshak proposed, I’m sure it would be happily accepted. Not fair to claim anything different ahead of time, even more so when you didn’t try.
But without any code offering or at least a well-scoped request it’s just asking someone to spend (a lot of) his spare time for your benefit. And for that to happen, you have to be a lot more convincing.