OH3 migration: doing my head in

Max_G · October 23, 2022, 4:39am

Over the last few weeks I have spent quite a few days of reading on the forum about OH3, migrating to it from OH2, how to, what to watch out for, and what not.
(Actually I am dabbling in it / contemplating since Jan 2022)

I see that some have changed their mind on how they went about migrating from OH2 to OH3, compared to how they did the same thing later, either redoing the migration, or spending a lot of time creating items via the UI, while others are using files (without the groups).
Others build models… and it just does not sink in, what it is actually used for.
It somehow can build what used to be sitemap, saying somewhere else you do not need a sitemap, why do I need a model to build one.

I am interested in some long-timer OH users, who may started out on v1, moved to v2, who may have, like I, never used the new things 2.5 offered. So yes, ‘things’ … never mind…
… anyway: looking back, with what you know today, how would you migrate to OH3?

I planning to move from a rPi3 to a rPi4 with 4GB memory.

Why? I see no choice, if wanting a supported uniform solution… and use some new bindings, such as ZigBee, Modbus, ComfoAir, myEnergi, etc. and not wanting to use a bridge. (Just get it over with.)

I have 1,475 items, 142 rules, and 167 groups, if this helps to imagine the task at hand. Most controllers are Arduinos communicating via MQTT.

While the automation is barely visible, a lot of thing are happening; however, I am using one HabPanel (I think; forgot how it all works); use the sitemap for mostly admin; never made to grafana, I’d like to use (much nicer), and there are these things called cards and yml which seems interesting.
Voice control (self-hosted) is something I’d like to eventually add as well.

Taking all the above into account, what would be the most suitable way to migrate?

What did I figure out so far?
Install openhabian, which I have. works
I would create things via the UI, as well as groups.
Remove groups from the .items files and keep them as text files.
I would keep rules in text file if this is a good idea. (but can’t argue pro or against it)… and fix any code incompatibilities.

And then expect all would work.

I can see three options:

migrate quick and dirty; keep mostly text files and sort out rules.
do one better by creating things, groups via UI
build all new in OH3 (I reckon I die before I finish); so not really an option, unless there is some quick import thingy.

What is the “doing head in” part?
When I read the concepts, these make sense; but when I want to apply these I get lost. Point, equipment, model, semantics, …

Any hints appreciated.

stamate_viorel · October 23, 2022, 5:15am

just copy the files directly and look at the logs and fix what’s broken easy way. hard way take it in pieces and go full UI. it’s a ridiculous task most of the time but the felling at the end it’s worth it.

hafniumzinc · October 23, 2022, 6:11am

This won’t work for a lot of your Items - OH3 is not backwards compatible with the old OH1 way of doing, um, ‘things’.

Just migrate bit by bit. Experiment with the UI to install bindings, create Things, then create Items, then create rules.

There’s a huge Getting Started section in the documentation - read it all before starting.

There is - you can import your Items into the UI, but again any Items using the OH1 ‘Thing’ syntax will not work as you intend.

mstormi · October 23, 2022, 9:10am

I suggest you make a proper distinction between a migration to OH3 software on the one hand side and a transformation of your setup to use any of the new features.
Don’t do them at the same time !
First things first. Migrate software first.
Config transformation is a lot more work and time consuming, and not necessary at all and particularly not so for long term users that have a working config.
OH3 introduces new features that you can use but don’t have to.
You can setup a new main UI based on pages and widgets in parallel to continue using sitemaps and/or habpanel. Be aware this is time consuming to get it right.

On model, I would not use it. It’s there to jumpstart new setups but hard to retrofit your config to the model. Most long timers like me that had a working OH2 config in place never bothered to move over. It’s essentially a full redo of your config.
You can integrate with the model by tagging your equipment and making it member of groups.
Note that while in theory that would even work with a text based config, in reality it’s a lot easier if your things and items are UI-defined so if they’re not yet that would be a good idea to take on first. Once you run OH3 you can (but don’t have to) replace your items from .items files with UI items, there’s an option to import those files. Unfortunately there’s no such option also for things.

I would only use the model if I started from scratch. You could also build an “overlay” config of new items by starting along the model UI while running your old config.
You call option 1 “q&d” but it isn’t, it’s perfectly valid. You can actually have the OH3 install routine migrate your OH2 config, should even work from within openHABian (take full box backups nonetheless for safety).

