Allow dynamic documentation properties for binding

[stefan-hoehn]

Currently there is one shortcoming that bundle information seems to be completely static. The documentation for a bundle can be for example looked up in PaperUI. However, sometimes the bundle itself likes to provide some information to the user related to the bundle itself which might be helpful for the user or the development community in case of issues.. In particular it is useful for support purposes.

An example would be presenting the build version of the bundle to know exactly what version a user is running without using advanced tools like karaf... as mentioned and described in the following thread:

https://community.openhab.org/t/solved-how-to-detect-exact-bundle-version-via-api/92375 (in this case I expose that through the thing but not the bundle information).

Therefore I would propose to add properties to bundles similar to what things have.

What do you think?

[J-N-K]

The problem with displaying the version is that there might be several bundles within one add-on:

Feature openhab-binding-mqtt 3.3.0.SNAPSHOT
Description:
  MQTT Binding
Feature has no configuration
Feature has no configuration files
Feature depends on:
  openhab-runtime-base 0.0.0
  openhab-transport-mqtt 0.0.0
Feature contains followed bundles:
  mvn:org.openhab.addons.bundles/org.openhab.binding.mqtt/3.3.0-SNAPSHOT start-level=80
  mvn:org.openhab.addons.bundles/org.openhab.binding.mqtt.espmilighthub/3.3.0-SNAPSHOT start-level=81
  mvn:org.openhab.addons.bundles/org.openhab.binding.mqtt.generic/3.3.0-SNAPSHOT start-level=81
  mvn:org.openhab.addons.bundles/org.openhab.binding.mqtt.homeassistant/3.3.0-SNAPSHOT start-level=82
  mvn:org.openhab.addons.bundles/org.openhab.binding.mqtt.homie/3.3.0-SNAPSHOT start-level=82

In general all of these bundles have the same version, but in some cases, even non-openHAB bundles are part of the feature:

Feature openhab-binding-xmppclient 3.3.0.SNAPSHOT
Description:
  XMPP Client Binding
Feature has no configuration
Feature has no configuration files
Feature depends on:
  openhab-runtime-base 0.0.0
Feature contains followed bundles:
  mvn:org.igniterealtime.smack/smack-extensions/4.3.3
  mvn:org.igniterealtime.smack/smack-experimental/4.3.3
  mvn:org.igniterealtime.smack/smack-im/4.3.3
  mvn:org.igniterealtime.smack/smack-tcp/4.3.3
  mvn:org.jxmpp/jxmpp-core/0.6.3
  mvn:org.jxmpp/jxmpp-jid/0.6.3
  mvn:org.jxmpp/jxmpp-util-cache/0.6.3
  mvn:org.minidns/minidns-core/0.3.3
  mvn:org.bouncycastle/bcprov-jdk15on/1.69
  mvn:org.igniterealtime.smack/smack-core/4.3.3
  mvn:org.igniterealtime.smack/smack-sasl-javax/4.3.3
  mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.xpp3/1.1.4c_7
  mvn:org.igniterealtime.smack/smack-resolver-javax/4.3.3 start-level=80
  mvn:org.igniterealtime.smack/smack-java7/4.3.3 start-level=80
  mvn:org.openhab.addons.bundles/org.openhab.binding.xmppclient/3.3.0-SNAPSHOT start-level=80

What would be the correct version to display and how should this be detected in a generic way?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stefan-hoehn]

I never got the difference between a bundle, addon and binding. Is this somewhere explained?

