Z-Wave system OH2 to OH3

Hi Z-Wave lovers,
I am basically ready to migrate my file-based OH2.5.9 on a RPi4B with 40 Z-Wave nodes, to a file-based (for now) OH3.2.0 on a new RPi4B. The .Items file has Z-Wave item channel names generated by OH2 PaperUI.

OH3.2.0 is loaded and running on the new RPi, and a new Aeotec Z-Stick gen 5 Plus+ is a clone. BUT I hesitate to power up and include the Stick before I understand if OH3 Z-Wave Binding/database will update/tweak the Z-Wave Network or Things, thereby preventing a return to OH2 as a fallback solution.

Enlightening is much appreciated.

Hi Bjorn,

First thing’s first: do you have any securely included devices? If so, you need to copy the Network Security Key over. You can find it in the thing settings for your controller in OH2. It’s also in a file somewhere, but I think it’s easiest to get from PaperUI. This should definitely be done before you discover devices in OH3.

Why a new one that’s cloned? I would just move over the old stick, on the assumption that you’re going to decommission OH2. The clone should work, but to me that’s just introducing a variable that might cause problems.

Either way, when you plug in the Z-Wave stick and boot up, MainUI should automatically pick up all included devices. You can edit the thing IDs to match your old ones, or update your .items file with the new channel IDs

Nothing is done to your Z-Wave stick by OH, so you never need to fear falling back.


It’s a property on the ZWave controller Thing. I forgot to grab it when I migrated and ended up needing to pull it out of the JSONDB entry for that. I couldn’t find it in any other files.

@satman The zwave network lives on the controller hardware. So if you are careful to give the Controller Thing the same ID on OH 3 as you had it on OH 2.5, all the remaining zwave node’s Things will be discovered and given the same ID as well (the ID is generated based on the controller Thing’s ID). I replaced the randomly generated string with the very clever and descriptive “dongle”. :stuck_out_tongue_winking_eye:

In addition to UIDs and the security key, the last thing to worry about is you’ll need to wake up your battery powered devices a few times for them to be rediscovered properly.

But even if you don’t do any of these things on OH 3, unless you change something (e.g. add or remove nodes from the network on the OH 3 system) you’ll always be able to plug in the Zwave dongle into your OH 2 instance and it will work as expected. So I agree, trying to use a cloned controller is way overkill here and adding unnecessary complexity.

Thanks Russ,

Nop, no security included devices.

A good question! I was thinking that if things go very wrong, then settings in the Z-Stick could also be altered and a full backup unit would save me. Just pull the power plug and power up the spare (plug & play). Its a small cost.

So, that’s my concern. I was hoping to avoid editing anything. Can you explain why I would have to edit IDs etc.? I would have to define the Z-Stick port though, and how do I do that? By Stick reinclution or…?

That’s comforting.

The link between the Item and the Thing’s Channel is based on the Thing’s ID. If you don’t edit them (see my post above) the Thing’s will have a new and different ID and you’ll have to relink them to your Items.

If you don’t want to edit anything, you need to ensure that the Things end up with the same IDs. But that’s as easy as making sure the Zwave Controller Thing has the same ID as on the old system.

Follow the same instructions as you followed the first time you configure Zwave.

  1. Create the Zwave Controller Thing
  2. Configure that Thing with the same UID, security key, and port where the Zwave Controller resides.
  3. Scan for new Zwave devices.
  4. Accept the Things from the In box.

Thanks Rich,
First, my aim is to build a cold redundancy unit (plug and pay).

That’s understood, but where and how is that done? Off line with the zensys tool before joined with RPi or…??

No battery devices no worries.

Do. Not. Touch. The. Controller.

Things and Channels are openHAB concepts. A Thing ID therefore is an openHAB concept. The controller doesn’t know or care.

Just follow the instructions to install and use the Zwave binding and when you create the Controller Thing, replace the ID field with the ID from the old OH instance.

At this point you should be convinced that there pretty much is nothing you can do at this point to mess up your controller (unless you start mucking around with zensys tool). So go give it a try. Once you are doing it most of this stuff will become obvious. And even if you somehow manage to mess something up, it’s trivial to restore the controller with a backup.

But again, you pretty much can’t do anything to change the controller itself until it’s already working with OH. So it’s basically impossible for you to mess it up. This is super low risk. Go give it a try.

I would just add that you might want to try using your cloned stick with your working OH2 installation. If you can swap sticks without issue on OH2, then you remove “the cloned stick doesn’t work” as a variable in OH3.

As noted, OH won’t affect your Z-Wave stick. Keep in mind that if you add/remove Z-Wave devices in the future, you’ll want to reclone the spare Z-Wave stick to make sure it’s up to date. Otherwise, you’ll just end up moving the most current Z-Wave stick to your backup system. Doesn’t hurt to have a backup, though. I’ve heard of Z-Wave sticks failing, but not often enough that I personally worry about it.

All good advice. Depending on how long you plan on keeping the OH2 system, I’d add that it is increasing hard to keep the systems in sync.

