Has anyone figured out how to accomplish this migration without messing things up?

ZWaveJSMQTT has things like network diagnostics, backup and OTA firmware updates. There’s no indication that ZWave JS will ever get those things. But migration risks losing the network and/or the HA namespaces.

There have been threads on this in the past but they always seem to end in confusion and disagreement revolving around the various ways these components can be installed.

Maybe by now, someone has it all figured out?


Maybe this will help you (ignore the Docker parts):

Otherwise just take a full backup, stop the Z-WaveJS addon, start the Z-WaveJS2MQTT addon, set it up to allow Websocket connection and use the correct USB path, wait for interviewing to complete (in case of battery powered devices you might want to wake them manually to speed up this process) and then reconfigure the Z-WaveJS integration within HA to point to the new addon. If the versions match up I don’t think (I know, assumptions) there should be any change in entities.

Holy smoke.

“Stop the zwave network in the prod HA Start up the zwavejs container, go into the control panel, and set it to use /dev/ttyACM0,”

See, that’s what I’m talking about. I can’t even parse that sentence. What does “prod” mean" What “container” are they talking about?

Some say to stop the “integration”, others say no, stop the “add-on”.

“reconfigure the Z-WaveJS integration within HA to point to the new addon”… um… huh?

Why would everything have to be interviewed again? I thought the mesh data was all in the controller?

A couple of years ago I had a full root canal on a “complex” tooth. A total of 3 hours of drilling, spread over 2 appointments. I think I’d rather repeat that than have to rebuild my ZWave network, and run around the house with my collection of micro-printed Chinglish instruction sheets, trying to get every device to cooperate with inclusion one more time.


What bothers me the most in this story is, that when the old Z-wave integration went on the deprecation list, we were told to migrate to ZWave JS, that was the BEST thing to do.

So we went thru that painful migration, and now everything is working somehow, we have to find out, that ZWave JS is far from optimal (lack of firmware updates, lack of network map, just to name something).

So, we wait patiently until this get sorted. But it does not get sorted.

So if we want to get the full functionality, we have to migrate again.

And when we start moaning about this, we get that story, like always, about volunteers and no responsibility and all that blah blah blah.

Well, I’m still really pissed about this, as I followed the advice of the devs, trusting them, that I do the best for my install, just to get disapointed again and been pushed to the next migration.

Don’t get me wrong, I love HA, I get the volunteer story. I participate where I can too. But this ZWave JS thing still makes me mad. I can’t trust anyone here again, as the best advice from today can be marked bullshit tomorrow…

And a CLEAR, BULLETPROOF migration manual is still nowhere to find…

I updated the terminology in that post.

I am finding the migration to be technically challenging and I was able to write those statements. I am 3 weeks into sorting through the migration across 2 homes and I am probably still 2-3 weeks away from being able to do a seam-less cut-over.

If you want to get started, work on Step #1 - and ask questions as you progress.

1 Like

The official docs have instructions on how to switch addons. As long as you follow the instructions, step-by-step, you won’t lose any device or entity customization.

Obviously step 3, installing the add-on, is the bulk of the work. There are docs you can read ahead of time to be prepared. This would be necessary if starting from scratch anyways.

If there is some confusion with those steps, please ask for clarification as to which step you are having trouble with.

The only thing I’d add to the official docs would be that after installing zwavejs2mqtt, make sure all devices have completed their interviews (i.e. wake up battery devices manually). The interview status must be “Complete” before they are usable in HA. This is the same requirement when migrating from legacy zwave. The reason for this is that the driver maintains a cache of the node information discovered during interviews. The cache is lost once you switch add-ons, so it needs to be rebuilt. Of course, there are ways to copy the cache between add-ons. That is additional complexity that can’t explained in a few sentences.

Other guides that reference different platforms besides HAOS or docker containers are going to include unnecessary information. I would ignore the linked Synology guide. That is for migrating from Legacy Z-Wave to zwavejs2mqtt on Synology. It has almost no relevance to what you want to do. I would also not trust any guides or experiences that are more than a couple months old.

Switching from the zwave-js add-on to the zwavejs2mqtt add-on is not the same as switching from Legacy zwave; it is not a “migration”. The driver software is exactly the same, there is no difference from HA’s perspective. It’s analogous to switching an MQTT broker from Mosquitto to Hive MQTT. There is no loss of network information.

Since you’re using HAOS, you can make a backup before attempting the switch, and restore if something goes wrong?

You do not have to rebuild the z-wave network. That was one of my main fears also. That said, if you start doing random stuff - you may find yourself doing this. Hence the purpose of the migration guide I’m starting on.

If you are running on dedicated hardware (like a pi), my first recommendation is to get another one as you’ll need that to stage your test system while working through the migration process. You’ll move the zwave stick carefully from one system to the other and back as you work through the process steps on your own time. While I’m on docker the same principals apply. I’ll switch the network over to the test system, work on the current process step for an hour or so, then switch back to the existing system.

EDIT - I’m on the wrong topic here. I’m talking about zwave deprecated to zwave_js migration. This topic is about zwave_js to zwavejs2mqtt migration - which I have no experience with. Apologies for the off topic content.

Like it, as you know I found functional differences on devices like motion sensors, water sensors and switches that have required application rework. Since I don’t like surprises, the parallel system approach that @finity brought to my attention has allowed me to work through these issues one by one on my own time and switch back to the working system in between. If I had just migrated as documented, I would have been in a world of hurt with sketchy supervisory control on the HVAC and water systems, alerts not occurring, etc.