He’s on OH2 so that’s essentially wrong.
It will work to keep using the config files in place also with OH3 unless there’s items that still rely on OH1 bindings to run in compatibility mode as that was dropped in OH3.
That would be a prerequisite to rule out by migrating to the OH2 binding alternative before starting any general migration activity.

hafniumzinc · October 23, 2022, 9:37am

I’m not wrong. He specifically said

which I also quoted.

As you say

Exactly what I said.

mstormi · October 23, 2022, 10:11am

well you said

and I don’t see that he’s using any v1 item in the orig post so this doesn’t apply.

I wouldn’t think he referred to ‘things’ in terms of OH Things as those were introduced with 2.0, long before 2.5.

hafniumzinc · October 23, 2022, 10:30am

I interpret his words differently.

I’m certain he is referring to openHAB Things.

Either way, @Max_G can enlighten us, but we’re both saying the same thing - you can’t use OH1 Item syntax in OH3 like you used to be able to in OH2.

Max_G · October 23, 2022, 12:46pm

I actually read quite a few of your posts; e.g. [OH3] Semantic Model setup via tags in configuration Items files

Yes, had a look at these, but the 'big picture is what I am missing.
It favours the UI, but the case for ‘pro’ is weak.

Do I need the model?
If so, does it need to be done first?
Assume I modify my items files suitable for import, can I later bring these into the UI?
Is a mixed mode possible? Leave existing stuff in text files and add new stuff in the UI (if this is ‘strongly recommended’ approach).
What must be configure in the UI? Things, groups?
What can stay in text files?

Well, guys, don’t get bonkers over what I meant…

I moved from v1 to v2 and may have or not used specific v2 functionality. Can’t really tell; too long ago.

These are the only ‘things’ I have:

// interval = minutes for astro
Thing astro:sun:home  [geolocation="-27.164855,152.701568,200", interval=60]
Thing astro:moon:home [geolocation="-27.164855,152.701568,200", interval=60]

Thing astro:sun:minus90 [geolocation="-27.164855,152.701568", interval=60]
{
    Channels:
        Type start : set#start [
            offset=-90
        ]
}

and I apologise for not having included some system info:

* Platform information:
  * Hardware: Raspberry Pi 3 Model B Rev 1.2_
  * Host: rpi3ohv2 Kernel: 5.4.51-v7+ armv7l bits: 32 Console: tty 2
  * Distro: Raspbian GNU/Linux 10 (buster)
  * OpenJDK Runtime Environment (Zulu 8.31.1.122-linux_aarch32hf) (build 1.8.0_181-b122)
* Version: 2.5.11 (Build) (apt-get), text-based config
  * binding = astro, exec, logreader, network, ntp, systeminfo, fritzboxtr0641, expire1, mqtt1, weather1
  * ui = paper, basic, classic, restdocs
  * persistence = rrd4j, mapdb
  * action = mail, mqtt
  * transformation = map, javascript, xslt, scale, jsonpath

There are a few v1 bindings in there; which I am aware need some modifications, some of which I have made and commented out.

This is a representation of my item file style:

String   spm_MAC                        "MAC address [%s]"                          <network>       (gSpProModbus)    {mqtt="<[mymosquitto:ArgyleCourt/Shed/Modbus/MAC:state:default]"}
String   spm_IP                         "IP address [%s]"                           <network>       (gSpProModbus)    {mqtt="<[mymosquitto:ArgyleCourt/Shed/Modbus/IP:state:default]"}
String   spm_Version                    "Modbus controller firmware [%s]"           <settings>      (gSpProModbus)    {mqtt="<[mymosquitto:ArgyleCourt/Shed/Modbus/Version:state:default]"}
String   spm_Name                       "System [%s]"                               <settings>      (gSpProModbus)    {mqtt="<[mymosquitto:ArgyleCourt/Shed/Modbus/Notification:state:JS(splitMqtt0.js)]"}

Rules are all DSL based.

I am on DarkSky which I replace with OpenWeather.
Want to use mosquitto as MQTT broker.

It seems that file-based and UI-based items can coexist?!

Andrew_Rowe · October 23, 2022, 1:29pm

No

As Markus said

In other words, it is there for people who are just starting to use openHAB 3 and have never even seen OH2 or OH1

mstormi · October 23, 2022, 2:11pm

No it’s fully optional.

Well yes but that doesn’t mean it’s recommended. Read https://www.openhab.org/docs/configuration/#versatility .

Note that that’s not really new and has been like that in OH2 already (just the admin UI was a different one).

