From 2f01fa4d809c3975405d77ae469ec744648ceaa3 Mon Sep 17 00:00:00 2001 From: Dominic Griesel Date: Wed, 14 Aug 2024 09:47:55 +0200 Subject: [PATCH 1/3] docs: clean up migration guides --- docs/_sidebar.md | 9 +-- docs/api/CCs/_sidebar.md | 9 +-- docs/getting-started/migrating/README.md | 10 +++ docs/getting-started/migrating/_sidebar.md | 79 +++++++++++++++++++ .../{migrating-to-v10.md => migrating/v10.md} | 2 +- .../{migrating-to-v11.md => migrating/v11.md} | 2 +- .../{migrating-to-v12.md => migrating/v12.md} | 2 +- .../{migrating-to-v13.md => migrating/v13.md} | 2 +- .../{migrating-to-v6.md => migrating/v6.md} | 2 +- .../{migrating-to-v7.md => migrating/v7.md} | 2 +- .../{migrating-to-v8.md => migrating/v8.md} | 2 +- .../{migrating-to-v9.md => migrating/v9.md} | 2 +- 12 files changed, 99 insertions(+), 24 deletions(-) create mode 100644 docs/getting-started/migrating/README.md create mode 100644 docs/getting-started/migrating/_sidebar.md rename docs/getting-started/{migrating-to-v10.md => migrating/v10.md} (99%) rename docs/getting-started/{migrating-to-v11.md => migrating/v11.md} (99%) rename docs/getting-started/{migrating-to-v12.md => migrating/v12.md} (99%) rename docs/getting-started/{migrating-to-v13.md => migrating/v13.md} (99%) rename docs/getting-started/{migrating-to-v6.md => migrating/v6.md} (98%) rename docs/getting-started/{migrating-to-v7.md => migrating/v7.md} (98%) rename docs/getting-started/{migrating-to-v8.md => migrating/v8.md} (99%) rename docs/getting-started/{migrating-to-v9.md => migrating/v9.md} (99%) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 73d042313f91..14074460b9e3 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -7,14 +7,7 @@ - [Frequently Asked Questions](getting-started/faq.md) - [Security S2](getting-started/security-s2.md) - [Z-Wave Long Range](getting-started/long-range.md) - - [Migrating to v13](getting-started/migrating-to-v13.md) - - [Migrating to v12](getting-started/migrating-to-v12.md) - - [Migrating to v11](getting-started/migrating-to-v11.md) - - [Migrating to v10](getting-started/migrating-to-v10.md) - - [Migrating to v9](getting-started/migrating-to-v9.md) - - [Migrating to v8](getting-started/migrating-to-v8.md) - - [Migrating to v7](getting-started/migrating-to-v7.md) - - [Migrating to v6](getting-started/migrating-to-v6.md) + - [Migrating from previous versions](getting-started/migrating/) - [🦎's device review](getting-started/device-review.md) - API diff --git a/docs/api/CCs/_sidebar.md b/docs/api/CCs/_sidebar.md index 021ff1aa6ee9..71a518df519b 100644 --- a/docs/api/CCs/_sidebar.md +++ b/docs/api/CCs/_sidebar.md @@ -7,14 +7,7 @@ - [Frequently Asked Questions](getting-started/faq.md) - [Security S2](getting-started/security-s2.md) - [Z-Wave Long Range](getting-started/long-range.md) - - [Migrating to v13](getting-started/migrating-to-v13.md) - - [Migrating to v12](getting-started/migrating-to-v12.md) - - [Migrating to v11](getting-started/migrating-to-v11.md) - - [Migrating to v10](getting-started/migrating-to-v10.md) - - [Migrating to v9](getting-started/migrating-to-v9.md) - - [Migrating to v8](getting-started/migrating-to-v8.md) - - [Migrating to v7](getting-started/migrating-to-v7.md) - - [Migrating to v6](getting-started/migrating-to-v6.md) + - [Migrating from previous versions](getting-started/migrating/) - [🦎's device review](getting-started/device-review.md) - API diff --git a/docs/getting-started/migrating/README.md b/docs/getting-started/migrating/README.md new file mode 100644 index 000000000000..6a241f47116f --- /dev/null +++ b/docs/getting-started/migrating/README.md @@ -0,0 +1,10 @@ +# Migrating from previous versions + +- [Migrating to v13](getting-started/migrating/v13.md) +- [Migrating to v12](getting-started/migrating/v12.md) +- [Migrating to v11](getting-started/migrating/v11.md) +- [Migrating to v10](getting-started/migrating/v10.md) +- [Migrating to v9](getting-started/migrating/v9.md) +- [Migrating to v8](getting-started/migrating/v8.md) +- [Migrating to v7](getting-started/migrating/v7.md) +- [Migrating to v6](getting-started/migrating/v6.md) diff --git a/docs/getting-started/migrating/_sidebar.md b/docs/getting-started/migrating/_sidebar.md new file mode 100644 index 000000000000..93e9a41d5fdb --- /dev/null +++ b/docs/getting-started/migrating/_sidebar.md @@ -0,0 +1,79 @@ +- Getting started + + - [Introduction](README.md) + - [Quick Start](getting-started/quickstart.md) + - [For Integrators / Why Z-Wave JS?](getting-started/integrators.md) + - [Our Philosophy](getting-started/philosophy.md) + - [Frequently Asked Questions](getting-started/faq.md) + - [Security S2](getting-started/security-s2.md) + - [Z-Wave Long Range](getting-started/long-range.md) + - [Migrating from previous versions](getting-started/migrating/) + - [Migrating to v13](getting-started/migrating/v13.md) + - [Migrating to v12](getting-started/migrating/v12.md) + - [Migrating to v11](getting-started/migrating/v11.md) + - [Migrating to v10](getting-started/migrating/v10.md) + - [Migrating to v9](getting-started/migrating/v9.md) + - [Migrating to v8](getting-started/migrating/v8.md) + - [Migrating to v7](getting-started/migrating/v7.md) + - [Migrating to v6](getting-started/migrating/v6.md) + - [🦎's device review](getting-started/device-review.md) + +- API + + - [Overview](api/overview.md) + - [Driver](api/driver.md) + - [Controller](api/controller.md) + - [ZWaveNode](api/node.md) + - [Endpoint](api/endpoint.md) + - [Virtual nodes and endpoints](api/virtual-node-endpoint.md) + - [Values and Metadata](api/valueid.md) + - [ConfigManager](api/config-manager.md) + - [Utilities](api/utils.md) + - [Zniffer](api/zniffer.md) + - [Command Classes](api/CCs/index.md) + +- Advanced usage + + - [Send custom messages](usage/custom.md) + - [External config DB location](usage/external-config.md) + - [Remote serial port over TCP](usage/tcp-connection.md) + - [Custom log transports](usage/log-transports.md) + +- Troubleshooting + + - [Overview](troubleshooting/index.md) + - [Connectivity issues](troubleshooting/connectivity-issues.md) + - [Problems with 700 series sticks](troubleshooting/otw-upgrade.md) + - [Nonsensical values appear randomly](troubleshooting/nonsensical-values.md) + - [Improving the network health](troubleshooting/network-health.md) + - [Missing updates from a device](troubleshooting/no-updates.md) + - [Configuration parameters are missing or wrong](troubleshooting/missing-config-params.md) + - [A device is not identified (unknown product)](troubleshooting/unidentified-device.md) + - [A lock (or any secure device) cannot be controlled](troubleshooting/lock-uncontrollable.md) + - [Some values are missing](troubleshooting/missing-values.md) + - [Upgrading the controller firmware](troubleshooting/otw-upgrade.md) + - [Creating a Zniffer](troubleshooting/zniffer.md) + +- Device Configuration Files + + - [Overview](config-files/overview.md) + - [File format](config-files/file-format.md) + - [Contributing device files](config-files/contributing-files.md) + - [Importing files from other sources](config-files/importing-from-others.md) + + - [Style guide](config-files/style-guide.md) + - [Conditional parameters and settings](config-files/conditional-settings.md) + - [Using templates](config-files/using-templates.md) + - [Guide on partial parameters](config-files/partial-parameters.md) + +- Development + + - [Introduction](development/intro.md) + - [Implementing a Command Class](development/implementing-cc.md) + - [Installing from GitHub](development/installing-from-github.md) + - [Releasing](development/releasing.md) + +- Data Collection & Use Practices + + - [Data Collection Notice](data-collection/data-collection.md) + - [User Disclosure](data-collection/user-disclosure.md) diff --git a/docs/getting-started/migrating-to-v10.md b/docs/getting-started/migrating/v10.md similarity index 99% rename from docs/getting-started/migrating-to-v10.md rename to docs/getting-started/migrating/v10.md index f6dd9025b4e9..bd649f9b25d0 100644 --- a/docs/getting-started/migrating-to-v10.md +++ b/docs/getting-started/migrating/v10.md @@ -1,4 +1,4 @@ -# Migrating to v10 +# Migrating to v10 What started out as an attempt to improve the testing setup, resulted in a huge refactor of the entire code base. diff --git a/docs/getting-started/migrating-to-v11.md b/docs/getting-started/migrating/v11.md similarity index 99% rename from docs/getting-started/migrating-to-v11.md rename to docs/getting-started/migrating/v11.md index 9aa8843394d3..3bf1171c4863 100644 --- a/docs/getting-started/migrating-to-v11.md +++ b/docs/getting-started/migrating/v11.md @@ -1,4 +1,4 @@ -# Migrating to v11 +# Migrating to v11 I've put this off for a while now. `v10` has been pretty stable - we've never had anything close to `.23` minor version before. But Z-Wave JS is on the road to certification, and some of those requirements are forcing my hand. diff --git a/docs/getting-started/migrating-to-v12.md b/docs/getting-started/migrating/v12.md similarity index 99% rename from docs/getting-started/migrating-to-v12.md rename to docs/getting-started/migrating/v12.md index 9706d51d28c4..abf90ad21f8a 100644 --- a/docs/getting-started/migrating-to-v12.md +++ b/docs/getting-started/migrating/v12.md @@ -1,4 +1,4 @@ -# Migrating to v12 +# Migrating to v12 A bit earlier than expected, but there were some necessary breaking changes queueing up. And with the upcoming end-of-life of Node.js 16, it's now time to get them out of the way. diff --git a/docs/getting-started/migrating-to-v13.md b/docs/getting-started/migrating/v13.md similarity index 99% rename from docs/getting-started/migrating-to-v13.md rename to docs/getting-started/migrating/v13.md index f4e0662492a1..5fcd3bfc02ba 100644 --- a/docs/getting-started/migrating-to-v13.md +++ b/docs/getting-started/migrating/v13.md @@ -1,4 +1,4 @@ -# Migrating to v13 +# Migrating to v13 As part of the ongoing efforts towards Z-Wave certification, I've found an issue in our `Meter CC` implementation that required a breaking change. Therefore I've collected a few other changes that would be breaking and decided to bundle them all into a major release. diff --git a/docs/getting-started/migrating-to-v6.md b/docs/getting-started/migrating/v6.md similarity index 98% rename from docs/getting-started/migrating-to-v6.md rename to docs/getting-started/migrating/v6.md index 5eee5cc07f2a..69af7a42685e 100644 --- a/docs/getting-started/migrating-to-v6.md +++ b/docs/getting-started/migrating/v6.md @@ -1,4 +1,4 @@ -# Migrating to v6 +# Migrating to v6 In version 6.x we used the opportunity to do some housekeeping and collect several breaking changes. Follow this guide if you're migrating to v6: diff --git a/docs/getting-started/migrating-to-v7.md b/docs/getting-started/migrating/v7.md similarity index 98% rename from docs/getting-started/migrating-to-v7.md rename to docs/getting-started/migrating/v7.md index 13c2e0925cdc..0d78632d78df 100644 --- a/docs/getting-started/migrating-to-v7.md +++ b/docs/getting-started/migrating/v7.md @@ -1,4 +1,4 @@ -# Migrating to v7 +# Migrating to v7 In version 7.x we got rid of some old habits, leading to several breaking changes. Follow this guide if you're migrating to v7: diff --git a/docs/getting-started/migrating-to-v8.md b/docs/getting-started/migrating/v8.md similarity index 99% rename from docs/getting-started/migrating-to-v8.md rename to docs/getting-started/migrating/v8.md index c7effd2ee27d..69862410e9ba 100644 --- a/docs/getting-started/migrating-to-v8.md +++ b/docs/getting-started/migrating/v8.md @@ -1,4 +1,4 @@ -# Migrating to v8 +# Migrating to v8 For version 8.x, we had several breaking changes lined up, so we also took the chance to sneak in a few more by reworking our dev environment. diff --git a/docs/getting-started/migrating-to-v9.md b/docs/getting-started/migrating/v9.md similarity index 99% rename from docs/getting-started/migrating-to-v9.md rename to docs/getting-started/migrating/v9.md index 241c4f45e763..1343a945ca56 100644 --- a/docs/getting-started/migrating-to-v9.md +++ b/docs/getting-started/migrating/v9.md @@ -1,4 +1,4 @@ -# Migrating to v9 +# Migrating to v9 The recent rewrite of the message queue made it much simpler to support use cases that go beyond executing a simple Serial API command. Examples are requesting Security S0 nonces (which was relatively convoluted before), handling other multi-step commands, as well as the ability to time individual commands. From 36411b6629a150c5500f77e824f523e834207116 Mon Sep 17 00:00:00 2001 From: Dominic Griesel Date: Wed, 14 Aug 2024 13:11:20 +0200 Subject: [PATCH 2/3] docs: rework troubleshooting section --- docs/_sidebar.md | 12 +- docs/api/CCs/_sidebar.md | 12 +- docs/getting-started/migrating/_sidebar.md | 12 +- docs/troubleshooting/common-issues.md | 159 ++++++++++++++++++ docs/troubleshooting/connectivity-issues.md | 64 ------- docs/troubleshooting/first-steps.md | 88 ++++++++++ docs/troubleshooting/index.md | 4 +- docs/troubleshooting/lock-uncontrollable.md | 7 - docs/troubleshooting/missing-config-params.md | 12 -- docs/troubleshooting/missing-values.md | 9 - docs/troubleshooting/network-health.md | 33 ---- docs/troubleshooting/no-updates.md | 4 +- docs/troubleshooting/otw-upgrade.md | 27 --- docs/troubleshooting/unidentified-device.md | 5 - 14 files changed, 258 insertions(+), 190 deletions(-) create mode 100644 docs/troubleshooting/common-issues.md delete mode 100644 docs/troubleshooting/connectivity-issues.md create mode 100644 docs/troubleshooting/first-steps.md delete mode 100644 docs/troubleshooting/lock-uncontrollable.md delete mode 100644 docs/troubleshooting/missing-config-params.md delete mode 100644 docs/troubleshooting/missing-values.md delete mode 100644 docs/troubleshooting/network-health.md delete mode 100644 docs/troubleshooting/otw-upgrade.md delete mode 100644 docs/troubleshooting/unidentified-device.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 14074460b9e3..7e2f98152c04 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -35,16 +35,8 @@ - Troubleshooting - [Overview](troubleshooting/index.md) - - [Connectivity issues](troubleshooting/connectivity-issues.md) - - [Problems with 700 series sticks](troubleshooting/otw-upgrade.md) - - [Nonsensical values appear randomly](troubleshooting/nonsensical-values.md) - - [Improving the network health](troubleshooting/network-health.md) - - [Missing updates from a device](troubleshooting/no-updates.md) - - [Configuration parameters are missing or wrong](troubleshooting/missing-config-params.md) - - [A device is not identified (unknown product)](troubleshooting/unidentified-device.md) - - [A lock (or any secure device) cannot be controlled](troubleshooting/lock-uncontrollable.md) - - [Some values are missing](troubleshooting/missing-values.md) - - [Upgrading the controller firmware](troubleshooting/otw-upgrade.md) + - [First steps](troubleshooting/first-steps.md) + - [Common issues](troubleshooting/common-issues.md) - [Creating a Zniffer](troubleshooting/zniffer.md) - Device Configuration Files diff --git a/docs/api/CCs/_sidebar.md b/docs/api/CCs/_sidebar.md index 71a518df519b..6b76e8718e2d 100644 --- a/docs/api/CCs/_sidebar.md +++ b/docs/api/CCs/_sidebar.md @@ -97,16 +97,8 @@ - Troubleshooting - [Overview](troubleshooting/index.md) - - [Connectivity issues](troubleshooting/connectivity-issues.md) - - [Problems with 700 series sticks](troubleshooting/otw-upgrade.md) - - [Nonsensical values appear randomly](troubleshooting/nonsensical-values.md) - - [Improving the network health](troubleshooting/network-health.md) - - [Missing updates from a device](troubleshooting/no-updates.md) - - [Configuration parameters are missing or wrong](troubleshooting/missing-config-params.md) - - [A device is not identified (unknown product)](troubleshooting/unidentified-device.md) - - [A lock (or any secure device) cannot be controlled](troubleshooting/lock-uncontrollable.md) - - [Some values are missing](troubleshooting/missing-values.md) - - [Upgrading the controller firmware](troubleshooting/otw-upgrade.md) + - [First steps](troubleshooting/first-steps.md) + - [Common issues](troubleshooting/common-issues.md) - [Creating a Zniffer](troubleshooting/zniffer.md) - Device Configuration Files diff --git a/docs/getting-started/migrating/_sidebar.md b/docs/getting-started/migrating/_sidebar.md index 93e9a41d5fdb..ecb4a25f56c1 100644 --- a/docs/getting-started/migrating/_sidebar.md +++ b/docs/getting-started/migrating/_sidebar.md @@ -42,16 +42,8 @@ - Troubleshooting - [Overview](troubleshooting/index.md) - - [Connectivity issues](troubleshooting/connectivity-issues.md) - - [Problems with 700 series sticks](troubleshooting/otw-upgrade.md) - - [Nonsensical values appear randomly](troubleshooting/nonsensical-values.md) - - [Improving the network health](troubleshooting/network-health.md) - - [Missing updates from a device](troubleshooting/no-updates.md) - - [Configuration parameters are missing or wrong](troubleshooting/missing-config-params.md) - - [A device is not identified (unknown product)](troubleshooting/unidentified-device.md) - - [A lock (or any secure device) cannot be controlled](troubleshooting/lock-uncontrollable.md) - - [Some values are missing](troubleshooting/missing-values.md) - - [Upgrading the controller firmware](troubleshooting/otw-upgrade.md) + - [First steps](troubleshooting/first-steps.md) + - [Common issues](troubleshooting/common-issues.md) - [Creating a Zniffer](troubleshooting/zniffer.md) - Device Configuration Files diff --git a/docs/troubleshooting/common-issues.md b/docs/troubleshooting/common-issues.md new file mode 100644 index 000000000000..9a947e692284 --- /dev/null +++ b/docs/troubleshooting/common-issues.md @@ -0,0 +1,159 @@ +# Common issues + +Here's a collection of common issues and how to solve them. + +## Nodes are frequently marked dead + +_...and sometimes come back immediately when pinged._ + +The log or error message likely mentions something along the lines of + +> Failed to send the command after 3 attempts (Status NoAck) + +> One or more nodes did not respond to the multicast request (Status NoAck) + +**NoAck** means that the controller sent the command (a couple of times, including multiple retries over several seconds), but the node never acknowledged it. This is a sign of a bad connection between the controller and the node, or a general issue with your mesh. Read and follow [first steps](troubleshooting/first-steps.md). + +_...and no, this can not be caused by a software update, even if that is when you noticed!_ + +## Inclusion finds no new devices + +This can have multiple reasons: + +**Bad connection between the controller and the device**\ +See [first steps](troubleshooting/first-steps.md). + +**The controller is set to a different frequency/region than the device**\ +Check that the device is for the correct region. If it is, check and possibly change the region of your controller to the correct one. + +**The device is not in inclusion mode**\ +Check the device manual on how to put it into inclusion mode. Some devices require a button press, others a sequence of button presses. + +**The device is still included in another network**\ +Exclude the devide first, then try to include it again. Exclusion can be done using Z-Wave JS and will end without a message or with a message indicating that no device was excluded. This is normal. + +**The device is out of range**\ +Some older devices do not support network-wide inclusion, or lower their transmit power for inclusion. Move the device closer to the controller or vice-versa, then try again. After everything is back in its place, rebuild the routes for the new device. + +## Inclusion of a new device fails completely + +This means the controller told us that it was not able to perform the necessary communication to include the device, without going into detail why. Possible reasons are: + +**Bad connection between the controller and the device**\ +See [first steps](troubleshooting/first-steps.md). + +**The device is in a weird state**\ +Power-cycle the device, then try again. Possibly exclude the device (see above) and try again. + +**The controller is in a weird state**\ +Soft-reset (restart) the controller, then try again. If that does not help, power-cycle the controller (e.g. by unplugging it for a few seconds), then try again. + +## Inclusion with Security ends in an error + +On supporting applications, the error message should indicate **why** the secure inclusion failed. If not, driver logs should include the reason. + +Typically, this is either a user error (wrong PIN, some keys not configured) or a timeout. Except for some rare cases, timeouts are caused by a **bad connection between the controller and the device**, see [first steps](troubleshooting/first-steps.md). + +## Sensors report nonsensical values + +See [nonsensical values appear randomly](troubleshooting/nonsensical-values.md). + +## A device is not identified + +In the Z-Wave standard, devices are identified by their "fingerprint", which are three numbers for **manufacturer ID**, **product type**, **product ID**. To map those to a device name, configuration files are required. However, for most of the functionality, these configuration files are **purely cosmetic**, especially for Z-Wave+ devices. It is likely that your device will work just fine, even if it is not recognized yet. + +**Fingerprint is missing/undefined**\ +This means that the device did not send its fingerprint during the interview. + +- Ensure the connection to the device is good, see [first steps](troubleshooting/first-steps.md). +- Re-interview the device to query the information again. +- If that does not help, exclude the device, factory reset it, then include it again. + +**Fingerprint is known, but the device is not identified**\ +A device configuration file is required to map the fingerprint to a device name. See [below](#configuration-parameters-are-missing-or-wrong) on how to do this. + +## A device is not sending updates + +See [missing updates from a device](troubleshooting/no-updates.md). + +## Some values are missing + +Check if the device is marked **ready**. If not, have patience - the first interview of battery-powered nodes may take several hours. This can be sped up by waking them up manually, which might take multiple attempts. + +> [!NOTE] A device that sends reports **does not** automatically mean it is awake. Refer to the device manual to figure out how to wake it up. Usually this is done by pressing a button on the device. + +If the interview never gets completed, please consider opening an issue. + +If the device is supposed to be using encryption, also see [below](#a-lock-or-any-secure-device-cannot-be-controlled). + +## Configuration parameters are missing or wrong + +Check the [changelog](https://github.com/zwave-js/node-zwave-js/blob/master/CHANGELOG.md) if there were any recent updates to the configuration files for your device. If so, **try re-interviewing** the device to pick up the changed parameters. + +It can also be that there were issues during the first interview. In this case, **try re-interviewing** the device. + +If that does not help, a change to configuration files might be necessary. Although the specification added the ability to discover the configuration, most devices out there don't support this functionality. For those, configuration files are required which define the available parameters. To add or correct support for a device, please do one of the following: + +- Open a Pull Request and provide such a configuration file or edit an existing one. The [documentation](config-files/overview.md) describes how this is done. +- Or open an issue detailing which device you want added/fixed. Make sure to provide all the requested information. + +## A lock (or any secure device) cannot be controlled + +Locks require encrypted communication for their critical functionality. There are several reasons that could cause the driver to communicate without encryption: + +1. It could have no or wrong encryption keys. Make sure that the security keys (1 for S0, 3 for S2) are configured and match the ones that were used when including the device. If the keys don't match, you have to **exclude**, possibly **factory reset** and **include** the device again. +2. The device could have been included without encryption. Make sure that the device is included securely. If not, you have to **exclude and include** the device again. See also [Inclusion with Security ends in an error](#inclusion-with-security-ends-in-an-error). +3. The device did not respond when the driver tried to figure out the encryption level. Try re-interviewing. + +## 500 series controller becomes unresponsive + +Aeotec Z-Stick Gen5 and Gen5+, Firmware `1.0` and `1.1`: Attempting to send a command to a dead node can cause cause some controller responses to be significantly delayed or completely lock up the controller. Upgrading to [firmware 1.2](https://aeotec.freshdesk.com/support/solutions/articles/6000252294-z-stick-gen5-v1-02-firmware-update) can solve this issue, but not all controllers can be upgraded. + +This issue may be present on other 500 series controllers as well, best to contact the manufacturer for support. + +## 700/800 series controller is "jammed" or becomes unresponsive + +This is a series of firmware issues, with the unresponsiveness being the most severe. + +> [!NOTE] You may have noticed this first after updating Z-Wave JS, but the issue is not caused by it. Rather, Z-Wave JS started detecting and exposing issues with the controller in a different way. Prior to that, it would be treated like a communication issue, randomly marking healthy nodes as dead. + +It can only be resolved by a firmware update. However, there is no known firmware version that is completely fixed, so it is recommended to choose a firmware based on the following criteria: + +- 700 series: + - prefer SDK versions 7.17.2 to 7.18.x + - SDK versions 7.19.x are okay + - avoid SDK versions before 7.17.2 + - avoid SDK versions 7.20 to 7.21.3 + +- 800 series + - prefer SDK versions 7.22.x + - SDK versions 7.17.2 to 7.19.x are okay + - avoid SDK versions before 7.17.2 + - avoid SDK versions 7.20 to 7.21.3 + +> [!NOTE] The SDK version does not have to match the firmware version. If you are unsure which SDK versions a firmware is based on, contact the manufacturer of your device. + +> [!WARNING] Z-Wave controllers generally do not allow downgrading the firmware, at least not without compiling a custom bootloader. Be careful which firmware you choose to install and avoid the `_v255` upgrades available from Silicon Labs - those can not be upgraded either. + +Firmware can be upgraded using the below directions: + +- [Upgrade instructions using Linux and Z-Wave JS based applications](https://github.com/kpine/zwave-js-server-docker/wiki/700-series-Controller-Firmware-Updates-(Linux)) +- [Upgrade instructions using Windows (Aeotec)](https://aeotec.freshdesk.com/support/solutions/articles/6000252296-update-z-stick-7-with-windows) +- [Upgrade instructions using Windows (Zooz)](https://www.support.getzooz.com/kb/article/931-how-to-perform-an-ota-firmware-update-on-your-zst10-700-z-wave-stick/) +- [Upgrade instructions using Windows/Linux (Z-Wave.Me)](https://z-wave.me/support/uzbrazberry-firmwares/) + +## Timeout while waiting for an ACK from the controller + +This means the controller is not responding to commands at all. Possible reasons are: + +**Wrong path configured**\ +The configured path points to an existing serial port, but it is not connected to a Z-Wave controller. Double check the path and the physical connection to the controller. + +**The controller is unresponsive**\ +See [above](#_700800-series-controller-is-quotjammedquot-or-becomes-unresponsive). + +**The controller is bricked**\ +If this happens after a firmware upgrade/downgrade, you may have bricked the controller. While 700/800 series bootloaders should prevent this, we've still seen reports of it happen. Contact the manufacturer for support. + +**Incorrect VM settings, e.g. USB passthrough**\ +Good luck, you're on your own. diff --git a/docs/troubleshooting/connectivity-issues.md b/docs/troubleshooting/connectivity-issues.md deleted file mode 100644 index 2023532b3275..000000000000 --- a/docs/troubleshooting/connectivity-issues.md +++ /dev/null @@ -1,64 +0,0 @@ -# Connectivity issues - -## General troubleshooting - -→ **Commands sometimes don't go through**\ -→ **Nodes that go dead and come back alive**\ -→ **Reports go missing**\ -→ **Nodes that are close to the controller are missing from its neighbor list**\ -→ **Nodes are vaninshing from the controller's neighbor list** - -Z-Wave sticks in particular are prone to interference by USB ports, especially by USB3 ports. We recommend putting the stick in a suitable location: - -- on an **USB extension cord** (this works wonders!) -- away from other USB ports -- away from metallic surfaces -- and especially not in the back of a server rack - -?> Seriously, try it! The success rate of this is surprisingly high. - -If that alone doesn't help, eliminate external sources of RF interference or move the controller away from them. For example, these can be electrical appliances like microwaves, other USB devices like external drives, active USB adapters, etc. - -> [!NOTE] Make sure to heal the network after physically moving devices around! - -If you've excluded all this, it's time to [look at the mesh](troubleshooting/network-health.md). - -## Problems communicating with the stick - -→ **Failed to send the _message_ after 3 attempts**\ -→ **Timeout while waiting for an ACK from the controller**\ -→ **Timeout while waiting for a response from the controller**\ -→ **Timeout while waiting for a callback from the controller** - -If one of these messages show up, Z-Wave JS has trouble communicating with the Z-Wave stick. Often, something is **really wrong** with the stick - e.g. it might be stuck. Try: - -- waiting a bit -- soft-resetting the stick (if this function is enabled) -- removing and re-inserting the stick -- or restarting your host - -## Problems communicating with nodes - -If communication with a device fails, the driver automatically tries to resend the messages up to 3 times. Afterwards, it gives up and moves on to the next message. You should get an error which looks like one of the following: - -→ **Failed to send the _command_ after 3 attempts. Transmission queue full.**\ -Too many messages were sent in a short time without waiting for a controller reply. The driver takes care of this, so it should really not happen. This can happen if your network is really busy. Check the logs to identify spamming nodes. - -→ **The controller response indicated failure**\ -→ **The controller callback indicated failure**\ -This usually means that the command could not be executed. Depending on what you tried to do, an issue might be worth it. - -→ **Failed to send the _command_ after 3 attempts (Status XYZ)**\ -→ **One or more nodes did not respond to the multicast request (Status XYZ)**\ -The command was accepted by the Z-Wave stick, but it could not be transmitted to the node. If the status is included, it tells you exactly what went wrong: - -- `NoAck`: The node did not acknowledge the receipt of the message. If the node is battery-powered, it most likely means that it is asleep. This is normal. If the node is **not** battery-powered, it either has a bad connection or it physically turned off. -- `Fail`: It was not possible to transmit data because the Z-Wave network or radio frequency is busy or jammed. This is usually a physical issue, like RF noise caused by external sources. When this appears on a 700 series stick however, read [this](troubleshooting/700-series-issues.md). - -→ **Timed out while waiting for a response from the node**\ -The node acknowledged the message but did not send the expected response in time. This can mean one of many things: - -- The node did not send a response -- The node did send a response, but it didn't reach the controller (might be a connectivity issue). -- The node does not understand or support the command -- When combined with Security S0, this can also mean that the node was not able to decrypt the command. diff --git a/docs/troubleshooting/first-steps.md b/docs/troubleshooting/first-steps.md new file mode 100644 index 000000000000..588b32bf5417 --- /dev/null +++ b/docs/troubleshooting/first-steps.md @@ -0,0 +1,88 @@ +# First steps + +A lot of reliability problems with Z-Wave networks are caused by the same few underlying issues. Often, the symptoms may not even seem related to the source of the problem, like one device not working when another one is causing the problems. + +Some examples: + +→ Commands sometimes don't go through\ +→ Nodes that go dead and come back alive\ +→ Reports go missing\ +→ Nodes that are close to the controller are missing from its neighbor list\ +→ Nodes are vanishing from the controller's neighbor list + +> Therefore, follow this guide before doing any further troubleshooting. + +## Controller placement + +Z-Wave sticks in particular are prone to interference by USB ports, especially by USB3 ports. The following video demonstrates the issue for Zigbee, but it applies to Z-Wave as well: + + + +To avoid this, put the stick in a suitable location: + +- on an **USB extension cord** (see video above) +- away from other USB ports +- in a central location in your home +- away from metallic surfaces +- and especially not in the back of a server rack + +> [!NOTE] Make sure to heal the network after physically moving devices around! + +If that alone doesn't help, eliminate external sources of RF interference or move the controller away from them. For example, these can be electrical appliances like microwaves, other USB devices like external drives, active USB adapters, etc. + +Look at the Background RSSI readings to determine whether there is an elevated noise level. The average background RSSI should be as close as possible to the sensitivity limit of your radio: + +- 500 series: around -90 dBm +- 700 series: around -100 dBm +- 800 series: around -110 dBm + +## Reduce reports from the network + +Even with a strong mesh, too much RF traffic can be the death of a Z-Wave network. While direct transmission can achieve a reasonably high throughput of 10-20 messages per second under good RF conditions, having this kind of load constantly and across multiple hops is absolutely devastating. + +Unfortunately, many devices come with a pretty bad default reporting configuration, causing many unnecessary reports in short intervals. In combination with multi-hop routes and retransmission attempts, the number of messages the network has to handle can quickly become overwhelming. Additionally, some controller firmwares have bugs that cause additional routing attempts, further increasing the load. + +As such, tuning the reporting configuration of all devices is crucial, especially for multisensors and power meters, which tend to be the worst offenders. Here are a few best practices we've found over time, just keep in mind that not all of these settings may be supported by your devices: + +1. **Turn off unnecessary reports**. If you only monitor the energy usage (`kWh`) of a single socket of a 5-port plug, but it supports reporting `W`, `kWh`, `V` and `A` on all sockets, you can easily cut the number of reports by a factor of 20 (a single report instead of 5 sockets times 4 reports per socket). +1. **Prefer reporting on changes over timed reports**. Being reminded every 5 seconds that a device still does not use power does not add any value, but stresses the network. Instead, configure your devices to report when the power usage changes by more than a certain (significant!) amount. This amount may be as low as 1 W for an LED bulb, but 50+ W for a washing machine. Tuning this depends on the device - too low and there will be too many reports, too high and your measurement history will be inaccurate. +1. **Use timed reports only as fallbacks**. You might still want to have timed reports in case a change report does not find its way to the controller. In that case, choose a high enough interval to prevent floods from many devices reporting at once, e.g. once per hour. +1. Alternatively: **Choose a high reporting interval**. Not all devices support reporting everything on change only. In these cases, you must make sure to prevent floods by choosing a sane (high enough) reporting interval. +1. **Turn off supervision for non-crucial reports**. More modern devices support sending their reports with supervision, which requests a confirmation from the controller that it received and handled the command. While this makes sense for fire/water alarms and such, some devices enable this for power meters. As a result, every single report causes two messages to be exchanged instead of one. This feature should be disabled unless you really need to make sure that commands are received. +1. **Do not use Security S0 for sensors**. Encrypting traffic also provides data integrity, which prevents picking up corrupted frames, like water usage on a power meter. However, S0 is very inefficient and devices using S0 need to exchange three commands for each report. Prefer using devices that support S2, otherwise stick to not using encryption - this is what Z-Wave JS does with the default inclusion strategy. As an alternative to S0, some devices support using CRC-16 encapsulation (often configurable), which doesn't require additional messages. + +> [!NOTE] To figure out where to start, look at the statistics for a node. Very high numbers of incoming reports (e.g. several thousands while others have only a handful) are a good indicator that they are misconfigured and/or have a bad connection to the controller. + +## Ensure strong connections between devices + +A flaky connection will cause issues during usage and can compound other existing issues. To be able to diagnose this, you need to use an application that exposes the necessary features, e.g. [Z-Wave JS UI](https://github.com/zwave-js/zwave-js-ui). The following section will assume that you are using Z-Wave JS UI. + +Z-Wave JS collects statistics that allows building a map of the network with the actual routes used, their speed and (if supported) the RSSI measurements. In general, all routes should be using as few hops as possible and use the highest speed supported by your devices, which will be 100 kbps, except for some very old ones (before 500 series). + +If this is not the case, investigate why this is happening, starting with devices that are close to the controller and have low speeds. Afterwards, move on to further away devices. If the connection quality drops off along a multi-hop route, it makes sense to check all nodes along a route (including node-to-node health checks where supported) to determine where issues start to appear. + +Z-Wave JS can perform health checks test the physical connection strength between the controller and a node (or between two nodes), see [Nodes health check](https://zwave-js.github.io/zwave-js-ui/#/usage/nodes_healthcheck). + +Such a health check will ping a node several times, and (if the node supports it) instruct it to ping the controller with varying TX power. This way, Z-Wave JS will determine the following things, not all of which may be supported by your combination of controller and nodes: + +- **Route changes**: During how many ping attempts a new route was needed. Should be as low as possible, ideally 0. +- **Latency**: The maximum time it took to send a ping to the node. Should be as low as possible, <100 ms are good, ideally 10 ms (lower values cannot be measured). +- **Failed pings (controller → node)**: How many pings from the controller were not acknowledged by the node. Should be 0, higher values indicate either a message loss between the controller and the node, or noise near the controller which causes the acknowledgements to get lost. +- **Failed pings (node → controller)**: How many pings from the node were not acknowledged by the controller. Should be 0, higher values indicate either a message loss between the controller and the node, or noise near the node which causes the acknowledgements to get lost. +- **Min. powerlevel without failures**: The minimum powerlevel where all pings from the node were acknowledged by the controller. Should be \< -6 dBm (or > +6 dBm if the application reports the _reduction_ in powerlevel). Ideally -9 dBm, "normal powerlevel" is bad (equals 0 dBm). +- **SNR margin**: An estimation of the Signal-to-Noise Ratio Margin, the difference between the background RSSI and the measured RSSI of acknowledgements. Should be > 17 dBm, lower values indicate excessive noise. + +If the test results show high variance in some of these values or measurements that are far from the ideal, it may be necessary to: + +- move devices around +- eliminate sources of noise +- manually assign routes, see below +- add additional repeaters + +## Manually assign routes + +Under ideal conditions, the Z-Wave firmware should figure out usable routes by itself. However, this is not always the case, which can lead to some _\*ahem\*_ interesting routes. For example, this can cause multi-hop routes across the house when a direct connection would be possible and seems like the most logical choice. + +In these cases, it is unlikely that rebuilding routes will result in any improvement at all. Instead, we recommend manually assigning so-called _priority routes_, e.g. to force a direct connection. These routes will always be attempted first, even if the last attempt failed. + +> [!NOTE] This is a double-edged sword. If the priority route is good, you can expect a fast and reliable connection. If not, or if an assigned repeater goes missing, it will introduce unnecessary delays. diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md index a55076262259..cdfb480208fc 100644 --- a/docs/troubleshooting/index.md +++ b/docs/troubleshooting/index.md @@ -40,7 +40,9 @@ Here's how it **DOES NOT** look like. This is an **application log** from `zwave ## Rule #2: Thou shalt only use the "debug" level -There are multiple log levels, but **only** the "debug" level contains enough info for troubleshooting. +There are multiple log levels, but **only** the **debug** level contains enough info for troubleshooting. +It may be tempting to go even higher and use the **silly** level, but like the name suggests, it adds silly amounts of information +that is only used to troubleshoot very specific issues. For all others, it just makes the logs harder to read.
Click here for another counter example diff --git a/docs/troubleshooting/lock-uncontrollable.md b/docs/troubleshooting/lock-uncontrollable.md deleted file mode 100644 index 0bf52c27c7bf..000000000000 --- a/docs/troubleshooting/lock-uncontrollable.md +++ /dev/null @@ -1,7 +0,0 @@ -# A lock (or any secure device) cannot be controlled - -Locks require encrypted communication for their critical functionality. There are several reasons that could cause the driver to communicate without encryption. - -1. It could have no or wrong encryption keys. Make sure that the security keys (1 for S0, 3 for S2) are configured and match the ones that were used when including the device. If the keys don't match, you have to **exclude and include** the device again. -2. The device could have been included without encryption. Make sure that the device is included securely. If not, you have to **exclude and include** the device again. -3. The device did not respond when the driver tried to figure out the encryption level. Try re-interviewing. diff --git a/docs/troubleshooting/missing-config-params.md b/docs/troubleshooting/missing-config-params.md deleted file mode 100644 index 9bcedb7b1db6..000000000000 --- a/docs/troubleshooting/missing-config-params.md +++ /dev/null @@ -1,12 +0,0 @@ -## Configuration parameters are wrong - -Check the [changelog](https://github.com/zwave-js/node-zwave-js/blob/master/CHANGELOG.md) if there were any recent updates to the configuration files for your device. If so, **try re-interviewing** the device to pick up the changed parameters. - -## Configuration parameters are missing - -It can be that there were issues during the first interview. In this case, **try re-interviewing** the device. - -If that does not help, a change to configuration files might be necessary. Although the specification added the ability to discover the configuration, most devices out there don't support this functionality. For those, configuration files are required which define the available parameters. To add support for a device, please do one of the following: - -- Open a Pull Request and provide such a configuration file. The [documentation](config-files/overview.md) describes how this is done. -- Or open an issue detailing which device you want added and provide a link to the device manual that includes a description of all parameters. diff --git a/docs/troubleshooting/missing-values.md b/docs/troubleshooting/missing-values.md deleted file mode 100644 index 4f15fc8e93ef..000000000000 --- a/docs/troubleshooting/missing-values.md +++ /dev/null @@ -1,9 +0,0 @@ -# Some values are missing - -Check if the interview is not yet completed. Check if the `ready` event has been emitted for the node in question. If not, have patience - the first interview of battery-powered nodes may take several hours. This can be sped up by waking them up manually, which might take multiple attempts. - -> [!NOTE] A device that sends reports **does not** automatically mean it is awake. Refer to the device manual to figure out how to wake it up. Usually this is done by pressing a button on the device. - -If the interview never gets completed, please consider opening an issue. - -If the device is supposed to be using encryption, also check out [A lock (or any secure device) cannot be controlled](troubleshooting/lock-uncontrollable.md). diff --git a/docs/troubleshooting/network-health.md b/docs/troubleshooting/network-health.md deleted file mode 100644 index 2ee09c402353..000000000000 --- a/docs/troubleshooting/network-health.md +++ /dev/null @@ -1,33 +0,0 @@ -# Improving the network health - -Only a strong and healthy Z-Wave network is a reliable Z-Wave network. Ensuring this consists of two parts. - -## Testing the connection strength - -A flaky connection will cause issues during usage and can compound other existing issues. Z-Wave JS can perform health checks test the physical connection strength between the controller and a node (or between two nodes). Whether this functionality is available depends on the application you use Z-Wave JS with, but at least [Z-Wave JS UI](https://github.com/zwave-js/zwave-js-ui) exposes it (see [Nodes health check](https://zwave-js.github.io/zwave-js-ui/#/usage/nodes_healthcheck)). - -Such a health check will ping a node several times, and (if the node supports it) instruct it to ping the controller with varying TX power. This way, Z-Wave JS will determine the following things, not all of which may be supported by your combination of controller and nodes: - -- **Route changes**: During how many ping attempts a new route was needed. Should be as low as possible, ideally 0. -- **Latency**: The maximum time it took to send a ping to the node. Should be as low as possible, <100 ms are good, ideally 10 ms (lower values cannot be measured). -- **Failed pings (controller → node)**: How many pings from the controller were not acknowledged by the node. Should be 0, higher values indicate either a message loss between the controller and the node, or noise near the controller which causes the acknowledgements to get lost. -- **Failed pings (node → controller)**: How many pings from the node were not acknowledged by the controller. Should be 0, higher values indicate either a message loss between the controller and the node, or noise near the node which causes the acknowledgements to get lost. -- **Min. powerlevel without failures**: The minimum powerlevel where all pings from the node were acknowledged by the controller. Should be \< -6 dBm (or > +6 dBm if the application reports the _reduction_ in powerlevel). Ideally -9 dBm, "normal powerlevel" is bad (equals 0 dBm). -- **SNR margin**: An estimation of the Signal-to-Noise Ratio Margin, the difference between the background RSSI and the measured RSSI of acknowledgements. Should be > 17 dBm, lower values indicate excessive noise. - -If the test results show high variance in some of these values or measurements that are far from the ideal, it may be necessary to add additional repeaters, eliminate sources of noise or move devices around. If you have access to the route statistics (which routes are actually used), it makes sense to check all nodes along a route to determine where issues appear. - -## Optimizing the reporting configuration - -Even with a strong mesh, badly configured devices can be the death of a Z-Wave network. Unfortunately, many devices come with a pretty bad default configuration, which can quickly be a problem in medium to large networks. Z-Wave is not made for high throughput, yet it is possible to generate a constant network load of 5-10+ messages per second, which is absolutely devastating. A message flood like this can cause the controller to get jammed, preventing it from responding/acknowledging commands. However, many devices handle a missing acknowledgement by re-transmitting their last command, making the issue even worse. - -> [!NOTE] This can typically be detected by looking at the statistics for a node. Very high numbers of incoming reports (e.g. several thousands while others have only a handful) are a good indicator that they are misconfigured. - -As such, tuning the reporting configuration of all devices is crucial, especially for multisensors and power meters, which tend to be the worst offenders. Here are a few best practices we've found over time, just keep in mind that not all of these settings may be supported by your devices: - -1. **Turn off unnecessary reports**. If you only monitor the energy usage (`kWh`) of a single socket of a 5-port plug, but it supports reporting `W`, `kWh`, `V` and `A` on all sockets, you can easily cut the number of reports by a factor of 20 (a single report instead of 5 sockets times 4 reports per socket). -1. **Prefer reporting on changes over timed reports**. Being reminded every 5 seconds that a device still does not use power does not add any value, but stresses the network. Instead, configure your devices to report when the power usage changes by more than a certain (significant!) amount. This amount may be as low as 1 W for an LED bulb, but 50+ W for a washing machine. Tuning this depends on the device - too low and there will be too many reports, too high and your measurement history will be inaccurate. -1. **Use timed reports only as fallbacks**. You might still want to have timed reports in case a change report does not find its way to the controller. In that case, choose a high enough interval to prevent floods from many devices reporting at once, e.g. once per hour. -1. Alternatively: **Choose a high reporting interval**. Not all devices support reporting everything on change only. In these cases, you must make sure to prevent floods by choosing a sane (high enough) reporting interval. -1. **Turn off supervision for non-crucial reports**. More modern devices support sending their reports with supervision, which requests a confirmation from the controller that it received and handled the command. While this makes sense for fire/water alarms and such, some devices enable this for power meters. As a result, every single report causes two messages to be exchanged instead of one. This feature should be disabled unless you really need to make sure that commands are received. -1. **Do not use Security S0 for sensors**. Encrypting traffic also provides data integrity, which prevents picking up corrupted frames, like water usage on a power meter. However, S0 is very inefficient and devices using S0 need to exchange three commands for each report. Prefer using devices that support S2, otherwise stick to not using encryption - this is what Z-Wave JS does with the default inclusion strategy. As an alternative to S0, some devices support using CRC-16 encapsulation (often configurable), which doesn't require additional messages. diff --git a/docs/troubleshooting/no-updates.md b/docs/troubleshooting/no-updates.md index ea23a0b7c34e..08833d779b52 100644 --- a/docs/troubleshooting/no-updates.md +++ b/docs/troubleshooting/no-updates.md @@ -28,7 +28,7 @@ This section is meant to help you figure out why and reduce debugging time for u If this is not the case, see b). Otherwise, this seems to be okay from the `node-zwave-js` point of view. - b) **No source endpoint:**\ + b) **No source endpoint**\ The device sends un-encapsulated reports (no source endpoint information): ```log @@ -40,7 +40,7 @@ This section is meant to help you figure out why and reduce debugging time for u This means that we don't know which endpoint this report is from. If it was meant to come from an endpoint, we might be able to work around the missing info - see 4. - c) **None:**\ + c) **None**\ Most likely the lifeline is not set up correctly. Some devices spread their reports across multiple association groups. Consult the manual to figure out which reports are sent in which group. 1. Check if the Command Class included in the report is supported on more than one endpoint (excluding endpoint `0`).\ diff --git a/docs/troubleshooting/otw-upgrade.md b/docs/troubleshooting/otw-upgrade.md deleted file mode 100644 index 6d72d942674a..000000000000 --- a/docs/troubleshooting/otw-upgrade.md +++ /dev/null @@ -1,27 +0,0 @@ -# Over-the-wire (OTW) firmware upgrades of Z-Wave controllers - -Several issues are caused by the controller firmware and can only be fully solved by upgrading it. So far, the following issues are known: - -- Aeotec Z-Stick Gen5 and Gen5+, Firmware `1.0` and `1.1`: Attempting to send a command to a dead node can cause cause some controller responses to be significantly delayed or completely lock up the controller. Upgrading to [firmware 1.2](https://aeotec.freshdesk.com/support/solutions/articles/6000252294-z-stick-gen5-v1-02-firmware-update) can solve this issue, but not all controllers can be upgraded. -- All 700 series controllers based on a Z-Wave SDK below `7.17.2` have a bug that could cause the mesh to be flooded on some networks and the controller to become unresponsive. It appears that this bug is largely, if not completely, resolved as of firmware version `7.17.2`. Users should upgrade the firmware on all 700 series controllers to this version (or higher). Take note of the issues in higher versions though! At the moment, only `7.17.2` and `7.18.x` can be recommended. -- Controller firmwares based on Z-Wave SDK `7.19.1` have a bug that causes the controller to randomly restart. It is strongly recommended to update to a firmware based on version `7.19.2`, but not later, because... -- Controller firmwares based on Z-Wave SDK `7.19.3` have a bug that causes the controller to randomly hang during transmission until it is restarted. It is currently unclear if this bug is fixed in a later SDK, as it is currently not possible to upgrade to the official builds of the `7.20.x` SDK. - -Until recently, 700 series Z-Wave Controllers had a bug that could cause the mesh to be flooded on some networks and the controller to become unresponsive. At present, all 700 series controllers share the same firmware and are subject to this bug. It appears that this bug is largely, if not completely, resolved as of firmware version `7.17.2`. Users should upgrade the firmware on all 700 series controllers to this version (or higher). - -## Upgrading the firmware - -OTW firmware upgrades of 700/800 series controllers can be done directly with Z-Wave JS. - -> [!WARNING] Z-Wave controllers generally do not allow downgrading the firmware, at least not without compiling a custom bootloader. Be careful which firmware you choose to install and avoid the `_v255` upgrades available from Silicon Labs - those can not be upgraded either. - -More details can be found under the following links: - -### Linux - -https://github.com/kpine/zwave-js-server-docker/wiki/700-series-Controller-Firmware-Updates-(Linux) - -### Windows - -- Aeotec - https://aeotec.freshdesk.com/support/solutions/articles/6000252296-update-z-stick-7-with-windows -- Zooz - [700 series](https://www.support.getzooz.com/kb/article/931-how-to-perform-an-ota-firmware-update-on-your-zst10-700-z-wave-stick/), [800 series](https://www.support.getzooz.com/kb/article/1276-how-to-perform-an-otw-firmware-update-on-your-zst39-800-long-range-z-wave-stick/) diff --git a/docs/troubleshooting/unidentified-device.md b/docs/troubleshooting/unidentified-device.md deleted file mode 100644 index 0b5d6b962792..000000000000 --- a/docs/troubleshooting/unidentified-device.md +++ /dev/null @@ -1,5 +0,0 @@ -# A device is not identified (unknown product) - -In the Z-Wave standard, devices are identified by their "fingerprint", which are three numbers for **manufacturer ID**, **product type**, **product ID**. To map those to a device name, configuration files are required. However, for most of the functionality, these configuration files are **purely cosmetic**, especially for Z-Wave+ devices. It is likely that your device will work just fine, even if it is not recognized yet. - -→ see [Configuration parameters are missing](troubleshooting/missing-config-params.md) From 62cc7f226f3b0de4d996f09a4ffb3b548a8aaa6e Mon Sep 17 00:00:00 2001 From: Dominic Griesel Date: Wed, 14 Aug 2024 13:34:57 +0200 Subject: [PATCH 3/3] docs: update Zniffer creation guide --- docs/troubleshooting/zniffer.md | 87 +++++++++++++++++++++++++++------ 1 file changed, 72 insertions(+), 15 deletions(-) diff --git a/docs/troubleshooting/zniffer.md b/docs/troubleshooting/zniffer.md index 788c9f607181..771bc9550de8 100644 --- a/docs/troubleshooting/zniffer.md +++ b/docs/troubleshooting/zniffer.md @@ -17,40 +17,97 @@ A Zniffer is a Z-Wave controller with special firmware that can capture Z-Wave t ## Installation 1. Install Simplicity Studio -1. If using an 700/800 series Zniffer, install the Z-Wave (Gecko) SDK in the latest version inside Simplicity Studio. +1. If using an 800 series Zniffer, install the **Simplicity SDK** in the latest version inside Simplicity Studio. +1. If using an 700 series Zniffer, install the **Gecko SDK** in the latest version inside Simplicity Studio. 1. If using the 500 series Zniffer, figure out where to get the Zniffer firmware and drivers from. ## Converting a 700/800 series controller into a Zniffer 1. Open Simplicity Studio and connect the Z-Wave controller to your PC. -1. (optional) **Enable Debug Access** - this can be necessary if the device behaves erratically after flashing: +1. If switching from a controller to a Zniffer, **erase the device**: 1. Click on **Tools** - 1. Click on **Flash Programmer**, then OK + 1. Click on **Simplicity Commander**, then OK + 1. Select your device in the top left corner under _Select Kit..._ + 1. Go to the **Flash** tab + 1. Click on **Erase User Data** _(not sure if necessary)_ + 1. Click on **Erase chip** 1. Click on **Unlock Debug Access**, then confirm that the device will be erased + 1. Close Simplify Commander 1. (optional) Install the Gecko **Bootloader** - this is only necessary the first time and after enabling debug access: 1. Open the Welcome page 1. Select your device, click **Start** - 1. Make sure that the latest Gecko SDK is selected under **Preferred SDK** + 1. Make sure that the latest Gecko SDK (700 series) or Simplicity SDK (800 series) is selected under **Preferred SDK** 1. Click on the **Example Projects & Demos** tab - 1. Select filters: **Z-Wave**, **NCP**, - 1. In the **Bootloader - NCP UART XMODEM (For Z-Wave Applications)** card, click **CREATE** - 1. Accept the defaults on the following dialog and click **FINISH** - 1. Wait for the project to be created - 1. In the Project explorer, right-click your project. From the context menu, select **Run As** → **1 Silicon Labs ARM Program** + 1. Select filters: **Z-Wave**, search for **bootloader** + 1. If the list contains a demo with an **OTW Bootloader** for your board, e.g. **Z-Wave OTW BRD2603A Bootloader**: + 1. On that card, click **RUN** + 1. If not: + 1. In the **Bootloader - NCP UART XMODEM (For Z-Wave Applications)** card, click **CREATE** + 1. Accept the defaults on the following dialog and click **FINISH** + 1. Wait for the project to be created + 1. In the Project explorer, right-click your project. From the context menu, select **Run As** → **1 Silicon Labs ARM Program** 1. Wait for the flashing to complete. The bootloader is now installed. 1. Install the **Zniffer firmware**: 1. Open the Welcome page 1. Select your device, click **Start** - 1. Make sure that the latest Gecko SDK is selected under **Preferred SDK** + 1. Make sure that the latest Gecko SDK (700 series) or Simplicity SDK (800 series) is selected under **Preferred SDK** 1. Click on the **Example Projects & Demos** tab - 1. Select filters: **Z-Wave**, **NCP**, - 1. In the **Z-Wave - NCP Zniffer PTI** card, click **CREATE** - 1. Accept the defaults on the following dialog and click **FINISH** - 1. Wait for the project to be created - 1. In the Project explorer, right-click your project. From the context menu, select **Run As** → **1 Silicon Labs ARM Program** + 1. Select filters: **Z-Wave**, search for **Zniffer** + 1. If the list contains a demo with **NCP Zniffer Beta** in the name (the region does not matter, as you can change it in software): + 1. On that card, click **RUN** + 1. If not: + 1. In the **Z-Wave - NCP Zniffer Beta** card, click **CREATE** + 1. Accept the defaults on the following dialog and click **FINISH** + 1. Wait for the project to be created + 1. In the Project explorer, right-click your project. From the context menu, select **Run As** → **1 Silicon Labs ARM Program** 1. Wait for the flashing to complete. The Zniffer firmware is now installed. 1. On Windows, you can immediately verify that it works by starting **Tools** → **Z-Wave Zniffer**. +## Updating the Zniffer + +See [Converting a 700/800 series controller into a Zniffer](#converting-a-700800-series-controller-into-a-zniffer), step _4. Install the Zniffer firmware_. + +## Converting a 700/800 Zniffer back into a controller + +1. Open Simplicity Studio and connect the Zniffer to your PC. +1. **Erase the device**: + 1. Click on **Tools** + 1. Click on **Simplicity Commander**, then OK + 1. Select your device in the top left corner under _Select Kit..._ + 1. Go to the **Flash** tab + 1. Click on **Erase User Data** _(not sure if necessary)_ + 1. Click on **Erase chip** + 1. Click on **Unlock Debug Access**, then confirm that the device will be erased + 1. Close Simplify Commander +1. Install the Gecko **Bootloader**: + 1. Open the Welcome page + 1. Select your device, click **Start** + 1. Make sure that the latest Gecko SDK (700 series) or Simplicity SDK (800 series) is selected under **Preferred SDK** + 1. Click on the **Example Projects & Demos** tab + 1. Select filters: **Z-Wave**, search for **bootloader** + 1. If the list contains a demo with an **OTW Bootloader** for your board, e.g. **Z-Wave OTW BRD2603A Bootloader**: + 1. On that card, click **RUN** + 1. If not: + 1. In the **Bootloader - NCP UART XMODEM (For Z-Wave Applications)** card, click **CREATE** + 1. Accept the defaults on the following dialog and click **FINISH** + 1. Wait for the project to be created + 1. In the Project explorer, right-click your project. From the context menu, select **Run As** → **1 Silicon Labs ARM Program** + 1. Wait for the flashing to complete. The bootloader is now installed. +1. Install the **Controller firmware**: + 1. Open the Welcome page + 1. Select your device, click **Start** + 1. Make sure that the latest Gecko SDK (700 series) or Simplicity SDK (800 series) is selected under **Preferred SDK** + 1. Click on the **Example Projects & Demos** tab + 1. Select filters: **Z-Wave**, search for **Serial api** + 1. If the list contains a demo with **NCP Serial API Controller** in the name (the region does not matter, as you can change it in software): + 1. On that card, click **RUN** + 1. If not: + 1. In the **Z-Wave - NCP Serial API Controller** card, click **CREATE** + 1. Accept the defaults on the following dialog and click **FINISH** + 1. Wait for the project to be created + 1. In the Project explorer, right-click your project. From the context menu, select **Run As** → **1 Silicon Labs ARM Program** + 1. Wait for the flashing to complete. The Controller firmware is now installed. + ## Converting a UZB3 into a Zniffer See https://community.silabs.com/s/article/z-wave-500-converting-a-uzb3-controller-to-a-zniffer?language=en_US for instructions to install the Zniffer firmware and https://community.silabs.com/s/article/z-wave-500-programming-uzb3-controller-stick?language=en_US (including comments) on how to use the **Z-Wave Programmer** software.