I had this plan to have my rpi3 as a hot spare for my rpi4, both on OH3. However, add a new zwave thing, tweak a rule, make a UI graph, clone the zstick, etc and it becomes quite a project. It was further complicated as my older Aeotec Zstick could not use the Silabs NVM backup, so I had to have a backup using the older aeotec backup tool. Additionally the rpi3 did not like not have a zstick removed, so had to restart OH after switching the Zstick back there anyway. At one point I was so far behind, I just installed the Rpi4 backup on the Rpi3, but that was a lot of work to fix the issues like the MQTT and other bindings. So, short term no problem but as you get going on OH3 going back is going to be problematic.

My two cents.


The 10 digit hex string in the z-wave controller’s Thing Identifier (“39d51d11b2” in the example below) must match the value in the channel parameter of the .items file. This can be done either by changing the controller’s Identifier to match what is in the .items file when creating the controller’s Thing or by doing a mass change in the .items file.

Dimmer HallLight  "Hall Light"  (gDimmers,gLights) {channel="zwave:device:39d51d11b2:node13:switch_dimmer"} 

One way to deal with this is to use some sort of source control software like a git server. As you make changes to your “production” system check those changes into source control. Then your spare is only a git pull away from having all the latest checked in changes.

Good idea. I’ll look into that.



Thanks a million for your precious time guys,
Very fruitful and enlightening discussion. Learning something every day.
Take care.

I have finally come around to testing my first OH3 (3.4.x) installation. Items, Rules and Sitemap are transformed as needed.
Dry runs without a Stick show that Rules seem to work OK.
Astro and Z-Wave binding is installed.

A cloned Z-Stick (of OH 2.5.9 Prod unit) was attached to RPi4B HW rev 1.5.
During Z-Stick inclusion the old Stick ID (8 characters) was reused.
A scan was initiated and all Nodes came up ONLINE, but does that mean they are Included??

My problem is that Rules do not seem to have contact with Things/Items.
I use Sitemap for insight but nothing apeares, and the event log basically stops after all Nodes have come ONLINE.

Only ERRORs appearing in the event log are “Could not cast NULL to java.lang.Number”, which is correct and should disappear a soon as Items get populated with numbers from related Things (Power, Energy etc.)

I am apparently missing something very important here.
Any suggestions?

I guess it depends what you mean by “Included”. If you mean included to the Zwave network than yes, all that stuff resides on the controller. If you mean included in openHAB, that’s what the Things represent so if the Things have been accepted from the Inbox and they show ONLINE they are included there too.

If you didn’t follow each part of step 2, the Thing ID for the Controller and all the Zwave Things will be different from before. That means the links will no longer be valid between the Channels and the Items. You’ll need to recreate those Links or recreate all the Zwave Things using the same Thing ID as you had before.

Does this also apply to the Astro items?


See, that’s the thing - I did all steps except security since no security has been applied to OH2 and the Stick. And I did change the Stick ID in openHAB to be the same as on the stick.
I should say that I did not have to include Things in openHAB.
If I now hit Things and +, there are only 2 elements: Astro and Z-Wave, and if I hit Z-Wave and +, not-included Things should appear, but there are none. Hence, I assumed all good to go.
So, what the heck is missing here?

Sunset happened at 17:33 CET and in OH2 log I see:
(2023-03-07 17:33:00.008 [vent.ChannelTriggeredEvent] - astro:sun:home:set#event triggered START)
No such message in OH3, so there could be more issues here??

This doesn’t make sense to me. What Stick ID that’s the same as on the stick? The ID I’m talking about is the Thing ID which frankly has nothing to do with the zwave controller stick.

That needs to be the same as it was on the old system or else all the openHAB Things will have a different ID and the Links to your Items will be invalid.

Or you can just relink the Channels to the Items with the new ID, though that’s more work.

Above you said “all Nodes came up ONLINE”. So you’ve already included all the Nodes and already have all the Things. The Inbox isn’t going to show you stuff that you’ve already approved from the Inbox. It’s only going to show new stuff and stuff you’ve not already approved.

In OH 3 I don’t know if ChannelTriggerEvents are logged to events.log by default. Look in $OH_USERDATA/etc/log4j2.xml and see if that logger is set to INFO. It it’s ERROR you’ll need to change that to INFO to see those events in events.log.

Sorry for presenting confusing semantics, which demonstrates my lack of knowledge on how Z-Wave communicates and integrates with OH.
I understand what you suggest(ed) and it is exactly what I have done. During Stick inclusion I entered the same ID and Port as in my old OH2. The ID is also part of my Item channel names.
I know that the inbox should be empty, but if it wasn’t it would be an indication of trouble.

Do you happen to know the full folder name on RPi? I will check and fix it.

So to my second worry. I see nothing happening on the Sitemap, which is also a sign of trouble. No data to present? My default.sitemap file is located in /etc/openhab/sitemaps and is a clone of the OH2 file and should work if OH3 can find it.

Do I have a com problem? I will check the .events file first to see if there are any entries, and take it from there.

If the Items are not updating, nothing’s going to show up anywhere.