Usability suggestion: More hints and examples in the OpenHAB3 UI

Is contextual help to the GUI a feasible goal in Openhab 3? I see this pattern of help in pfSense, FreeNAS/TrueNAS and other successful open-source projects (Especially GUI front-ends for famously hard back-ends such as pf, zfs etc.). It seems like a no-brainer to bring these good ideas to OH in the form of help hyperlinks at the top of pages, and/or a (?) icon button near each GUI element to be filled out with examples/concepts etc…

No surprise, OH3 is a big improvement over OH2 in terms of ease-of-use. IMO the word that best describes the difference is ‘discoverable’. In OH3, one can largely discover how to achieve the addictive ‘hello world’ moment in the UI, and then add/learn incrementally, enabling repeated success and repeated rewards with small gains (keeping the process addictive to new users). OH2 of course had too much prerequisite knowledge to get started, turning off new users. Kudos to the OH team for this progress!

That said, the thing I keep wishing for as I discover OH3 is better contextual help, and more contextual examples and contextually significant concepts (As a supplement to OH guides/tutorials, and big-picture concepts). For example, as an OH noob, it was not clear to me that you can make item labels contain item variables. e.g. label=“My String Value is [%s]” or label=“My float Value is [%.1f]”. It’s a painfully simple idea, but you can’t search or ask a question about something you don’t know exists. Yes, it’s documented “on the Internet”, but how much aggravation and hair-pulling could have been saved with the right contextual example?

To this end, as I dig in to OH3, I’m happy to make specific suggestions, and offer my help in writing contextual help wording (in English) for such things (assuming it can be incorporated in a contextual and usable way).

Just a trivial example:
Hints in the GUI would have been very helpful while I was setting up an HTTP thing (and its links & channels). For example, after figuring out that I needed a Regex transformation service to parse the endpoint’s response, the regex transformation UI element showed a nice example of matching a temperature with a regex: .=(\d.\d*).*
Great. However, it was unclear that THIS was also the correct place to cast a string into its correct decimal precision, and that sed-style substitutions were even allowed: e.g. s/.=(\d)(\d$)/$1.$2/g
It’s not self evident for a transformation called REGEX (versus being called SED), nor is it clear exactly which character classes are supported.

I think it’s safe to say that noobs, particularly OH noobs that are NOT simultaneously technical noobs are in a good position to know when and where hints and examples can be productive to help/retain new adopters. Of course the goal is to keep the pain threshold low enough for continued interest so that OH can compete for new adopters interest.

FWIW: I’m a new user of Openhab, but I’ve bee following IOT and following OpenHab since Kai first talked about it in 2014 on the FLOSS podcast. The OH architecture is pretty brtilliant IMO.

Fully agree with your analysis. I am a newbie too and have absolutely no idea about programming (albeit in the past I did play around with Pascal and … well…who remembers Simon’s Basic on the C64?).

I find that there is a a wealth of information and most probably the solutions to all my issues or ideas, however not being contextual I can make little use of it.

Having said that I am not letting go, I need Domotics to manage a number of issues in my house and above all it’s a nice and rewarding hobby.

1 Like

I don’t have a whole lot to say against the suggestions except to say that it would be a gigantic effort to make it happen. In many ways, openHAB is an order of magnitude more complex compared to pfSense, FreeNAS/TrueNAS/OpenMediaVault (I’ll add one to the list). In those cases you are pretty much just configuring a relatively limited set of services, some bundled and others separately installable. Looking at the list of plug-ins for pfSense there are maybe 50 in total (I didn’t count, just a thumb in the air).

openHAB, on the other hand, is a full up development platform. You are not responsible for building a UI for the members of your household to use to interact with pfSense. FreeNAS doesn’t provide a full event based programming environment where you can define something to happen when something else happens, but only on weekends after 10:00 am as a normal and basic function. And openHAB has somewhere around 350 supported add-ons, at least an order of magnitude more compared to the other listed projects.

And then there is the problem for what makes sense. Take your trivial example. The root of that confusion I think is mistakenly equating SED for Regular Expressions. openHAB does not support SED. But it does support Regular Expressions (REGEX). Those substitutions are a core feature of REGEX that both openHAB and SED can use. And given that is standard REGEX syntax no matter where you are using it (you can use that syntax with grep too).

And then the question raised, is this the correct place to round the string to the correct decimal place? I’m not sure that it is. It is usually better to leave the full precision of the number and just round it when showing it on a UI to a human using a String formatting in the label. Or even better would be to us a JavaScript transformation to actually round the number instead of truncating it.

Next we have the complexity added by the fact that we actually have here two separate add-ons interacting, the HTTP binding and the REGEX transformation. You don’t really have that in something like pfSense where if two plug-ins do interact, it’s because they are very closely related. In OH any transformation add-on can be used by any binding. Any profile can be used on any Link. Rules are fully fledged coding so pretty much anything is possible there including interacting with Items, Thing through Actions, and transformations too.

