I’ve had an openhab instance 2.5 running for a very long time without problems. I’ve now moved into a new house and have decided it would be time to upgrade openhab as well. I’ve got all the old rules DSL running and textual config files as well.
What would be the smoothest way to migrate to a current version (4 or 5, which is recommended?)? Should I start from zero and do all the stuff through the UI or import configs, if that’s even possible?
I’d be happy for any sort of guidance in this. My openhab was/will be running on a RPi 4 with 4G or 8G ram, I forgot, but should be enough for the newer openhab versions as well. I’ll be running zigbee2mqtt as well as an NGINX reverse proxy, but importing these configs should be pretty straightforward.
Do not skip the Getting Started Tutorial. I cannot stress this enough. Those who have the hardest time with recent OH are old 2 and before users who don’t read Getting Started.
If you are using any OH 1.x bindings you’ll have to reconfigure all those from scractch using the new bindings. OH 3+ only supports bindings that implement Things now.
To be “future proof” make sure to install a 64-bit OS. OH 5 and onwards will only support 64-bit.
Once you’ve gone through Getting Started and learned some of what’s new (MainUI, Semantic Model, etc) you should have enough information to make some decisions.
File based or UI: almost everything is still possible through separate DSL formatted config files. However, there are a few things that are only supportable in the UI like MainUI widgets, rule templates, etc. Note that everything you do in the UI gets saved as plain text to the userdata folder so it’s no more or less easy to backup and configuration control. Note that it’s not all or nothing. You can choose to do Things and Items in the UI and rules in files, for example. But as of OH 4 everything can be configured through the UI, even logging levels for add-ons.
Which UI to use. You have to use MainUI for some configuration steps but BasicUI and HABPanel are still around and can be used.
Move to a new rules language: I assert that Rules DSL is no longer the best choice when it comes to rules development. Any of the other options are going to be more complete, more consistent, and result in less code. With JS Scripting you also get Blockly with is a graphical programming enviornment.
Answering these should help guide your overall approach.
If you have a live setup, a lot of people used the Remote openHAB add-on to aid in the transition. You can have OH 2.5 running on one machine and OH 4.3 on another. Install the Remote openHAB add-on on 4.3 and it will discover your OH 2.5 instance. You can then create a Thing and some Items that will be synchronized with the 2.5 instance. Then you can move stuff over gradually, adding them to the new OH and removing them from the old until everything is transferred over.
If not, I recommend just starting over fresh with OH 4.3.
If you go through Getting Started and decide you don’t want to use any of that new stuff, it is perfectly reasonably to migrate your existing configs to the new OH. You’ll need to go through the release notes for each version of OH between 3.0 and 4.3 and review the breaking changes to see what, if anything, needs to change in your text configs. Don’t forget to look at the notes for changes to the bindings you use as some add or remove fields from the Things.
If you decide to give the UI a try, I recommend the following approach:
When OH first starts you’ll be presented with a wizard. Follow it and as part of that fill out the start of your semantic model by creating some locations.
Install one binding you need
Discover the Things and manually configure any Things that cannot be discovered.
Open the Channels tab on one of the Things and choose “add equipment to mode”. This will create an Equipment Group, create and let you configure all the Items linked to the Channels of the Thing you need, and add the Equipment to the chosen location. For now, this is the fastest and easiest way to create Items and make them fit into the semantic model. If you are careful you can make sure the Items are named the same as the old ones, but this is also an opportunity to choose new names.
If you use MainUI, these Items will aready appear on the Locations, Equiupment, and Properties tabs of the Overview page in MainUI. If you want to use Sitemaps, add your new Items to your sitemap (.sitemap file or you can create a sitemap through MainUI).
Once you have some Items, start moving over some rules, one by one. Now is a great time to check out some of the other rules options since you’re going to have to do a good deal of work to migrate 2.5 Rules DSL to 4.3 anyway. If you are not great at programming, Blockly is a good choice.
At some point you’ll want to configure persistence. This will be in a .persist file or done through the UI. Unlike in OH 2.5, persistence add-ons will come with a default strategy which is usually “everyChange, restoreOnStartup”. There are a bunch of new features in persistence too like filters and the ability to work with time series that go into the future (e.g. weather forecasts, energy pricing) that are worth checking out.
Transformations too can be added through the UI now and you can write script transformations using any supported rules language, not just Nashorn JS. Inline script transformations are supported and in a lot more places, transformation chaining is supported. Between 7 and 8 you might be able to eliminate some rules.
There are a bunch of new Profiles which do stuff like debounce, hysteresis, rounding, etc which can also eliminate some rules sometimes.
There are several new rule traiggers, in particular the “Time is item” trigger which triggers the rule at the date time or just time stored in a DateTime Item.
Rule templates and MainUI widgets can be installed from the marketplace. You don’t need to code everything yourself or copy/paste from the forum.
Repeat these steps until everything is transferred over.
First of all, thank you very much for the detailed write up, I really appreciate it! I’ve fiddled around with openhab 4.3 in a docker installation on my diskstation and read up about the semantic model already - I like it. Very logically structured and definitely helps to pause and think through what is where and how they should all interact.
I think I’ll be going the route of doing a fresh install since many items will have changed/ are not there anymore anyway and the old system has more or less grown over time and all the rules might be in need of overhauling and prettifying anyway.
I’ve used the HTML folder to serve a landing page that had links to basic Ui, fronttail and a bunch of other stuff I ran behind my reverse proxy, if I’ve seen correctly, I can use the overview page for stuff like that as well?
I’ll be creating a backup for all my old stuff and then make a fresh openhabian x64 install on another sd card on my RPi 4 and see how long it’ll take me to get everything up to speed.
I’ve made a backup of the stuff I created in the docker OH 4, the semantic model and Shellys I already added, can I simply throw the data and config folders into the freshly installed OH4 on the RPi?
MainUI has links to BasicUI (Sitemaps) and Frontail when installed by openHABian (you can add a link if you need to). However, keep in mind that Frontail is abandonware at this point and MainUI now has a Log Viewer which is pretty basic right now but improvements are being made.
Beyond that, there is a webframe widget you can show in a page in MainUI with links to other stuff if you need it. I don’t think among the many actions supported by widgets if opening a new page not hosted by OH is supported.
Theoretically but definitely clear the cache first. Your Docker image is probably not running on ARM so the compiled stuff (e.g. some add-ons depend on third party compiled libraries) and such are almost certainly not going to work. When you clear the cache, it will remove all that stuff and they’ll be redownloaded and reinstalled using the correct CPU architecture binaries.
Either way. Clear the cache before doing the backup, or clear the cache after coping the backup over but before starting OH. If you do it before the backup, there’s less to copy.
I’ve successfully installed OH 4.3.3 on my RPi and imported the backup from docker. So far, it all seems to be working. Got a long way ahead of me but boy, am I excited.
