Lost in 2.x Migration

After reading the manual “Migration from openHAB 1.x to openHAB 2” this leaves me in a very undefined state:

  • why do you want users to migrate their metadata, when a simple migration wizard could do the job?
  • why make version 2 so much different when the enduser experience is almost identical?

Is there any paid support that will migrate a user setup from version 1.x to 2.0? Why not have all configuration data in the cloud?

I wonder if it’s worth the 100s of hours to redo configuration, as version 3 may break compatibility again.


PS don’t get me wrong - I love openhab - with kids you have decide what to spend your time on

Maybe you could post what exactly doesn’t work in your case. When i migrated to OH2, i installed them parallel on different ports and switched one functionality after another from 1 to 2, whenever i had a little time. Some worked out of the box, some needed some more care.


You have a migration wizard? Please contribute it so everyone else can benefit from it.


(1) KNX has no 2.x compatible binding
–> all items need to be configured manually again
–> I have > 1000 bus addresses to go

(2) ModBus no autoconfiguration, no modbus monitor
–> have to guess parameters

So for me it’s like a real migration nightmare:

  • go through all files (items, sitemaps, rules, configuration) again
  • translate from 1.x to 2.x
  • check all items / etc sitemaps

This would be OK once - but who can tell if thats not needed again for rel 3.x ? I thing I easily spend 300 hours on the first configuration, as there was not autodetection nor import from KNX files.


I would WANT a migration wizard / paid migration service.

Imagine Word documents would all need to be reformatted if you go for a new version.


You can use most, if not all OH1 bindings in OH2. You can also use your existing .items files - not sure why you would need to spend 100s of hours to redo configurations.

Reuse my item files?

Reading the documentation, I got the impression that “KNX defintions” have changed.

There’s line with KNX (likely in 1.x notation):
Switch Light_Floor “Light at Floor” { knx=“1/0/15+0/0/15” }

Then it states:
Thus, as described in the Binding’s readme one would manually define a Thing in a .things file (located in conf/things) with the line …

This leaves me lost here:

  • KNX does not autoconfigure
  • the new concept of things does not autoconfigure (at least for KNX)
  • there is no step by step migration description for every item type
  • I speed weeks on testing / verifying KNX (as this uses a complex datatype and address layout with sending, receiving addresses)

Reading some other posts, I found some more confused users trying to get KNX to work with OpenHAB.

I’d be glad if there would be an instruction on every step to convert from 1.x to 2.x when using KNX on every possible KNX item configuration or at least address type.

As an example, this is how a very simple KNX item look like:
Dimmer Light_GF_Living_Table “Table” (GF_Living, Lights) {knx=“1/1/13+1/3/13,1/2/13,<1/4/13+1/5/13”}

How do I have to configure this as a “thing” in the 2.x world?


Thats really unexpected from reading all the manuals:

  • items can be just copied from 1.x to 2.x
  • same for sitemaps

–> Tried this after reading your post here

Sitemap will work as long the binding is still 1.x . Items on 2.x binding won’t work (probably need some work)

So, as KNX is an 1.x binding, all my KNX based items still work in openhab 2.x . What will happen when the binding is updated to 2.x?

My homematic items don’t work --> have to read manual on to use things in sitemaps.


which KNX (1.x) binding docs entry refers to things? (this is wrong and should be corrected if there is such reference). Do you have a link to this please?

The “official” http://docs.openhab.org/addons/bindings/knx1/readme.html doesn’t have any mention of things.

From my experience: The exact same KNX.items stuff will work in OH2.1 without any changes since the underlying KNX binding is still 1.x version and does not use the concept of Things.

You can choose to stay on KNX 1.x binding :slight_smile: The KNX 2.x will be made available on top of the existing KNX 1.x (as many other bindings exist today in parallel)

I’m not sure what you are referring to specifically here. The Migration Tutorial has you make the upgrade in stages. First install your 1.x version of the bindings you are using. Then copy over your existing config files watching for errors. Correct the errors (there is a section in the tutorial that tells you what changed). Once everything is working only THEN do you start to upgrade your bindings to 2.x version bindings.

The problem is, with over 150 1.x bindings, there is nothing simple about a migration wizard. And frankly, there is no wizard because no one donated the time and effort to make one. This is all a volunteer effort. No one is getting paid to work on this stuff.

First of all, the end-user experience is not almost identical. Major changes had to be made to the architecture to allow for OH to move to the future. In particular, we have:

  • the ability to automatically discover devices and configure them for OH use
  • the ability to manage more and more of the OH configuration through web based UIs instead of text files
  • the new Rules Engine which will allow for the creation of reusable libraries and web UI based coding of rules

None of that was possible with OH 1.x’s architecture and required a lot of changes to the core architecture to support.