That’s all just setting the scope for the effort though. On top of that we have some practical issues:

  • Who is responsible for writing these examples and additional help? Who is going to have both the time and the willingness to write all these helps? We don’t even have enough volunteers to write the base docs right now.
  • How’s it going to work technically? There is currently no API and no direct support in the software to support this. Who’s going to write that? There has to be some way for the core to provide this information and the UI has to have a way to query that for the right information given the context.

Over all this is a lot like the requests to build a database of all supported devices. It sounds like a great idea and indeed it would be very useful. But the amount of effort to even begin to implement something like this is vastly underestimated to the point where, in my opinion, if we start now we would never actually be able to catch up.

Unfortunately this is a problem that can’t really be solved. If we simplify and say that “context” is just the specific combination of add-ons you have in installed. Which of the 350! (factorial, which calculates to something like a 3 with 750 zeros after it) is your specific context? There are more combinations of just add-ons that can be installed on OH than there are grains of sand on the planet. And that doesn’t even bring into consideration Things, Items, Rules, etc.

Everyone’s home automation is completely unique, even more so than most any other product you may encounter (e.g. those listed above). So it’s pretty much impossible to present things to each and every user of OH “in context”. Instead, what we can present and which we do present, are isolated “here’s how to do X” type docs and tutorials. But it’s up to you to identify whether and how that context presented differs from your own and adapt it accordingly.

Want an MQTT tutorial? We can do that and get you up and running on MQTT. But that’s not going to show how to write a rule to process the data. It’s not going to show you how to chart the data as it comes in. It’s not going to talk too much about how to transform the data using XSLT (one of the many transformation add-ons one can use). So you’ll need to find a different tutorial for each of those and string them together to reach your end goal.

Like it or not, that’s just the way it is.

I might be wrong and someone may have a brilliant idea and the ability to make the changes to the system to achieve that idea. But so far, my experience tells me that is not likely.


Thanks for your thoughtful reply Rich. Also, thank you for your many contributions over the years.

I agree completely that a FreeNAS file server and/or a pfSense Router/Firewall have are much more constrained worlds, that is, they have enormously simpler/smaller universes to document and describe than OpenHAB does (i.e. OH is far less constrained, and far more complex).

My thought is that this could be a case where an optimal solution (like you’ve accurately envisioned) could stand in the way of a much, much simpler sub-optimal solution which could nevertheless result in a dramatic reduction in the initial steep learning curve of OH.

There is of course already some contextual help right in the GUI in the form of prompts/hints. :slight_smile: Some even have short code examples in the prompts. Of course this is proper and and necessary, but obviously not the right place to write more than a single line of description (even if a long description would be helpful or desirable). I happen to have authored the pfSense description/prompt for the DHCP server option ‘Ignore client identifiers’. I can say that it was virtually an impossible task to describe the purpose of the simple checkbox without including paragraphs on the underlying issue that the checkbox addressed.

We see large companies do research on hurdles to new-user product adoption to improve documentation, adoption and training. It’s obviously an idea with a track record of good return on investment. I could envision contextual help for OH idealy being less than perfect, non-exhaustive, and not a replacement of any other documentation, favoring instead the goal of getting people hooked on a functional stub of a solution that will serve to motivate their future investment in OH (e.g. so they go on to create the UN-documentable long-tail applications).

To your important questions of how and who, let me try to take a swing at it:

As to the how: It could imagine high payoff from something as simple as the existing per-binding GUI elements holding hyperlinks to per-binding pages in the existing documentation framework (e.g. for more verbose descriptions about each of the GUI elements, possibly with some related concepts and examples where appropriate, even if just the bottom of the existing documentation page).

As to the who: I can say personally, after I spent hours in several places trying to understand what it was that I didn’t actually understand, I would have GLADLY offered some doc on the concepts I thought needed to be shared in those places. Moreover, I would say that I (and people like me; new to the platform) are in a special position to identify places where people commonly get stuck. In any project, there’s the risk of people deeply involved becoming so familiar with it, that they lose the ability to identify the would-be pain points of adoption, contributing to hurdles that keep out adoptees. I know I’m guilty of this in my professional life. Soon I too will be one of the people deeply involved and familiar with this project, and I too will lose my ability to see old pain points because they will seem familiar and self-evident.

With regard to Rich’s point about casting, I agree with the philosophy. Even though I was in fact attempting to grab all of the precision offered, even so, what Rich said it’s a great example of a contextual hint that a noob could benefit from (even just as written). I would also say that even If that same philosophical idea were in a perfectly-written best practices guide (or in a post like this one), a noob wouldn’t be nearly as likely see it at the right time in order to benefit from it.

In any case, thanks to everyone for letting me bend your ear on this. Obviously OH3 was a gigantic undertaking, precisely in service of many of the same priorities I’ve nattered on about in this post. As I see it, now that that this new foundation has been laid, the marginal ROI of contextual help seems higher than ever.

Regards from Chicago und auch Neuss!