I’m not casting any criticism on your guide, it’s just not really relevant to this discussion, which is switching from the Z-Wave JS Add-on to the ZWaveJS2MQTT add-on. Switching add-ons is much different, and simpler, then migrating from Legacy Z-Wave to Z-Wave JS. There is no behavior change from the perspective of HA.

there was a post made by petro in one of the guides on switching from the old zwave to the new zwavejs that talked about how to switch from the zwavejs add on to zwavejs2mqtt by copying the zwavejs database from one addon to the other.

I can’t find it easily tho so you will need to read thru those if you want to find it.

I haven’t ever done it myself so I have no experience with it.

Yep I’m on the wrong topic. Apologies.

The official documents say this:

How do I switch between the Official Z-Wave JS add-on and Zwavejs2Mqtt?

Switching does not require renaming your devices.

Disable the Z-Wave JS integration. Do not remove the Z-Wave JS integration or you will lose all device and entity naming. This will automatically stop the official Z-Wave JS add-on.

Note your network security keys from the official add-on.

Install and configure the Z-Wave JS to MQTT add-on, including setting the location of your Z-Wave device and the network security keys.

Add the Z-Wave JS integration again (even though it is still installed), and uncheck the “Use the Z-Wave JS Supervisor add-on”. Enter the correct address for the community add-on in the URL field in the next step.

Uninstall the official Z-Wave JS add-on.

Enable the Z-Wave JS integration.


Just in this topic is posted this:

According to that, the guide is incomplete and will likely fail.

I CAN’T try this just to test in a house, where everything is hanging on HA. Do you hear the family members already:
Is it failing again? Why do i have to poop in the dark?

And I can go like this for a while. I’ve seen many different topics about this and every topic says something else and everywhere I see problems passing around.

I can’t migrate ZWaveJS to ZWave2MQTT without a guide, that assures me of being safe.

Actually I still hope, that ZWaveJS will be updated according the roadmap, but it is told me already, that no one knows, when it will be done.

Hopeless, that’s the only state, I’m in now. How more I try to find the needed info, how more hopeless it make’s me…

I’m not 100% sure of that.

the post I was referring to was made a long time back around the time that zwavejs was being introduced.

Maybe things have progressed since then or maybe more knowledge has been attained on how to do the switch.

It is very possible that since the controller software runs the same on both add-ons when the database is created on the new zwavejs2mqtt server HA won’t see a difference and just pick up the old names for the new server.

I know that is a lot of “maybe” but that’s the best “hope” i can give you.

Copying the cache files from one add-on to the other just saves you time. In that case there’s no need to re-interview the devices.

Either way, nothing is lost in the network (that’s stored on the controller) or nothing is lost in HA. As long as you follow the instructions.

I’ll ask again, what part of the official instructions is not clear? There has been no concrete answer to that, only hand waving and references to out of date guides, experiences, or here-say. Perhaps the docs for this FAQ could be improved, but not without some input.

I’m the OP and these are my feelings exactly.

Every discussion on this seems to go off the rails into ‘legacy’ Zwave. Let me try to clarify my situation.

I have the Zwave JS integration AND the Zwave JS add-on. I run Home Assistant OS. I want the additional features of ZWave JS MQTT, like network diagnostics, backups and firmware updates. I don’t actually need MQTT.

The mesh network data is in the controller - so why do I need to worry about a “cache file”? . I don’t know where the HA namespace live - in the integration?

If all I need to do is replace the add-on, does that guarantee - in blood - that the existing network and namespaces will not be affected?

When replacing the add-on, what exactly must I do with - or to - the integration?

1 Like

Copying cache files as possibility is not mentioned in the guide.

If you don’t do it, you need to re-interview device’s, i see. It is not mentioned in the guide. So if I did not read it here, i will end up with unforeseen problems, that I can not address.

That are only two things, i get out of one sentence in this conversation.

How many of such unforeseen possibilities are still hidden from my eyes and i will find them on moment supreme, not being ready to deal with it?

That’s what I mean. It all is confusing…

Hardly any of my z-wave devices were successfully interviewed on the first attempt. Or the second. Some required a full-factory reset right out of the box, which was some combination of hold-this-push-that-wait-30-seconds. Many had to be explicitly removed, and some even made that a struggle. Eventually I got them all working and by then I already wished I’d never heard of z-wave.

So anything that might require me to re-interview everything is a total non-starter. I’d rather just sell all the z-wave and start over with wi-fi.

I’m trying to get to ZWaveJS MQTT so that I can deal with problems - not just create new ones.

Step 3. in the guide says:

Install and configure the Z-Wave JS to MQTT add-on, including setting the location of your Z-Wave device and the network security keys.

configure. OK. What questions I can expect? do I need to prepare something? As I can’t see the configuration window anywhere, it is a step in the dark… Maybe to get stuck with questions, I do not have ready answer. Nice, half way of a migration.

Copying cache files is out of scope of that document. It involves using undocumented/debug functionality to access the add-on containers. Or, you can make backups, modify them, and re-upload them. If the guide as-is is not understandable, adding this information would make it even more difficult.

What some seem to be saying is that we don’t need to “re-build” the network in the sense of doing inclusion on every device all over again - but we may need to get them all re-interviewed. Because apparently there’s a cache file containing all that.

Having said that, I’m sure someone will jump in an say I’m wrong.