The only thing you cannot configure via text is the new user UI itself.
Which all by itself is optional.

hilbrand · October 23, 2022, 3:57pm

You can just migrate with most of your configuration. Here are some suggestions:

The openHAB v1 bindings are not available anymore as was said. So you need to use a V2/V3 replacement. You could start with doing this already in your 2.5 configuration. (Except for expire which has no replacement in openHAB 2, but does have in openHAB 3, and weather also requires a different approach). If you use mqtt heavily this is probably the most work.
paper and classic ui are gone in 3. Basic is still present and works the same as before.
If you want to start directly with openHAB 3. Just copy your configuration files, and just remove the V1 bindings and paper,classic from your system configuration (so openHAB doesn’t try to load them) and replace the removed v1 bindings with the V2/3 variants (just keep the configuration files, and rewrite them with V3 notation)
You mention habpanel, but your configuration doesn’t seem to install it. Do you maybe use paper ui for this? You can still use habpanel though with the same configuration.

Max_G · October 24, 2022, 9:32am

Huh, this sounds like a plan…

HabPanel: I may have identified the wrong tech; I have one panel on the wall, where I can’t remember how I did it (yonks ago).

I use only the classic UI:

rlkoshak · October 24, 2022, 3:26pm

Definitely go through the Getting Started Tutorial. I find the people who have the most trouble with OH 3 are long time OH 1/2 users who skip the Getting Started Tutorial, thinking they already know what they need to know.

See A Deep Dive into the Semantic Model after reviewing the Semantic Model page in Getting Started. For now the model is used in three different ways:

to provide information needed by HABot to do it’s natural language processing
to build the automatically generated parts of the Overview page
there are some actions that can be used from rules

Most who use the semantic model at all do so for 2. If you don’t plan on using MainIUI, skip it. You probably won’t get enough benefit for the work to make it worth while.

You can still use sitemaps. Or you can use MainUI. If you use MainUI, you will probably want to set up the semantic model so that you can get those automatically built parts of MainUI. See the Pages section of the Getting Started Tutorial for some details.

You can’t get away without Things any more. There is no other option.

Migration depends on whether you want to minimize the changes required to your current config, or whether you want to use new capabilities in OH 3.

If you want minimal changes:

You’ll have to translate your MQTT Item configs to Things. There is no way around that. You may want to use .things files or, if you use the UI see OH 3 Tips and Tricks, in particular the “Buying in Bulk” sections.
Except for removing any OH 1.x binding configs, leave your Items as is. Skip the semantic model entirely. You’ll have to add the channel link config to connect the Item to the correct Thing Channel.
There are a few minor breaking changes in your rules you’ll need to address, particularly the move from Joda ZonedDateTime to java.time.ZonedDateTime which have some minor differences. The executeCommandLine Action works differently too and if you use the MQTT publish Action, there’s a new action that handles that.
Your sitemap should work as is. There are special instructions to migrate HABPanals.

This may push you in the second direction.In that case I recommend the following.

1 Create/discover the Things in the UI.
2. Recreate from scratch your Items using “Create Equipment from Thing” which can let you create dozens of Items all at once automatically linked to the Thing Channels and situated in the Semantic model
3. Bring over rules one-by-one and adjust for breaking changes and potentially changed names.
4. Install from the marketplace widgets and or create custom widgets and apply those to your items.

I’m not sure there’s any advantage to moving the Groups in the UI and keeping the rest of the Items in files.

There are some neat opportunities in UI rules with the rule Condition clause and rule templates. But there are limitations too, such as no being able to easily share variables between rules.

There is for Items but, if you plan on using the semantic model, it’s faster and easier to “Create Equipment from Thing”.

I’m a strong proponent of doing the semantic model in the UI and only in the UI because of this. There are too many tags and you have to keep them all straight. In the UI it presents all the appropriate tags for a given context. You don’t end up with impossible situations like a Location with a Property tag and the like or typos in a tag name through the UI.

Also, managing Group membership is a pain in the UI right now so retrofitting existing Items into the semantic model is painful. That’s why I recommend recreating the Items which automatically sets the Group membership for you.

No

No, but if you wait it might cause more work later on.

Yes, there’s a “Create Items from text definition” option.

Yes, but with the usual caveat that having two ways to configure something active at the same time can cause complexity and confusion.

Custom MainUI widgets and rule templates. All else can be configured in text configs. However, there are a few things that might not be possible for text config Things and it’s way easier to automatically discover Things in the UI than it is to get the text file syntax right (for those bindings that support that).

