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.