Migrate RP 4 OH 2.5.12 machine to new RP 5 OH 4.1 machine

Late migration here…

My OH production system is a RP 4 with a SSD running openhabian / OH 2.5.12.
This system has hundreds of items defined and a huge influx database and thousands of lines of code with Jython rules and routines. No DSL any more.

As I do not want to run into down-times by upgrading that system to OH 4, I have prepared a brand new RP 5 with another SSD and an empty OH 4.1 installed in parallel.

Question: what is your recommendation to migrate the OH 2.5 system with all data and rules to the new system. I’m aware I will need to migrate my Jython code to use the new DateTime etc, but I have no clue if I can use some backup / restore or need to copy over things one my one. Thanks a lot!

You can take two different approaches.

  1. install 2.5.12 on the new machine, then do an in place upgrade there and then deal with all the breaking changes that have accumulated over the past five years or so.

  2. Set up OH 4.1 on the new machine with the Remote openHAB add-on to mirror all the Items in your 2.5 instance on the new machine. Then gradually migrate stuff, binding by binding, rule by rule from the 2.5 instance to the 4.1 instance. When everything is migrated you can turn off the 2.5 instance but in the mean time you’ll be running both.

2 is definitely going to be a more controlled migration and it will enable you to explore lots of the new stuff in OH 3/4.

Note that you’ll have to find CrazyIvan’s fork of the Jython helper library. And also note that Jython should be treated as deprecated since OH 3. The upstream library is barely maintained. The helper library is no longer maintained. Eventually it’s going to break and when it does there will be no one here who can fix it.

If you like Python, look at HABApp as a potential replacement. If you want to stick to OH native, look at the JS Scripting add-on.

Thanks Rich for the feedback, although it includes the worst message you could send…

I probably have been away from OH development for too long. The drop of Jython / Python support is absolutely disappointing. My last information has been that openHAB would support multiply scripting languages for the future. It looks like I need to make up my mind whether to start that migration at all. I’m familiar with JS too, but I neither want to migrate the code completely nor make JS my daily platform.

I had a look into HABApp. Looks about right although it degrades OH to be just a state layer and binding provider… It looks like a single person development in addition? So again, it will be a question whether an investment into it will be safe for the future. I probably need to do some research on home automation solutions focussing on Python…

It’s not like we want to drop it. The Jython project still only has a 2.7 version of Python supported, which reached end of life four years ago. Support for Python 3 is still nowhere in sight. That’s a third party project we have no control over.

It does. OH currently is supports:

  • Groovy
  • Blockly (a graphical programming enviornment)
  • Nashorn JavaScript (which should be considered legacy)
  • JS Scripting
  • jRuby
  • Groovy
  • Java

So was Jython support in OH and that single developer disappeared right when OH 3 was released. The helper library for Jython also was never made a part of the openHAB project unlike the above meaning there was really no way for someone part of the OH project to take over maintenance of that.

All of the options listed above have multiple maintainers and unlike in 2.5, the helper libraries come with the add-on. No more need to clone some random github repo and change some config file.

I believe HABApp has multiple contributors but it, like the Jython helper library, it is also maintained outside of the openHAB project.

I think the most important thing to note though is that Jython is currently supported in OH 4.1. So that’s not by itself a reason to not upgrade if you want or need to. Whether it will remain supported in OH 5 or even OH 4.2 is unknown and outside of our control. So if one is going to migrate to another language, it’s better to migrate gradually when you have time rather than after everything breaks.

Migrating to some other rules language is going to always be way less work than migrating to a whole new platform. But if you want to see if the grass is greener that’s encouraged as well. I know that HomeAssistant is written in Python, but it’s support for automation overall is anemic and super simplistic.

Just to be sure before I start this bigger effort… In OH2.5, I had most things discovered in PaperUI, some in text files (e.g. MQTT). I had all items used in rules defined in text files. When going the named path for migration, do I need to discover all things from the start or is there an option to pull the thing definitions from OH2.5. When setting the thing IDs the same as in OH2.5, should it be possible to reuse the item text file definitions 1:1? Certainly with changes like the former Expire Binding.


If you’ve discovered the Things in 2.5, you are better off rediscovering then in 4.1. There have been changes to Things over the years and you’ll spend more time dealing with those breaking changes than it takes to just run a new scan for the devices that are discoverable.

There are a lot of new parameters and capabilities in MQTT which might make it worth recreating those from scratch too, even if it’s just for the first one or two to learn what’s new. If you look at the Code tab for a thing, you’ll see the names of the parameters you’ll use in a .things file if you want to stick to that approach (not my recommendation).

The implementation for Expire changed but the syntax to configure it remains the change, except for a number of enhancements like being able to ignore updates. If you use managed configs for Items, you’ll use “add metadata” to configure Expire. There’s a nice form there showing all the possible parameters and what they do.

What the Remote MQTT binding letter you do is recreate your 2.5 Items on your 4.0 install and keep them in sync (i.e when it’s updated on the 2.5 instance the 4.1 instance updates, when you command the 4.1 instance, the command gets sent to the 2.5 instance). Note what the Item names do not need to be the same on both instances so you can rework your Item names if you want.

This can let you move all your rules over to 4.1 first if you want. It it lets you move everything for the lighting except the Things to the 4.1 instance and only move the USB dongle when everything else is ready.

It you can move one binding and everything associated with that one binding over to 4.1 and even if there’s a rule or something that depends on Items from another binding you can maintain trigger full functionality.

When I moved, I did the following:

  1. choose a binding
  2. Disable the binding on 2.5
  3. Move hardware if required (e.g. Zwave controller)
  4. rediscover the Things on the new instance
  5. Use “add equipment to model” to create the Items
  6. move the relevant rules
  7. Disable/delete Things, Items, Rules on 2.5 as they get moved to 4.1.
  8. repeate1-7 for the remaining bindings

Thanks Rich for the detailed description. I just counted my things and items. I have 178 things in PaperUI and roughly 1300 items in text files. So I definitively need to keep the thing IDs to allow a migration of items with text files. I can’t define these from scratch. ;-(

When you discover the Thing you have the option to “add thing with custom id” where you can set the Thing ID.


I think you’ll find it’s not so bad really. For example, take the Astro Sun Thing which has almost the most Channels of any binding outside of OpenWeatherMap and let’s say I want to add Items for all the Channels for some reason (that’s reasonable for most Things, not so much for Astro but this is just showing the process).

When I click “add equipment to model” I get this form:

From this form I can select the Location in the model where this Equipment will reside, create the Equipment Item and create the Point Items for all the Channels by filling out a few fields and a couple of clicks. It’s a good idea to review what’s selected by default. You may want to use different units for Number Items or different semantic tags. The names of the Item will be the name of the Equipment+“_”+Name of the Channel.

For grins I timed myself using this approach. I created a new Astro Thing, added equipment to model and selected all 62 Channels. For each Channel I set the category and both semantic tags. It took in total 12:21 so a little under 12 seconds per Item.

When I’ve done this in the past with text files, it took significantly longer than 12 seconds per Item to create the Equipment Group, figure out what the correct semantic tags are for the Group, adding all the Point Items to the Group, and figuring out what the correct semantic tags are to each individual Point Item.

That’s why my recommendation is always to use managed Items and “add equipment to model” to create your Things if you will be using the semantic model. Attempting to shoehorn your existing Items into the semantic model is going to take significantly more time and work.