Why is Z-wave inclusion so @#$* hard?

I’ve got a mid-sized Z-wave network (~50 nodes) controlled by a Zooz ZST39LR, using Z-Wave JS UI (latest versions as of today). Things generally work reliably… except when I try to add a new device.

Most devices I add are 800 series devices (often made by Zooz – same brand as controller), and even with “SmartStart” QR codes, it’s just a nightmare. I wanted to ask how others go about including a new device in case I’m making some boneheaded error. Here’s what I do:

Method A:
0. Relocate device to the same room as my controller. Inclusion never works via mesh.

  1. In Z-wave JS UI click on the blue circle “hamburger menu” in bottom right corner, then hit the green infinity button above it.
  2. Select “inclusion”, hit “next”, then enter name and location then hit next.
  3. Choose “Default”. Hit “next”
  4. Frantically initiate inclusion on the device.
  5. 7 times out of 10 it times out. So restart inclusion in both Z-Wave JS UI and on the device.
  6. If I make it this far, it asks for the 5 digit PIN. I enter it. Very carefully.
  7. 3 times out of 4 it includes without S2 security (even though the device is capable of it)… sometimes because it says the S2 PIN is wrong (I promise it matches what’s printed on the label.) and other times it times out waiting for a response and other times it just successfully includes without S2 security. So then I exclude the device and go back to step 1.

Periodically I try factory resetting the device just in case. Sometimes that helps. Usually it doesn’t. Sometimes I try restarting my Home Assistant instance. Also usually doesn’t work. I’m usually able to eventually include the device (in which case I uninstall it from the room with the controller and reinstall it in its “real” location – lots of fun for light switches!) but it can take more than an hour to include a single device… Though things do work pretty reliably once inclusion has completed.

Method B
Steps 0-2 are the same as above
3. Choose “Scan QR code” and hit next. Of course the Home Assistant app, and website are unable to use a camera, but fortunately the iOS camera app can copy the numerical string contained in the QR code. So choose the “text” option and paste it in.
4. Wait a long time (like an hour… or overnight). Try initiating inclusion on the device. Wait longer. Twice this has worked, but for the rest I eventually go back to Method A.

I feel like this can’t be expected behavior or the Z-wave standard would have shriveled up and died years ago. So I must be doing something wrong. Can anyone help set me right?

Thanks so much!

I have a similarly sized Z-wave mesh and a 500 series controller. I can’t remember ever having an inclusion problem. That said, I almost never use S2 security, not sure I see the value.

Just my 2 cents, not easy to compare with any valuable insight, but I think all radio networks are difficult to compare as they are naturally all “snowflakes”. I marvel that engineers can make it work at all. :slight_smile:

  1. You need to setup HTTPS in order to use a camera with Z-Wave JS UI.
  2. What does your resource utilization look like on the host that you run Z-Wave JS UI on?
  3. Do you have your controller on an extension cable?
  4. You don’t have to put your hub into inclusion mode first then rush to put your end device into inclusion mode. You can put your end device in inclusion mode first then put your hub into inclusion mode and it will still add.
  5. Also in Z-Wave JS UI you can go to SETTINGS > Z-WAVE > adjust the Inclusion/Exclusion timeout value. I have mine set to 120 seconds.
  6. It shouldn’t take an hour to include a device. What type of devices are they? Battery powered or mains powered?
1 Like

To help with your Method A, steps 4 and 5… First, open the Z-Wave JS control panel, go to the “Settings” tab, and then click on Z-Wave. Scroll down and change the “Inclusion/Exclusion timeout” to 60 seconds or whatever you like. Now you can replace “Frantically” with “Leisurely” in Step 4.

Also - Is your Zooz stick plugged directly into your system? If so, consider getting a USB extender cable and moving the stick a bit away, in case it’s picking up interference from the computer.

Edit: What Cornell said… :slight_smile:

1 Like

Just wanted to add another vote for the extension cable, I have a Zooz ZSE41 800 series door sensor with the ZST39 800 series controller that would only work reliably with every other closure. A 3-foot USB extension to move the ZST39 away from the RPi made it 100% reliable, haven’t had a problem since.


The 800 should have a longer range but no mesh as far as i understand.

I think you’re confusing LR (Long Range) and standard Z-wave. Standard Z-wave is certainly a mesh network and is supported by 800 series controllers. I believe it’s an either/or choice.
Z-wave JS UI has just recently added support for LR.

A device has to support NWI (Network-Wide Inclusion) for in-place inclusion to work without direct access to the controller. I’m guessing the age of nodes in the mesh will impact this as well.

It is an “either or choice” for each device. But the stick can certainly support both protocols simultaneously. Most of my devices are connected using mesh, but I now also have a few new ones that are using LR.

