Removal of the OH 1.x Compatibility Layer

One of the proposed goals for OH 3 is the removal of the OH 1.x Compatibility Layer. The Compatibility Layer serves to translate the old OH 1.x package names to ESH package names. Now we are changing these package names once again with the merge of ESH back into OH. Consequently the Compatibility Layer would either need to be dropped or rewritten.

The only bindings that use the Compatibility Layer are those OH 1.x bindings that have not been updated to use the new package names. If the binding is listed in the OH docs and PaperUI then it has been updated and that binding will continue to be supported. If an OH 1.x binding has not been updated to use the new package names in the three (ish) years since OH 2.0 pre-release then IMHO it is an abandoned binding. With the removal of the Compatibility Layer, these OH 1.x bindings would be left behind.

To all who see this, do you have any bindings that require you to install the OH 1.x Compatibility Layer and install the binding by dropping the jar file into the addons folder? If so which ones?

1 Like

The main concept of openHAB is the eventbus. This is true for OH1 as well as OH2.
As soon as any command/state ends up on the eventbus everything is fine.

How about this proposal: We provide an OH 1.9 core runtime for all the left-behind OH1 addons that connects/syncs via MQTT (for example) with OH 3. I wanted to propose an OH-sync service anyway. I’m willing to write one for a new OH, the one for OH1 would need to write someone else though.

That way OH1 bindings work indefinitely (until all old hardware died out) and in OH2/3 nobody need to care about breaking changes for old OH1 bindings.


All persistence bindings are OH1 bindings. Suppressing the compatibility layer would require to rewrite them for OH3 ?


from what I learned (the last day) I think that
it’s not because something is an 1x binding that it is using the compatibility layer.

so it could be that the persistent bindings are already upgraded.
Brings the questions which are the bindings we are talking about?
(and how many are there ) and are they still used?

OH 1.x already supports the event bus configuration in the MQTT 1.x binding. Since you are looking to use MQTT anyway, there may not be anything to write for 1.9 at all.

I’m not sure how big of a problem this is and I don’t know how to find out. I suppose I can go through the big list of bindings, find out which OH 1.x versions are in openhab-addons but not listed in PaperUI but that seems tedious and error prone. Maybe I can figure out a way to screen scrape and script it.

No. It is important to realize that if you are using it now and you didn’t have to do any extra steps to install the add-on, then the binding is not using the Compatibility Layer.

The Compatibility Layer was a shim intended to be used to test that an add-on written for OH 1 works with OH 2. Once we prove that it works with the Compatibility Layer, then the binding would be updated to use the new package names and no longer use the Compatibility Layer.

If the add-on is listed in PaperUI, it is not using the Compatibility Layer.

If you had to install the Compatibility Layer (which is done through the Karaf Console) then downloaded the jar file and placed it into the addons folder to install the binding, then the proposed change would impact you and we need to hear from you.

Any binding that is in the openhab-addons github repo that is not listed in PaperUI’s list of addons would be impacted. I don’t think we can worry about add-ons that users are distributing on their own outside of the OH repos. I believe that if it is an add-on that is distributed by the IoT Marketplace it wouldn’t be impacted either.

If so, then the users are not active participants on this forum and the users did not follow the original instructions for using the Compatibility Layer and inform us that they tested the add-on on OH 2 and it works. Once were were told that it works, an issue was opened and the changes were made to make the Compatibility Layer no longer necessary for that add-on.

So these are add-ons that likely:

  • have a low user base
  • have not received a significant PR or change to the code in three+ years
  • are not addressing a technology or API that is in high demand

That is why I would call these bindings abandoned.

OH1 bindings including actions and persistence services which doesn’t yet have OH2 equivalent can be found here

For some of those OH1 bindings, there are OH2 PR already available.

Following list contains all OH1 legacy bindings will already have OH2 equivalent available, but some users still use OH1 bindings even OH2 version is available because they support more functionality than OH2 binding versions.

1 Like

That doesn’t necessarily mean that all of those bindings use the Compatibility Layer. If you can install it through PaperUI, it doesn’t use the Compatibility Layer.

Only those bindings that are in that repo that do not appear in the OH Docs or in PaperUI’s list (when show legacy 1.x bindings is enabled) would be impacted.

I repeat, this does not impact any add-on that is installed the normal way in OH 2 through addons.cfg, PaperUI, the REST API, or Karaf Console. It only impacts those bindings that require this procedure to install.

1 Like

To be honest, I’m not so sure. Look at the following feature.xml part:

<feature name="openhab-persistence-influxdb" description="InfluxDB (v 1.0) Persistence" version="${project.version}">
    <bundle start-level="80">mvn:org.openhab.persistence/org.openhab.persistence.influxdb/${project.version}</bundle>
    <configfile finalname="${openhab.conf}/services/influxdb.cfg" override="false">mvn:${project.groupId}/openhab-addons-external/${project.version}/cfg/influxdb</configfile>

