Best way to Migrate from 2.5 to 3.0, What would you do?


Ive tried updating my 2.5 install to 3.0 by using OPENHAB-CONFIG tool and issueing the ‘03’ Upgrade to Openhab 3. after this it updates, brings in my items but there is no links to the things. I would have to go through and recreate all the links from the items to the things. Is this normal or should it copy the OH2.5 data?


First, OH 3.1 was released so migrate to that instead of 3.0.

What I did was as follows:

  1. Left my OH 2.5 running
  2. Started a fresh OH 3 instance
  3. Basically followed the Getting Started Tutorial
    a. Install a Binding
    b. Create/Discover the Things
    c. Created Items from scratch using “Create Equipment from Thing”; you can create hundreds of Items in very little time this way
    d. Copied over/reimplemented the relevant rules
    e. Once it was working removed the binding, Items and Things in the old OH 2.5 instance
  4. Once everything was moved over I removed the old OH 2.5 instance and moved the OH 3 instance and config to the production server

One advantage I had was that I had a strong focus on automation over control meaning that the OH UIs were not really used for much except monitoring and administration by me. It didn’t matter if the UI was partially broken as I moved stuff to OH 3.

But if the UI is important for you, you could start with the Remote openHAB add-on on OH 3 and create mirrors of all your OH 2.5 Items. Then focus on the OH 3 UI until it works as you need (a .sitemap will transfer over without change I believe). Then follow the steps above. Thanks to the Remote OH binding anything you’ve not yet migrated to OH 3 will still work.

I did not attempt an in place upgrade but I’ve seen reports that it works for the most part.

How are you verifying that there are not links to the Things? Do the links simply not exist or are they pointing to the wrong place (e.g. Thing IDs changed)?

EDITED: I only had to reinstall Log-Viewer (frontail) using openhab-config.

I just did the openhab-config upgrade from 2.5 to 3.1 an hour ago. I was hoping everything would work automagically but I’m now needing to go back and read posts and instructions to figure out if it’s just my lack of familiarity with the new interfaces or if some things didn’t actually happen as planned.

I’m not sure my links were not reinstated. I see in my log viewer that all my links were removed after the upgrade but I also noticed that no new logs are being shown. I’m guessing it is my expectation that the log viewer is still working that is my problem. I have opened up basic UI and that is working. Actually, I’m sure the log viewer isn’t doing what I expected because it still shows “tail -f /var/log/openhab2/openhab.log /var/log/openhab2/events.log”


I gave up on migrating using UI, tried three times during last 12mo, for different reasons (mainly way too much time consuming work), but found out earlier today, that I can just use my files exactly as in 2.5 and had everything working within two hours. Grafana, mqtt zwave, rules. What a relief!
I know I miss some of the new stuff, but I can always change to that later. At least I have everything up now. Yes, I am a “file guy” :slight_smile:

So am i, but i have not got a THINGS file. Do you have a things file?

If you are not using a .things file and you are not careful to make sure your rediscovered Things have the exact same Thing ID as they have in your 2.5 instance than yes, of course you will need to relink all your Items. The Thing ID is what is used to identify the Channel the Item is linked to.

This is easiest to handle by:

  • make sure your manually create Bridge Things have the exact same ID as the 2.5 Thing
  • manually create Network, Astro, etc binding Things instead of allowing the binding to discover them; you can’t change the names of those Things

Make sure to set the ID before clicking on “Create Thing”. That’s your only opportunity the change the Thing ID.

So it may be easier to create a things file!

Depends on how many Things you have and whether or not you are already familiar with the syntax and options for all your existing Things.

In general I strongly recommend against the use of .things files. It ends up being a huge time sink for little to no benefit. Better to stick withe .items files if you think that using text files will somehow be easier. I’m not sure i see it. You have to create these bridge Things anyway. It doesn’t take much at all to set the Thing ID when you create the Bridge Thing. When the Bridge Thing has the same ID as your 2.5 Thing, all of the Things discovered under that Bridge Thing will also have the correct IDs.

It’s only those Things that do not have a bridge where you might need to manually create them because, unless a specific PR was merged without my noticing already, you can’t change the Thing ID of discovered Things that are not discovered through a Bridge.

1 Like

I have some things files - I have for MQTT (~50 things/items), sonos (~8) and for a few odd bindings. But not for zwave items (>100), and so on. Most without, that is.

But I think having things file for MQTT is useful, so if I where to suggest, I would add that, if you have MQTT (and have already done the MQTT1 → MQTT2 migration) the others can be made, as @rlkoshak suggested, with a little careful inspection or the thing id before creating it. For me, files where endlessly much easier, I guess because I had already so many devices and rules - it was overwhelming for me to try to push this though the webui, while also trying to understand. I know that there are tricks to to multiple edits, and tricks to do this and than, but then you have to learn the tricks. In short, I had a working system, and wanted a working system. Now I can always move my rules to the webui over time, when I need to change something instead of doing it all in one go. The rules management is what I see as the most important upgrade. I don’t have to worry about sematic stuff until I decide I want it.

I don’t want to sound negative, for each system is different, and we - the admins as well, so I accept that files are not for everybody. I am certainly glad that this made it into v3xx as well. At least I tried the web approach :slight_smile:

Yer, the only things i use and rules to trigger lighting from my weather station when it gets dark and the homekit binding so i can control the lights and my garage door, so using the UI isnt the top of my list either.

Hi Rick,
What would you suggest if i have zwave and zigbee2mqtt devices to move from 2.5 to 3.1, but I only have 1 controller of each type? How do you actually “move” the things and items?

Most of my things and items in 2.5 are not created via the UI. Should I do so in 3.1, for future ease of management?

For Zwave I’d move the3 controller over, discover the Things automatically and then create the Items using “Create Equipment from Thing”. I don’t use zigbee2mqtt so I can’t comment on that. I know there are a lot of complexities with it. The .things files should transfer over mostly unchanged but I don’t know for sure.

Thank you Rich.
Should i start a new mqtt server, or the existing one during the “migration”?
I like to use dockers for OH (eg mqtt, zigbee2mqtt,frontail)

You can keep using the same MQTT broker unless there is some reason you don’t want to.

how to access basicui on 3.1?

I got it, same as before… I copy the link from 2.5 and it works.

Anyone has tips on migrating zigbee2mqtt things, using the same controller?