Thanks so much @cornellrwilliams !

  1. I will look into this. Once I have enabled HTTPS will the camera function in the iOS app just magically start working?
  2. HA is running on a Home Assistant Green. Currently RAM is 1.2/4GB, processor is at a few percent, and storage is 25% used.
  3. Thanks for the pointer (and @landolfi too). I’ve ordered an extension cable and will try it!
  4. This option is amazing! Thank you (and @PecosKidd !) for cluing me in! So much easier! (Devices still constantly time out when trying to include but I no longer have to rush as much. The timer for devices to remain in inclusion mode is now the gating factor… as is apparently the timer for devices to respond to the S2 PIN. (Maddeningly the device will still add without security most times — prompting the need to then exclude and further running up my node numbers — even if I check the Force Security option in inclusion…)
  5. Today I was adding a much of smart lightswitches (obviously mains powered). They were mostly Zooz 800 series. It easily can take an hour of trying and retrying before finally successfully adding and that’s not even including the time it takes to temporary wire the switch in the same room as the controller (since inclusion basically never works far from the controller)…

@istapeter I mean that I have practically no success ever trying to include a device that is physically far from the controller (and therefore must presumably have its messages repeated via another pre-existing node in the Z-wave mesh network).

@PecosKidd and @mterry63 : if LR is non-mesh, then for devices that support “800 LR” is there an option within Z-Wave JS UI to select whether this particular device I’m trying to include will join the network via standard mesh or LR? I’m slightly concerned because my standard process is to physically move a device close to the controller to include it and then move it to it’s final installation place… so is there a risk that an LR capable device that will ultimately be placed far away (but with a strong chain of intermediate devices to repeat in between) will unintentionally include in a non-mesh way and therefore lack connectivity when moved to its final place?

To get the camera scan function working, be sure to copy the URL from here (Settings/Home Assistant Cloud):

Then log out of the phone companion app and when you log back in, use the URL you copied above for your Home Assistant URL. The URL will be a random bunch of characters because it’s encrypted.

Same boat. Same thoughts.

1 Like

LR is a direct connection between the controller stick and the device. It does not use the mesh method of intermediate devices to repeat the signal. So initially connecting a device using LR while close to the controller and then moving it to it’s final destination should be fine. In theory though, this should not be necessary with LR devices. You should be able to connect to them just fine in their final destination, since the signal reaches much further.

It’s actually not good practice to connect mesh (ie, not LR) devices close to the controller and then move them. This can cause the mesh to be built inefficiently, with an incorrect map of which devices it should use as repeaters. This might be a source of some of your communications issues and lag.

Have you used the network map feature of the Z-wave JS UI interface to look at how your devices are connected to and communicating with each other?

@PecosKidd Thanks!

Re network map: I’ve tried using the network map but it can become pretty un-useful once you have a lot of devices (everything is drawn on top of everything else…). And again, everything seems surprisingly solid once devices are included . It’s just the inclusion that is a huge pain.

Re LR vs mesh: is there a way within Z-wave JS UI to see whether a given node is connected via mesh or LR? Is this a permanent attribute of the node (the way that security levels are set upon inclusion and do not change until exclusion/re-inclusion) or do compatible devices, e.g., every day try to connect via LR and if that doesn’t work then fall back to mesh? (Most of my nodes are 800LR compatible, but I don’t honestly know what “mode” they are in… if that’s even a well-defined thing.)

Re moving devices in order to include: I’ve just qualitatively had so much more trouble trying to include devices when they are further from the controller. (TONS of timeouts… and the very rare occasion inclusion doesn’t time out, security times out and the device ends up included without S2 security.) Perhaps it’s superstition but I’ve been moving devices to include them, then moving them to their final position… then if there appear to be any problems I’ll rebuild routes for that node. Either way, I’m in the process of a big rollout right now (replacing a bunch of light switches) and afterwards was going to try to see if things seem stable. I’ve read elsewhere (e.g., here) about the importance of doing a global “heal” (which I’m assuming is called “Rebuild Routes” in Z-Wave JS UI?)… but I’ve read elsewhere (e.g., here) that this should generally be avoided. Any advice?

Thanks again to everyone for all of this! Unfortunately the only “introduction to z-wave” style articles I’ve found stop short of some of these more-nuanced issues, so advice in forums like this is incredibly helpful for someone like me who is trying to learn!

@landolfi Thanks! Dumb question though: in order to get the camera working, do I also have to create my own SSL certificate if I’m using Nabu Casa’s Home Assistant Cloud?

Yes - the “Protocol” column shows blue for standard (mesh) connections, and purple for LR connections.

As far as I understand this is a permanent attribute of a node, in that it will not automatically switch or fall back to the other protocol. You could, however, manually exclude a node and then include it again using the alternate protocol if desired.

I have a Aeotec gen5+ stick on an extension cable, using Z-WaveJS-UI. 67;devices connected to it: fFibaro, Aeotec, Shelly, Vesternet, Qubino, no Zooz.

I did have problems with S0 security back in the day. Don’t ever use that, there are ay too many things wrong with that. I have no locks or other things requiring strong security so I use unsecure, but S2 security should be fine too. I do that also because you cannot mix security levels when you use direct associations, which I use a lot.

I seem to remember S2 security requires close proximity for pairing though because it limits send power for inclusion (security reasons).

Z-wave long range requires direct connections to the controller, so i.m.h.o. using mesh gets you longer range.

But anyway, my situation is probably a bit too different, but I never have problems. I always pair in place, it always works at first try. Connections are always stable. So it is definitely not a given that Z-wave is hard. I have way more problems with Zigbee (same number of devices).

Info about Z-Wave Long Range and Mesh from the source:

Thank you again, @PecosKidd
I checked and all of my devices — most of which are 800LR compatible — are connected as Z-wave mesh rather than LR. Is there something I have to — or can — do in the inclusion process to steer between the two?