Bundle: Osgi explains it as "Each bundle is a tightly coupled, dynamically loadable collection of classes, jars, and configuration files that explicitly declare their external dependencies (if any)." Addon: Any dynamically installable functionality that can be installed for openHAB (my most probably incomplete definition) Binding: A specific addon that allows to connect hardware and online services (that's what the Ui says).

Can you provide an better specification?

[J-N-K]

A bundle is a collection of classes that work together to provide some functionality (e.g. the org.openhab.core.io.rest bundle provides basic support for the REST API). Some of these classes are exported (and are available to other bundles), some are internal. Each bundle can depend on the exported classes from other bundles (e.g. the org.openhab.io.rest.audio bundle which handles the audio-related endpoints in the REST API depends on org.openhab.core.io.rest and org.openhab.core.audio). Each bundle has its own version (e.g. 4.0.0.202212232149).

A feature is a KARAF specific collection of one or more bundles (e.g. the openhab.tp-jna consists of net.java.dev.jna/jna and net.java.dev.jna/jna-platform). When we talk about installing or de-installing something in openHAB, it's a feature that is either added or removed from the runtime. We have different "types" of features: target platform features (e.g. openhab.tp-jna), core features (e.g. openhab-core-base) and add-ons (e.g. openhab-binding-xmppclient). A feature has a version of its own, that is not linked to the versions of the containing bundles (see my example above for openhab-binding-xmppclient). A typical version for an openHAB feature would be 4.0.0-SNAPSHOT or 3.4.0). Some qualifiers (like -SNAPSHOT) have a special meaning, see https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN8855 for a good explanation.

An add-on is a feature that adds some functionality that is not part of core. If necessary, optional target platform or core features are installed automatically. No longer needed target-platform or core features are also removed when the add-on that needs them is uninstalled. We group add-ons in several categories: automation, binding, transform, persistence, ui and some more. Add-on features usually DEPEND on openhab-runtime-base and optionally other core features. They CONTAIN additional bundles that contain their code, like org.openhab.addons.bundles/org.openhab.binding.xmppclient and optionally other bundles (see the list above).

[stefan-hoehn]

Very comprehensively and well written, Jan. Thank you! 🥇

So I try simplify / summarize from a different perspective:

• a binding is a specific add-on which is a feature that adds some functionality that is not part of core (the other way around is not necessarily correct)
• A feature is a KARAF specific collection of one or more bundles
• A bundle is a collection of classes...
  • Each bundle can depend on the exported classes from other bundles
  • Each bundle has its own version

so when I do a

openhab> bundle:list | grep Nano
302 │ Active │  80 │ 3.4.0                  │ openHAB Add-ons :: Bundles :: Nanoleaf Binding

it really gives me the version of that bundle (I can see that that version is different from 3.4.0 when I install a self-compiled version via bundle:update)

and when I do

openhab> feature:list | grep Nano
openhab-binding-nanoleaf                          │ 3.4.0            │ x        │ Started     │ openhab-addons-3.4.0                       │ Nanoleaf Binding

1) It gives me the version of that feature. As I never deployed that feature intentionally, is this automatically created when I deploy the bundle?

2) What would be actually shown in case of your example

Feature openhab-binding-xmppclient 3.3.0.SNAPSHOT

"Version" and where does that version come from or better, how is this version derived or set?

under /settings/addons/binding-xmppclient

[J-N-K]

I made it bit simpler than reality :-)

It's also possible to install bundles that are not part of feature (that happens if you drop a .jar in the addons folder or use bundle:install ... on the console.

There are also feature repositories (you can see the available repos with feature:repo-list). They can be remote repositories or .kar files. If you type feature:list you get a list of all available features from all repositories. You can install a feature by feature:install openhab-binding-dmx or the same for uninstall. When you click on "Install" in the UI, that is what happens in the background. The list of add-ons is compiled from the available features that start with openhab-binding-, openhab-automation- or similar.

The version of the feature is set when the repository is build (in the feature.xml of the respective add-on). It contains either something like 3.4.0-SNAPSHOT, 3.4.0.M1 or 3.4.0. This bundle version can be the same, but can also be different.

This the version that you see in the UI. The "openHAB version" on the info page is taken from <userdata>/etc/version.properties.

[stefan-hoehn]

Ok, i give up, Jan

A plan is good until it hits reality and things are sometimes just more complex as one might think. At least I learned a lot.

Let me close that then.

(just the fact that you provided so much valuable information here is a pity that we don't have that in our documentation but maybe when I have some time left some day it might find its way ;-) )