This is the influxdb persistence service and it requires the compat1x feature. And that feature will not exists for OH3 as far as I understood Kai. Maybe I’m also looking at the wrong place and there is a second OH2 version of influxdb persistence.

1 Like

All OH1 bindings which is executed on OH2 environment need compatibility layer.

Hmm. I might be wrong then. I made an assumption that these had all been migrated based on the original set of instructions.

Grrrrr. I can’t get into my karaf console to see if it is installed.

Clearly these add ons would not be left behind. So I would expect there would be a big find and replace across all the add-ons to use the new package names.

If that is the case then why:

  • did we have to manually install the Compatibility Layer when we wanted to test an unsupported OH 1 addon? It’s been years but I distinctly remember I had OH 1 add-ons installed already (i.e. Astro1) and yet the Compatibility Layer was not enabled when I looked in Karaf.

  • What was done after we reported that an OH 1 add-on worked?

Maybe I missremember.

@kai, can you elaborate a bit more about the proposal to replace the OH 1 Compatibility Layer? Does this mean

  • leaving behind all OH 1.x add-ons (I hope not) (including all Persistence, Transformations, and Actions)
  • all add ons will be updated to not require the Compatibility Layer
  • some add ons will be left behind and others will be updated?

I made some assumptions that may not be correct.

I just had a look at the code and it is not much effort to migrate OH1 actions to OH2 actions, I have created a separate topic.

1 Like

Just saying, I would be in a bad place without the EXPIRE binding.


We all would be in a bad place without Expire (though that will have to be replaced with something 2.x at some point) all persistence and all actions.

Just checked my system and found the compat-layer, I using bindings version 2 only, but I’m also using persistence.


I finally got back into my karaf console (the setting somehow got reset to only allow connections from but I run in Docker so localhost is inside the container). I have it installed too.

so if all 1.x bindings are using the compatibility layer, what is the best way to find out which bindings are still used?
Asking on the forum?

I don’t know. But if they are all using the compatibility layer, then perhaps the job to remove the compatibility layer will include changing ALL of the bindings not to use it. It looks like David has a good approach for the Actions already. All of the Persistence and Transformation add-ons will need to be changed no matter what.

Beyond that, someone(s) either need to take it upon themselves to change every binding in openhab-addons or only those bindings for which there is a maintainer will make the changes and the “abandoned” ones left behind. I’m hoping Kai will chime in to give us a little more about his thinking.

1 Like

What are the characteristics in the Core Engine that’s causing these incompatible changes between major versions?

It seems like something is missing in the Engine/Binding decoupling that’s causing the impedance mismatch with major releases. In turn it’s causing the need for Bindings to be tweaked and/or rewritten.

Seems like that should be something fundamentally addressed in any next release planning. When this level of compat is there, it clearly lessens the reasons to remain running on older (major, minor) releases.

Right. You’d end up with a more neutral, and inherently versioned, federation layer for people to run their Bindings against. They can upgrade, to pickup new functionality, without worrying (too much!) about what they’ve already got working.

Similar to the compat expectations people have for Wifi (old works with new), where the compat has been maintained for nearly two decades (from 802.11b through 802.11ac). Some of the functionality is missing, but it’s meant that people haven’t had to perform co-ordinated replacements of their physical/client devices every few yrs. :slight_smile:

It’s been a while, but I only remember having to report back that I’d used the compat layer, and tested against it. Once it was in I don’t remember any subsequent request to eliminate it.

In my case I made changes due to the [hard, Java] types used, specifically in the MIOS Action sub-component (IIRC). In the end I think I was able to remove it, but the Nest v1 plugin ran into similar issues.

I suspect the sample of environments here, or even the broader forum user-base, is somewhat skewed from what the majority of users actually do.

ie. The “it’s not broke, don’t fix-it” users may not be active forum users

That said, a forum poll is better than nothing. I suspect you’d ask what version of core people are running, and separately what v1 bindings they’re running (and how to find out)

What would be handy here is something that, via opt-in, periodically does a phone-home of key version/platform information (Core + Bindings). From that you’d have real data to help make the decisions.

1 Like

OH2 introduced Things/Channels. That was a breaking change. And OH1 bindings actually do not really work in OH2, if you are not using textual configuration.

That was a change, but not really a breaking change. It was introduced in a manner that provided compatibility.

IIRC, the biggest technical/developer issue was the use of hard types (imports) on both sides (engine + binding) that changed for some of the widely used base types in rules.

I’d argue that the original plain textual configuration was a major plus (from OH 1.x), and that anything that’s forced the JSON-only config is a bigger issue… still better than the intermediate binary DB that was around for a while… but that’s out of context for this discussion :wink:

It’s still supported, operating in a semi-degraded mode, and provided via a well considered compatibility later.

The “it’s not broken, don’t fix it” model has worked reasonably for config files and the Things/Channel introduction from a user-centric standpoint.

My question relates to what’s missing in the infrastructure/integration between Core and a Binding that’s causing the churn from a Binding author-centric standpoint.

1 Like