Consistency needed for widespread adoption of OpenHab 2.0

I am for years a happy user of OpenHab 1.x. Now it’s holiday season so I decided to check out the state-of-affairs of OpenHab 2. I downloaded build #447 from Cloudbees and started to tinker with it.

I checked out the following Bindings. Astro, NTP and Weather.

What I found out that, although they are all officially bundled with OpenHab2 as a compatible addon, they function differently when it comes to configuration. An overview:

  1. Astro
    After Install two Things appear in the Inbox. Local Sun and Local Moon. In the Thing panel of PaperUI you can activate the right channels. In my case SunRise#start and SunSet#start. In the .items file I use them as such:
    DateTime Sunrise_Time "Sunrise [%1$tH:%1$tM]" { channel="astro:sun:local:rise#start" } DateTime Sunset_Time "Sunset [%1$tH:%1$tM]" { channel="astro:sun:local:set#start" }

  2. NTP
    After Install the NTP Thing appears in the inbox. In the Thing panel of PaperUI you can activate the ntp:ntp:local:dateTime channel. But in my code the following did not work, although there are several examples to be found stating that it should.
    DateTime CurrentDate "Date [%1$tA, %1$td.%1$tm.%1$tY] {channel="ntp:ntp:local:dateTime"}
    Instead I had to use HABmin (because PaperUI doesn’t allow me to) to Link the channel to the variable definition:
    DateTime CurrentDate "Date [%1$tA, %1$td.%1$tm.%1$tY]
    BTW. this works also not completely right since the formatting is gone when NTP updates the variable. A refresh of the screen resolves this again.

  3. Weather
    After install NO thing appears in the Inbox. In the error log you see this is because there is no config file found. So I created a weather.cfg with the following contents:
    location.home.woeid=15005030 location.home.provider=Yahoo location.home.language=en location.home.updateInterval=10
    Actually a Thing should have been created that let me type in the above as parameters to be consistent. In the .items I can now use the following syntax:
    Number Weather_Temperature "Temperature [%.1f °C]" <temperature> (Weather) {weather="locationId=home, type=temperature, property=current"} Number Weather_Humidity "Humidity [%d %%]" (Weather) {weather="locationId=home, type=atmosphere, property=humidity"}

So what is the conclusion of this? Every add-on/binding has a different way of configuring itself. Parts in the UI and parts outside of it. Also in the Field definition we are not consistent. Sometimes referring to a channel. Somethings Linking to a variable through another UI (Habmin). Sometimes using the old OpenHab 1.0 syntax and directly referring to the add-on because there is no Thing in between.

We need consistency. Without consistency everybody will get annoyed and stops using OpenHAB2.0 which I think is not what we want.

Maybe we need a certification or process in place so that when an add-on is packaged with OpenHAB2.0 it is:

  1. Installable via the UI

  2. It creates Things

  3. Things can be configured in the UI (channels visible, parameters are configurable like updateIntervals, URL’s, etc.)

  4. One way of referring to a Thing in an .item definition. Either via the channel syntax. Or by Linking in the UI. I don’t care which one as long as we do it all the time in the same way.

Consistency and predictability will help people understanding the platform. Accelerate its adoption and make it a success. Please let me know your thoughts.

Regards,

Mario

2 Likes

There is a difference between 1.x bindings running through compatibility layer and native 2.x bindings.
As for the Weather binding, this is a 1.x binding, so you have to use config files, like running openHAB 1.x.

The consitency you are asking for is already in place.

  1. Bindings tested as compatible with openHAB 2.0 are made installable trough PaperUI
  2. Native openHAB 2.x Bindings create things after the according devices are discovered. Note, not all devices support auto discovery.
  3. In general, things are configurable through UI.
  4. As there are differences between 1.x and native 2.x Bindings, the item definitions cant be the same, but you can link your items to the specific channels in your .items definition.

Thank you Hans-Joerg for your reply.

So you say that this inconsistency is okay? We have 1.x bindings that need manual configuration (even though it is not clearly stated that this is a 1.x binding). We have native 2.x bindings that do things through the UI. And we have in-between bindings that do half UI and half in a .item or .cfg file.

There are two ways to solve it. Either make it consistent or clearly mark a binding as 1.x or in-between and make sure there is a good manual with examples on the web. Something I accept in a beta-stage is trailing behind.

Maybe we have to wait on a final position in this discussion https://community.openhab.org/t/oh2-ideas-to-help-advanced-users-to-create-config-files/12284 as well.

Can you tell me, which binding is not shown with it’s version in PaperUi?
If it is shown with 1.9, it is a openHAB 1 binding, that needs old configs. Version 2.0 indicates a opnHAB 2 binding, and 0.9 an ESH binding, that is configurable through UI.
I can not see your point here.

Hello,
while your reasoning makes total sense, I can follow Marios concern:

How would a user ever know that? It’s totally normal for software components to have unrelated version numbers. The fact that one addon has version number 1.9, another 2.0 is a technicality without intuitive meaning. When did you last check the version number of your browser addons?

I would agree, that this lack of clarity creates the impression of inconsistency.