Like I said, it is all a volunteer effort. There is no openHAB corporation or company. Just a lot of developers donating their time to a project they enjoy and want to succeed. However, several people have put a call out on these forums offering to pay for someone to help.

Many to most users of openHAB use it specifically because it does not depend on a cloud to work.

Depending on the size of your setup, you should be able to migrate from the OH 1.x core to a 2.x core in a few hours to a day. As others have mentioned on this thread, with the 1.x version bindings, your .items files can be used as is, there are not .things, your sitemap should be usable as is, and there are minor changes needed to your rules.

When looking at the entire section in context:

In openHAB 1.x (and importantly still for 1.9 version bindings running in openHAB 2) one had to add “binding configuration” in curly brackets to the end of Item definitions in order to link that Item to some control point on a physical device or API. The openHAB wiki gives a nice examples of how this looks:

The bold is added by me for emphasis. I do see this needs to be changed to 1.x instead of 1.9.

Then that knx example is listed as one of those 1.x examples.

So this part of the section is providing examples of how it used to be done. Then we have a little later after a paragraph explaining the limitations the 1.x apprpoach:

These issues were identified a long time ago and the concept of Things and Channels were introduced to solve them. The general idea is to standardize the binding configuration and move it away from the .items file. A Thing represents a configurable device/system/unit, which provides different functionality through a set of one or more Channels. Each Channel corresponds exactly to one binding configuration string (stuff in { }) in openHAB 1.x.

Let’s look at a concrete example. The Yahoo Weather Binding supports exactly one Thing which takes two parameters: a WOEID location and unit.

Thus, as described in the Binding’s readme one would manually define a Thing in a .things file (located in conf/things) with the line:

Again, I added the bold for emphasis. The sentence you quoted and the example apply to the Yahoo Weather Binding as a concrete example of how the 2.x verison bindings and the new concepts of Things and Channels work. Nowhere is it meant to imply that any of this applies to any of the previous 1.x examples.

KNX is a 1.x verison binding. “In openHAB 1.x (and importantly still for 1.9 version bindings running in openHAB 2)” they work the same and they always have."

By this point in the tutorial, if you were following it as written, you should have an OH 2.x OH core running all 1.x version bindings and a slightly edited version of your existing config files. The section that starts “New Concepts: Things and Channels” is where you can start, on a binding by binding basis and as desired, migrate from your 1.x version bindings to 2.x versions of those same bindings.

But you are not required to do that all at once or ever should you choose to stick with the 1.x versions. These “legacy” bindings are still being updated and in many many cases, these 1.x versions are not legacy because they are the only version. KNX, MQTT, and HTTP are two of the more commonly used examples of bindings that do not have a 2.x version yet.

So really, you should have a working OH install before you start worrying about and messing with Things and Channels and anything significantly new. That at least is how the Migration Tutorial is structured.

To specifically address your statement, there is no tutorial because there is not difference at this point in the tutorial. When you do decide to move to a 2.x version of a binding you are currently using, the instructions for how to define the Things you need will be in that binding’s README on the docs. Your Items will just need to be changed to use channel="channelid" instead of the old 1.x style binding config.

As mentioned, there are no steps because it should be identical. KNX is a 1.x version binding so “In openHAB 1.x (and importantly still for 1.9 version bindings running in openHAB 2)” they work the same and they always have."

Identically to how you have it defined now.

From this section of the Migration tutorial:

Now openHAB 2 is ready to receive your other configurations, items and such. Watch the log file as you transfer over files for errors. These errors will have to be fixed.

Copy over your files in the following order:

cp <openHAB 1.x conf>/configurations/transform/* <openHAB 2 conf>/transform/*
cp <openHAB 1.x conf>/configurations/scripts/* <openHAB 2 conf>/scripts/*
cp <openHAB 1.x conf>/configurations/persistence/* <openHAB 2 conf>/persistence
Copy any custom icons added from webapps/images to <openHAB 2 conf>/icons/classic
Copy any custom webviews from webapps to <openHAB 2 conf>/html
cp <openHAB 1.x conf>/configurations/items/* <openHAB 2 conf>/items/*
cp <openHAB 1.x conf>/configurations/rules/* <openHAB 2 conf>/rules/*
cp <openHAB 1.x conf>/configurations/sitemaps/* <openHAB 2 conf>/sitemaps/*

The next section lists all the things you will have to change in your existing files.

You will have the option to keep using the 1.x version of the binding or to transition to the 2.x version. Should you choose to migrate to the 2.x version the second half of the migration tutorial starting here is what you will want to follow.

If you have any suggestions on what could be changed to the migration tutorial to make future readers less likely to be confused as you were we are more than open to suggestions. We don’t want anyone to needlessly spend a lot of wasted time because of confusing docs.

But as far as I can tell, the Migration Tutorial does contain all the information you were mistaken about.

1 Like