It is possible to apply default widgets in the .items files but it gets complex and troublesome really fast. OH 3 makes heavy use of Item metadata.

Pretty much everything else. Though some things will be harder in the text files than in the UI since you can’t make syntax errors in the UI quite as easily and that tends to be the part that most people struggle with for both the things and the semantic model.

Yes.

Max_G · October 25, 2022, 6:58am

As always: thank you for taking timeout to reply! (Much appreciated, not only by me, but I am sure the community as well)

Yes, can imagine the skipping part; but I read it, based on “if I go OH3, I better understand it”, as I hate redoing things.

It is this kind of feedback I was looking for; someone who’d done it, may even have failed and regrouped. Yes, it is lame to let others fall on their nose, but why not benefit from their wisdom.

Things: understood loud and clear, why I have started setting up things in the UI.

Actually both, but understand this may not be possible.
But… I am happy to go the hard way, for a better set-up.
I have seen your post elsewhere, where you said you stared importing items, then dropping this approach creating these in the UI. (yep, in the link Buying in bulk 2)

The items files allow for a segmented piece of work. While my handful of items in the UI are already cumbersome. If I need a minute per item, I am looking at over 1,000 minutes (16h) to add these.

Yes, happy to create things; already started.

Yes, add channel link; which is what doesn’t work ATM as stated in another post.

Yes, time … am aware.

Yes, have publish action already in rules (commented out for migration)

Will do just that… (am convinced now)

I started out with the semantic model as many groups where locations.

… for the rest I have to re-read and regroup, and explore the concepts explained.

Again, thank you kindly for your reply.

rlkoshak · October 25, 2022, 2:41pm

This is one reason why I’m really big on “create equipment from thing” (I guess they renamed that to “add equipment to model”. In one go you get the Equipment Group Item created and made a member of the right Location Group and you have one form to create all the Items linked to the Thing’s Channels. You just need to select the Channels and set the usual Item stuff like Label and the Point semantic tags. It greatly reduces the amount of time required.

Let’s say I want to add the UV readings from OpenWeatherMap.

First navigate to the Thing and open the Channels tab.

pick-thing

Create equipment from thing, select the location and all the Channels.

select channels

Often the binding will supply reasonable semantic tags, label, and other Item settings so you could just accept them as written. But if you want to customize something simply edit the fields in the form. For example, in this case, it only supplies reasonable semantic tags for the first day. So let’s fix the second day’s semantic tags. Except for the Item name, you can change anything later on.

correct item

Once everything is as you want, create the Items. I fixed the categories and added Status/Timestamp to the date Items and Measurement/Ultraviolet to the index Items. The date Items already had time as the category and I added sun as the category for the index Items. I was happy with the labels and the Item names. The whole effort took under three minutes.

Create the Items and show they exist and are part of the model.

create-items

In under five minutes I created a Group (the equipment), made that Group a member of my root Location in the semantic model, and created and configured 12 Items which are automatically members of the Equipment Group. Because everything is semantically tagged, these Items automatically show up in the Overview page.

Hmmm, that doesn’t look great so next I would go and fix those Item labels to make it more apparent which Item represents which day. It pays to spend a little more time on that Item creation page. I’d probably eliminate the DateTime Items entirely. I don’t need them. But if I had a use for them, I’d set their visibility to false. I’d install List Item Widget for OpenUV Binding [4.0.0.0;4.9.9.9] and apply that to each of the UV index Items as the “default list item widget” which will change how they appear on that card in the Overview tab.

Let’s say I hate what I’ve done and want to start over. It’s super fast to delete the Thing and the Items and the Links.

delete

And now they are gone. You could keep the Items or delete them. I usually delete them. Now they are all gone and I can redo it all in one go without needing to navigate to each and every Item.

Max_G · October 30, 2022, 5:35am

Thank you!
I appreciate the work you’ve put into showing me how this all fits together.

One question, why does the UV stuff have its own place in the semantic model? E.g., why it is not under the Weather? (Or was this for demo purposes only?)

rlkoshak · October 31, 2022, 2:13pm

It’s just where I decided to put it. I don’t actually have a use for UV in my home automation so all of the above was just for demonstration. I didn’t put much thought into is. I probably would put it under the Weather Equipment but that’s mostly personal preference. That sort of structure is up to you. The model is there to serve you. It is going to mostly depend on where you want the Items to appear in the Overview tabs.