Continuing the conversation: @sourceror did you know / do you think it is enough that every user can find out about OH2 bindings and compatible OH1 bindings through docs? http://docs.openhab.org/addons/bindings.html / http://docs.openhab.org/addons/1xaddons.html
Is more clarification needed in this part? Where and how? How would you imagine to “mark a binding as 1.x”?

I understand we have an inconsistency because we want to cater for three things, being new 2.x add-ons, old 1.x add ons through the compatibility layer and power-users that want to do things through text files.

Currently it is not visible in PaperUI and HABmin what type of add-on/binding we are installing or have installed. In my case I see this.


Notice in the Binding overview the Weather binding is missing.

An easy way to solve this is to mark 1.x add-ons as “classic” add-ons. Also I think it would be helpful if there would be a link to the corresponding doc page on the web per item in the Extensions (before installing) and Bindings (after installing) overview. There a user would find additional instructions and a description of the binding.

It could just be added to its parameters like currently the name of the author and name of the binding.

It is reasonably visible in the extensions list in recent versions of HABmin -:

Note that in the Bindings configuration, I think you will only see OH2 bindings listed.

Yes that looks like it. Clearly visible.

If we could, in this overview, also add a button, per binding, to the webpage describing what the post-install steps are. This would make it much easier for the beginner/novice.

For example this one for the Astro binding: link.

PS. looks like I have to upgrade my HABmin :wink: I don’t have this version it seems.

I agree, but this information needs to come from somewhere and I don’t think it’s available at the moment. My preference was to have the readme available in the binding, but that’s not where we ended up. So, we have to link to docs (somewhere), but I’m not sure if we can derive the URL from the binding name and know where to point the browser as the information isn’t available in the REST. Trying to guess this sort of thing, and only having it work some of the time, is probably worse than not having it (IMHO anyway).

I also agree that there should be a documentation linked to every binding.
While there might be some legwork needed, I think the documentation URL can be derived easily when knowing the “binding.id” of the binding:

https://raw.githubusercontent.com/openhab/openhab-docs/gh-pages/addons/bindings.md

However when looking at OH1 bindings documented in the wiki or special addons like the z-wave binding, it would probably be best to have a URL to the documentation in the properties of each binding. Adding the README directly to the binding and presenting it inline when wished for is also neat. Why didn’t we “end up” there?

These two features (visually distinguished OH2 vs OH1 bindings, documentation links) should be available in PaperUI as well.

Yes - it does look like this should work.

Of course ZWave isn’t in the list at the moment, but hey-ho… That’s another thing to sort out…

One other point while we’re discussing this. The method I used to detect the OH1/OH2 versions will likely stop working, and that’s due to ESH versions. Currently ESH bindings are version 0.9, so I can distinguish them as well - when ESH goes to version 1, it might get a bit more blury… I can use the sub version as well, but it’s still a bit of a hack and probably should have more information in the REST interface if we really want to do this properly.

I don’t see, why it would not be anything but beneficial to have more metadata for add-ons.
Concerns would be to have a clear defined set of properties and options and to “enforce” these on add-ons developers…

I’m thinking about this document the whole time, so why not post it here: https://getcomposer.org/doc/04-schema.md

After a bit of a look at this, it’s not really ideal. The binding id isn’t (directly) available in the extensions list - it can be derived, but deriving information is prone to error as it relies on naming conventions not changing and having dealt with the hassle of ESH thing naming conventions changing, I’d not recommend this as a long term solution…

All this information should be contained in the binding XML file if it were added, so it would be mandatory or the binding wouldn’t compile/run. So, I don’t think enforcement is a concern - the issue is probably agreeing what to add as it would need to be mandated by ESH ;).

Exactly what I was talking about. Ideas could be taken from the composer definition. Things like docs and homepage URL might be just as useful as a license or taggings
Maybe a new thread should be opened on this topic.

It would need to be discussed in the ESH forum.

Would you be interested in doing so @chris ? I have no add-on development experience.

Doesn’t Habmin vs Paper UI just add to this inconsistency the trhead stqrted with? I am an OH1 user and fiddle about the best I can.

I have tried a number of times to migrate to OH2 but find that I get to a point and go “nup don’t get it”, or “ah it doesn’t do that yet” to the point where I go “why would I want to migrate yet - what am I gaining but the pain of migrating”

Ive looked at Habmin and sory but don’t get it’s purpose - there seems to be cross over of features to paperUI, some features that should be in paperUI etc.

I’m just a bit confused and will keep reading and not migrating for some time yet I think.

I like it.

The composer definition or elements of it would certainly enrich the binding overview. It’s like installing an App on your mobile phone. When you do that you have a description, authors and a link to the website of the maintainers with follow up comments/information.

And yes, it’s best not to derive from a version number. Better to have an explicit element in the definition that says if it’s a legacy/classic add-on or a 2.x one.

Why?

That’s correct - the same as there is crossover between other UIs (BasicUI, ClassicUI etc). HABmin is a bit more targeted at ZWave and has extensions for ZWave, and you need to remember that PaperUI comes from ESH so has its own requirements there.

It’s just a case of different UIs and you can install either one or the other, or none. If we all wanted the same look and feel, and ran the same bindings, things would be easier for everyone, but life would probably be more boring ;).