¶ How to Troubleshoot Z-Wave
Having trouble with your Z-Wave network (slow devices, devices not responding, difficulty paring/including devices, etc.)? Find some ideas below to help.
¶ Device will not add/include (or: how to do a general exclusion)
If a Z-Wave device does not pair, first try a factory reset or a "general exclusion." Consult the device manual for specific instructions on how to reset or put the device in exclusion mode. If you no longer have these instructions, some of the most popular ones are documented in the list of compatible devices (see the Instructions column). To perform a general exclusion with Hubitat:
- Connect to the hub and navigate to the Devices page in the sidebar.
- Choose Add Device in the top right corner.
- Choose Z-Wave, then choose Start Z-Wave Exclusion, and follow the exclusion process for your device.
- You will see "Unknown device excluded" (or the name of a specific device) appear on screen if a device was found in exclusion mode.
Then, try the inclusion process again. If the device still fails to pair or does not function after pairing, consider other possibilities below.
After any failed inclusion attempt, you will likely need to perform a general exclusion, as above, before the device will successfully pair again.
¶ "Ghost nodes" or failed inclusions
So-called "ghost nodes" can be created by failed pairing attempts or by force-removing a device from Devices instead of properly excluding it. "Ghost nodes" may cause network problems, either problems in operation or pairing new devices. To check for these nodes and remove them:
-
Connect to the hub and navigate to Settings from the sidebar, then open the Z-Wave Details page.
-
Look for any row in the table without anything in the Routes column and often without a link to a Hubitat device in the Device column; these devices may be "ghosts" (or at least have not had any traffic since the hub was rebooted and/or do not have a device associated with them in Hubitat). Functioning devices are never "ghosts," and blank routes are not necessarily a problem.
-
If you see a "ghost" you want to remove, select the Remove button (in the Status column) for that node. Wait several seconds for the page to reload, then verify that the device no longer appears in the table.
-
If you do not see a Remove button, select the Refresh button. Wait several seconds for the page to reload, then repeat step 3.
-
If you still do not see a Remove button, then:
- Try again; you may need to repeat the process once or twice before Remove appears; and
- Verify that the failed device is not actually "online." Assuming you know or can guess which device this might be, removing power from the device or performing a factory reset on the device may help (consult the device manual for how). The Remove option will not be presented if the hub hears back from the device on a Refresh.
TIP: Keep the "Logs" page (from the sidebar) open in another window/tab as you try the above. Any status messages from the Z-Wave radio will be logged as coming from "Hub."
¶ Locks and other secure devices
Barrier devices, including locks and garage door openers, usually must be paired securely and will not function if secure inclusion fails. To check if secure inclusion was successful, navigate to the device page, then look under Device Details in the Data section for zwaveSecurePairingComplete: true:
If you do not see the zwaveSecurePairingComplete field or if the value is false, try excluding the device and then pairing it again. The device may need to be near to the hub for secure pairing to succeed (consult the device manual to see if the manufacturer recommends this).
¶ Range issues
Z-Wave is a mesh network. This means some nodes in the network "repeat" signals to/from the hub and other devices, extending the range of your network beyond what the hub alone can reach. If you are having problems using or pairing a Z-Wave device in-place, range could be a problem.
To help eliminate range as a possible problem, try bringing the device closer to the hub and trying the inclusion process again (or if the device has already been paired, see if it works better closer to the hub). Note that if a device cannot pair when in its desired location, the device will likely not work when the device (or hub) is moved back to its permanent location. You will likely need to add repeaters to strengthen your Z-Wave mesh.
¶ What are repeaters?
Most non-battery-powered Z-Wave devices are repeaters. This includes hardwired devices or devices plugged into an outlet, like switches/dimmers, smart plugs, etc., as well as dedicated repeater devices. Battery powered Z-Wave devices are not repeaters. Repeaters help your network cover a larger area than the hub alone could reach.
¶ What range can I expect?
Z-Wave can use up to 4 hops between devices. The maximum range with 4 hops is roughly 600 feet (or 200 meters), but the placement of your hub and repeating devices as well as the layout of your home and surrounding environment will impact the actual range of your network. Therefore, you may still require Z-Wave repeaters even if all devices are within theoretical range of the hub.
¶ Chatty devices
Certain types of devices may generate lots of network traffic. Reducing congestion on your network may help resolve problems in such cases.
¶ Power metering, energy monitoring, etc.
Some Z-Wave outlets, switches, dimmers, and similar devices have power, energy, current, and/or voltage monitoring features enabled by default. Depending on the use and nature of the connected load, this may cause high amounts of Z-Wave traffic. You can cut down on this congestion by disabling these features if they are not needed or tuning their settings to report only what you need.
To do this, look in the Preferences section of the device page for these devices. Look for options related to features that may be labeled with names like "power reporting," "electrical current reporting," and similar. The exact preferences you see will depend on the device and driver you are using. Here is one example, where the device is configured to report any time the power reading changes by at least 25 Watts (the other option would allow configuring a percent-based instead of Watt-based change with either or both being allows; again, your specific devices will vary):
¶ Groups and scenes
If you are having trouble turning on/off a Hubitat group or activating a Hubitat scene or Room Lighting setup that contains Z-Wave (or other) devices, the following options may help. They are available for your specific group or scene under Apps > Groups and Scenes:
- For groups:
- Enable on/off optimization: if enabled, will not send "on" commands to member devices that already report as on and will not send "off" commands to member devices that already report as "off" (may reduce network traffic, but may cause unexpected results if devices do not accurately report state to hub, so consider both possibilities).
- Enable metering: allows you to specify a delay, in milliseconds, between commands. Try enabling this option and specifying a delay; if you aren't sure where to start, try a value around 50 or 75, but you will need to experiment; results will depend on your network and devices.
- For scenes:
- Enable activation optimization: if enabled, will skip sending certain commands to device if device is already in the expected state (may reduce network traffic, but may cause unexpected results if devices do not accurately report state to hub, so consider both possibilities).
- Enable metering: allows you to specify a delay, in milliseconds, between commands. Try enabling this option and specifying a delay; if you aren't sure where to start, try a value around 50 or 75, but you will need to experiment; results will depend on your network and devices.
- For Room Lighting:
- Command devices on/off irrespective of reported state (Force): if disabled (default), will not send "on" commands to devices that already report as on and will not send "off" commands to member devices that already report as "off" (may reduce network traffic, but may cause unexpected results if devices do not accurately report state to hub, so consider both possibilities). This option is available under Means to Activate > Activate Lights Options > Additional Options.
- Activate even if already partially activated: If disabled (default), will not activate the lights (via activator device) if it believes they are already activated. For some circumstances, particularly where some of the automated lights are turned off independently of this app. Enabling this option will cause any means to activate to send commands for activation to all devices as specified in the table, regardless of the current device or app/Room Lights status.
¶ Z-Wave S0
Z-Wave S0 (an older version of Z-Wave Security) can be significantly chattier than non-secure Z-Wave or newer S2 Security. For some devices, like older door locks or garage door openers that do not support S2, S0 is the only option. For many other devices, security is optional. Check the device manual to see if there is a separate method for secure vs. "regular"/non-secure pairing, and consider that pairing a large number of Z-Wave devices as S0 may cause congestion on your network, particularly if any such devices frequently send or receive messages on your network. S2 Security (supported on model C-7 and newer only) improves on this problem significantly, though some users still choose S2 only for specific kinds of devices.
To check if a device is paired with S0 Security:
- Navigate to Settings > Z-Wave Details and look for entries with "S0" in the "Security" column (hub model C-7 and newer only);
or
- On any device page, look under Device Details for the Data section.
- If you have a model C-5 or earlier and see a zwaveSecurePairingComplete: true entry, then the device is using S0; or
- If you have a model C-7 or newer and see zwaveSecurePairingComplete: true and S2: 128 entries, then the device is using S0 (other values for the S2 field or the lack of this field denote various S2 options or or no security)
¶ Z-Wave Switch or Dimmer Status Not Updating
Some older Z-Wave switches and dimmers do not update their switch (on/off) status on Hubitat when turned on or off from the device itself (i.e., on the wall), including many made before 2016 but also some that remained on the market for years afterwards. This is due to a now-expired patent that many manufacturers chose not to license, affecting many "classic" Z-Wave (not Z-Wave Plus) switches and dimmers. To determine if your device is affected:
- In the Hubitat web interface, navigate to Devices and then to the device detail page for your specific switch/dimmer. Keep this page open (ideally on a tablet or laptop you can take with you to the device).
- Tap or flip the switch or dimmer on or off from the switch/dimmer itself (e.g., by pressing or flicking the paddle or toggle on the wall).
- While doing the above, look at the Current States section on the device detail page (opened in step 1). If the value of the
switchstate does not update to "on" or "off" to match the actual on/off state of the switch or dimmer (generally within a few seconds), your device may be affected.
Note that in contrast to the above, the switch state will usually update correctly if an "On" or "Off" command is issued directly from Hubitat. Thus, one solution is to send commands from Hubitat only rather than using the physical device. If you do rely on switch state on the hub (e.g., for use in Hubitat Dashboard or as a "trigger" for a rule or other app), then the built-in Z-Wave Poller app can be configured to periodically "poll" the devices—that is, request their state. Alternatively, if you do not rely on the switch state on the hub being necessarily accurate, you may simply ignore this quirk.
A note for users switching from other platforms: some platforms may have configured polling for you automatically, making you wounder why the switches behave differently on Hubitat. Hubitat allows you to choose if and how frequently you need this workaround. Generally, Z-Wave networks work better with less traffic. Polling creates more traffic. Keep this in mind as you make decisions about this issue.
If your switch does not appear in Z-Wave Poller, it likely is not one that could be affected by this problem. If you do not think this is correct, you may wish to match your model with the model and driver in the List of Compatible Devices to make sure the driver chosen is correct. (The driver is shown under the "Type" dropdown on the device detail page, opened in step 1 above.) Z-Wave Plus and Z-Wave Plus v2 products, also known as 500-series and 700-series products (and the upcoming 800-series), should not be affected by this issue—only Z-Wave series 300 and older.
Status not updating on the hub could also be due to other problems, like a weak Z-Wave mesh, preventing messages from getting back to the hub; or other network troubles (the rest of this document can help you identify them).
¶ Z-Wave Details: Node Health, Topology, and Routes
The Settings > Z-Wave Details page contains diagnostic information that may be helpful for some users. This feature is not available on model C-5 or earlier hubs.
- PER: Packet error rate. Lower is better; 0 is good.
- Neighbors: The number of "neighbor nodes" (nodes in direct wireless range) that this node is able to see. More is better, but actual number will depend on the number and layout of devices in your network.
- Route Changes: Number of times the route has changed (fewer is generally better)
- RTT Avg: Round trip time average, the elapsed time between the sending of a packet and the receipt of an acknowledgment packet from the device (shorter is better)
- LWR RSSI: Calculated value of the RSSI for the last working route (LWR) over each hop, compared to the background noise sampling (higher values above 0 are better)
¶ Z-Wave Radio Firmware Update
Occasionally, new firmware for the hub's Z-Wave radio is released. If one is available for your hub, a Firmware Update button will appear in the row of buttons above the table:
It is recommended to apply any available updates, though they are optional and will only install if you start the process. (If you do not see this button, no updates are available.)