jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-28 19:57:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Z-Wave: replace controller by antenna

Browse Source
This commit is contained in:
c0ffeeca7 2025-06-19 11:09:56 +02:00
parent a198f877f5
commit 889a281ab3
No known key found for this signature in database
GPG Key ID: 11BDC0C7599B77E7
2 changed files with 73 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
source/_docs/z-wave/controllers.markdown
View File

@ -1,5 +1,5 @@
---
title: "Z-Wave Controllers"
title: "Z-Wave antennas"
description: "Extended instructions how to setup Z-Wave."
related:
- docs: /integrations/zwave_js/
@ -12,7 +12,7 @@ You need to have a compatible Z-Wave stick or module installed. The following de
{% warning %}
The firmwares of 700 and 800 series Z-Wave controllers have several bugs which impact the stability of the mesh and can cause the controller to become unresponsive. Because there is no known firmware version that is completely fixed, it is recommended to choose a firmware based on the following criteria:
The firmwares of 700 and 800 series Z-Wave antennas have several bugs which impact the stability of the mesh and can cause the antenna to become unresponsive. Because there is no known firmware version that is completely fixed, it is recommended to choose a firmware based on the following criteria:
- 700 series:
- prefer SDK versions 7.17.2 to 7.18.x or 7.21.6 and newer
@ -32,7 +32,7 @@ The SDK version does not have to match the firmware version. If you are unsure w
{% endnote %}
{% important %}
You should upgrade the firmware on all 700 and 800 series controllers to a recommended version.
You should upgrade the firmware on all 700 and 800 series antennas to a recommended version.
{% endimportant %}
Firmware can be upgraded using the below directions:
@ -44,11 +44,11 @@ Firmware can be upgraded using the below directions:
{% endwarning %}
- 800 series controllers (with some caveats, see notes)
- 800 series antennas (with some caveats, see notes)
- HomeSeer SmartStick G8
- Zooz 800 Series Z-Wave Long Range S2 Stick (ZST39 LR)
- 700 series controllers
- 700 series antennas
- Aeotec Z-Stick 7 USB stick (ZWA010) (the EU version is not recommended due to RF performance issues)
- HomeSeer SmartStick+ G3
- HomeSeer Z-NET G3
@ -56,7 +56,7 @@ Firmware can be upgraded using the below directions:
- Zooz S2 Stick 700 (ZST10 700)
- Z-Wave.Me Z-Station
- 500 series controllers
- 500 series antennas
- Aeotec Z-Stick Gen5 (see note below)
- Everspring USB stick - Gen 5
- GoControl HUSBZB-1 stick
@ -73,7 +73,7 @@ Firmware can be upgraded using the below directions:
- Z-Wave.Me Razberry 2 (500 series)
- Z-Wave.Me Razberry 1 (300 series)
If you are just starting out, we recommend that you purchase a 700 series controller or a Raspberry Pi module. The 700 series controllers are the more recent version (when compared to the 500 series). The 700 series controllers support SmartStart, which allows you to add a device by scanning a QR code.
If you are just starting out, we recommend that you purchase a 700 series antenna or a Raspberry Pi module. The 700 series antennas are the more recent version (when compared to the 500 series). The 700 series antennas support SmartStart, which allows you to add a device by scanning a QR code.
{% tip %}
It's recommended to use a USB stick, not a module. Passing a module through Docker is more complicated than passing a USB stick through.
@ -88,7 +88,7 @@ The alternative to a stick is a hub that supports Z-Wave. Home Assistant support
- [SmartThings](/integrations/smartthings/)
- [Z-Wave.Me Z-Way](/integrations/zwave_me)
## Controller notes
## Antenna notes
### 800 Series Controllers
@ -98,7 +98,7 @@ Z-Wave JS does not support Z-Wave Long Range yet.
{% note %}
The Aeotec Z-Stick and some of its variants (e.g. Z-Wave.Me UZB1) are known to have compatibility issues with the Linux kernel because of their [non-compliant behavior](https://forums.raspberrypi.com/viewtopic.php?f=28&t=245031#p1502030). Plugging these controllers through a USB hub can serve as a workaround that sometimes mitigates the issue.
The Aeotec Z-Stick and some of its variants (e.g. Z-Wave.Me UZB1) are known to have compatibility issues with the Linux kernel because of their [non-compliant behavior](https://forums.raspberrypi.com/viewtopic.php?f=28&t=245031#p1502030). Plugging these antennas through a USB hub can serve as a workaround that sometimes mitigates the issue.
{% endnote %}

128
source/_integrations/zwave_js.markdown
View File

@ -50,7 +50,7 @@ The **Z-Wave** {% term integration %} allows you to control a Z-Wave network fro
## Device compatibility
You do not need a Z-Wave controller that is specifically designed for the Z-Wave integration in Home Assistant. The Z-Wave integration in Home Assistant can be operated with any Z-Wave network with other Z-Wave certified devices from other manufacturers. All mains operated nodes within the network will act as repeaters regardless of vendor to increase reliability of the network.
You do not need a Z-Wave antenna that is specifically designed for the Z-Wave integration in Home Assistant. The Z-Wave integration in Home Assistant can be operated with any Z-Wave network with other Z-Wave certified devices from other manufacturers. All mains operated nodes within the network will act as repeaters regardless of vendor to increase reliability of the network.
## Getting started
@ -60,11 +60,11 @@ This sections shows you how to set up a Z-Wave JS server and how to add your fir
Throughout this documentation, Home Assistant terminology is used. For some of the concepts, the terminology does not correspond to the terminology used in Z-Wave documentation. The table below provides equivalents for some of those terms.
| Z-Wave functionality | Home Assistant | Definition |
| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| inclusion | add | The process of adding a node to the Z-Wave network |
| exclusion | remove | The process of removing a node from the Z-Wave network |
| replication | copy (not supported in Home Assistant) | The process of copying network information from one controller to another. Not supported in Home Assistant. |
| Z-Wave functionality | Home Assistant | Definition |
| -------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| inclusion | add | The process of adding a node to the Z-Wave network |
| exclusion | remove | The process of removing a node from the Z-Wave network |
| replication | copy (not supported in Home Assistant) | The process of copying network information from one antenna to another. Not supported in Home Assistant. |
| barrier operator | cover |
| window covering | cover |
| multilevel switch | represented by different entity types: light, fan etc. |
@ -81,7 +81,7 @@ For more Z-Wave term definitions, refer to the [terminology section](#z-wave-ter
To run a Z-Wave network, you need the following elements:
- A [supported Z-Wave controller](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules). First-time user? For recommendations on what to buy, go [here](#which-z-wave-controller-should-i-buy).
- A [supported Z-Wave antenna](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules). First-time user? For recommendations on what to buy, go [here](#which-z-wave-controller-should-i-buy).
- A running [Z-Wave JS server](#setting-up-a-z-wave-js-server).
- An installed Z-Wave integration in Home Assistant.
@ -121,7 +121,7 @@ Use this My button:
- If this Z-Wave dongle has already been paired with secure devices, you need to enter the previously used network key as the S0 network key. S2 security keys will be automatically generated for you.
- Make sure that you keep a backup of these keys in a safe place in case you need to move your Z-Wave dongle to another device. Copy and paste them somewhere safe.
5. Wait for the Z-Wave JS add-on to start up.
6. Once the installation is complete, the **Device info** of the Z-Wave controller is shown.
6. Once the installation is complete, the **Device info** of the Z-Wave antenna is shown.
- You successfully installed the Z-Wave integration and the Z-Wave JS add-on.
- You can now [add](/integrations/zwave_js/#adding-a-new-device-to-the-z-wave-network) devices to the Z-Wave network.
@ -134,7 +134,7 @@ While your Z-Wave mesh is permanently stored on your dongle, the additional meta
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the Z-Wave integration. Then select **Configure**.
3. Select **Add device**.
- The Z-Wave controller is now in inclusion mode.
- The Z-Wave antenna is now in inclusion mode.
4. Check, if your device supports SmartStart:
- On the packaging, check for the SmartStart label.
- Find the QR code. It can be on the packaging or on the device itself.
@ -147,53 +147,53 @@ While your Z-Wave mesh is permanently stored on your dongle, the additional meta
- Set the device in inclusion mode. Refer to the device manual to see how this is done.
- If your device is included using S2 security, you may be prompted to enter a PIN number provided with your device. Often, this PIN is provided with the documentation _and_ is also printed on the device itself. For more information on secure inclusion, refer to [this section](/integrations/zwave_js/#should-i-use-secure-inclusion).
6. The UI should confirm that the device was added. After a short while (seconds to minutes), the entities should also be created.
7. **Troubleshooting**: If the controller fails to add/find your device, cancel the inclusion process.
7. **Troubleshooting**: If the antenna fails to add/find your device, cancel the inclusion process.
- In some cases, it might help to first [remove](/integrations/zwave_js/#removing-a-device-from-the-z-wave-network) a device (exclusion) before you add it, even when the device has not been added to this Z-Wave network yet.
- Another approach would be to factory reset the device. Refer to the device manual to see how this is done.
**Important:**
1. **Do not move your Z-Wave stick to include devices.** Moving the controller is no longer necessary and leads to broken routes.
1. **Do not move your Z-Wave stick to include devices.** Moving the antenna is no longer necessary and leads to broken routes.
2. **Do not initiate device inclusion from the Z-Wave stick itself.** This is no longer supported.
### Removing a device from the Z-Wave network
Do this before using the device with another controller, or when you don't use the device anymore. It removes the device from the Z-Wave network stored on the controller. It also removes the device and all its entities from Home Assistant. You can not join a device to a new network if it is still paired with a controller.
Do this before using the device with another antenna, or when you don't use the device anymore. It removes the device from the Z-Wave network stored on the antenna. It also removes the device and all its entities from Home Assistant. You can not join a device to a new network if it is still paired with a antenna.
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure**.
3. Select **Remove device**, then **Start exclusion**.
- The Z-Wave controller is now in exclusion mode.
- The Z-Wave antenna is now in exclusion mode.
4. Put the device you want to remove in exclusion mode. Refer to its manual how this is done.
5. The UI should confirm that the device was removed and the device and entities will be removed from Home Assistant.
## Migrating a Z-Wave network to a new controller
## Migrating a Z-Wave network to a new antenna
Do this if you have an existing Z-Wave network and want to use a new controller. This will reset your current controller (remove all network information from it) and remove the controller from Home Assistant. The Z-Wave integration with all its entities will stay in Home Assistant. The new controller is added to Home Assistant and paired with the existing network.
Do this if you have an existing Z-Wave network and want to use a new antenna. This will reset your current antenna (remove all network information from it) and remove the antenna from Home Assistant. The Z-Wave integration with all its entities will stay in Home Assistant. The new antenna is added to Home Assistant and paired with the existing network.
### Prerequisites
- Administrator rights in Home Assistant
- If you want to migrate from a 500 series controller, before starting migration, update the controller to SDK 6.61+
- If you want to migrate from a 500 series antenna, before starting migration, update the antenna to SDK 6.61+
- Check the documentation of your device to see if and how they can be updated.
- [Steps to update Aeotec Z-Stick 5](https://aeotec.freshdesk.com/support/solutions/articles/6000252294-z-stick-gen5-v1-02-firmware-update).
### To migrate a Z-Wave network to a new controller
### To migrate a Z-Wave network to a new antenna
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure**.
3. Under **Backup and restore**, select **Migrate controller**.
4. Select **Migrate to a new controller**.
3. Under **Backup and restore**, select **Migrate antenna**.
4. Select **Migrate to a new antenna**.
- To confirm device reset, select **Submit**.
- **Info**: This will initiate a backup of the network information and factory reset the controller. All the stored network information will be removed.
5. When the **Unplug your controller** dialog shows up, unplug your old controller.
- Connect the new controller.
- Confirm that you connected the new controller by selecting **Submit**.
- **Info**: This will initiate a backup of the network information and factory reset the antenna. All the stored network information will be removed.
5. When the **Unplug your antenna** dialog shows up, unplug your old antenna.
- Connect the new antenna.
- Confirm that you connected the new antenna by selecting **Submit**.
6. Follow the steps on screen.
## Overriding the radio frequency region of the controller in the Z-Wave JS add-on
## Setting the radio frequency region of the antenna in the Z-Wave JS add-on
The frequency used by Z-Wave devices depends on your region. For 700 and 800 series controllers, this frequency can be changed. The frequency of end devices cannot, so you need to make sure to buy devices specific to your region.
The frequency used by Z-Wave devices depends on your region. For 700 and 800 series antennas, this frequency can be changed. The frequency of end devices cannot, so you need to make sure to buy devices specific to your region.
If you are using the Z-Wave JS add-on, Home Assistant automatically changes the radio frequency region to match the region/country you're in. If needed, you can override this setting.
@ -201,20 +201,20 @@ If you are using the Z-Wave JS add-on, Home Assistant automatically changes the
- Administrator rights in Home Assistant
- All your Z-Wave devices must be specified for that region
- Note: this procedure only applies if your controller is [set up using the Z-Wave JS add-on](#setting-up-a-z-wave-js-server)
- Note: this procedure only applies if your antenna is [set up using the Z-Wave JS add-on](#setting-up-a-z-wave-js-server)
### To override the radio frequency region of your Z-Wave controller
### Overriding the radio frequency region of your Z-Wave antenna
1. Go to {% my supervisor_addon addon="core_zwave_js" title="**Settings** > **Add-ons** > **Z-Wave JS**" %}.
2. Open the **Configuration** tab.
3. In the **Options** section, select the **Radio Frequency Region**.
4. To apply your changes, select **Save**.
- Your Z-Wave controller is now ready to communicate with devices that were specified for your chosen region.
- Your Z-Wave antenna is now ready to communicate with devices that were specified for your chosen region.
5. To return to the default setting and use the region defined by Home Assistant, under **Radio Frequency Region** choose **Automatic**.
## Backing up your Z-Wave network
It's recommended to create a backup before making any major changes to your Z-Wave network. For example, before migrating from one controller to another, or before resetting your controller. The backup stores your Z-Wave controller's non-volatile memory (NVM), which contains your network information including paired devices. It is stored in a binary file that you can download.
It's recommended to create a backup before making any major changes to your Z-Wave network. For example, before migrating from one antenna to another, or before resetting your antenna. The backup stores your Z-Wave antenna's non-volatile memory (NVM), which contains your network information including paired devices. It is stored in a binary file that you can download.
### Prerequisites
@ -230,7 +230,7 @@ It's recommended to create a backup before making any major changes to your Z-Wa
## Updating the firmware of your Z-Wave device
Controllers and devices with the Firmware Update Metadata Command Class allow you to update the firmware by uploading a firmware file. In those cases, you can start the firmware update from the device page in Home Assistant. Refer to the documentation of the device manufacturer to find the corresponding firmware file. An example is the [firmware page by Zooz](https://www.support.getzooz.com/kb/article/1158-zooz-ota-firmware-files/).
antennas and devices with the Firmware Update Metadata Command Class allow you to update the firmware by uploading a firmware file. In those cases, you can start the firmware update from the device page in Home Assistant. Refer to the documentation of the device manufacturer to find the corresponding firmware file. An example is the [firmware page by Zooz](https://www.support.getzooz.com/kb/article/1158-zooz-ota-firmware-files/).
{% caution %}
**Risk of damage to the device due to firmware update**
@ -251,7 +251,7 @@ The Home Assistant and Z-Wave JS teams do not take any responsibility for any da
### To update firmware of a Z-Wave device
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure** and select the controller.
2. Select the **Z-Wave** integration. Then, select **Configure** and select the antenna.
3. Under **Device info**, select **Update**.
4. Select the firmware file that you previously downloaded to your computer.
- **Caution: Risk of damage to the device**
@ -261,27 +261,27 @@ The Home Assistant and Z-Wave JS teams do not take any responsibility for any da
- An interrupted update can damage your device.
5. Select **Begin firmware update** and wait for it to complete.
## Resetting a Z-Wave controller
## Resetting a Z-Wave antenna
It is recommended to back up your Z-Wave network before resetting the device.
- The controller will forget all devices it is paired with.
- The antenna will forget all devices it is paired with.
- All Z-Wave devices for this network will be removed from Home Assistant.
- If there are any devices still paired with the controller when it is reset, they will have to go through the exclusion process before they can be re-paired.
- If there are any devices still paired with the antenna when it is reset, they will have to go through the exclusion process before they can be re-paired.
- The device firmware will remain on the device.
### Prerequisites
- Administrator rights on Home Assistant
### To reset a Z-Wave controller
### To reset a Z-Wave antenna
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select the controller.
2. Select the **Z-Wave** integration. Then, select the antenna.
3. Under **Device info**, select the three dots {% icon "mdi:dots-vertical" %} menu, then select **Factory reset**.
![Screenshot showing the device panel of a Z-Wave controller](/images/integrations/z-wave/z-wave-controller-commands.png)
4. Once the process is finished, you can use this controller to start a new network, or pass it on to someone else.
![Screenshot showing the device panel of a Z-Wave antenna](/images/integrations/z-wave/z-wave-controller-commands.png)
4. Once the process is finished, you can use this antenna to start a new network, or pass it on to someone else.
## Special Z-Wave entities
@ -291,7 +291,7 @@ The Z-Wave integration provides several special entities, some of which are avai
1. **Node status** sensor: This sensor shows the node status for a given Z-Wave device. The sensor is disabled by default. The available node statuses are explained in the [Z-Wave JS documentation](https://zwave-js.github.io/node-zwave-js/#/api/node?id=status). They can be used in state change automations. For example to ping a device when it is dead, or refresh values when it wakes up.
2. **Ping** button: This button can be pressed to ping a device. It is an alternative to the `zwave_js.ping` action.
3. **Controller/node statistics** sensors: Z-Wave JS collects statistics about communications between [nodes](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotstatistics-updatedquot) and the [controller](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=quotstatistics-updatedquot). The statistics can be used to troubleshoot RF issues in your environment. These statistics are available in the network configuration and device info panels. But they are also available as sensors which are disabled by default.
3. **Antenna/node statistics** sensors: Z-Wave JS collects statistics about communications between [nodes](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotstatistics-updatedquot) and the [antenna](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=quotstatistics-updatedquot). The statistics can be used to troubleshoot RF issues in your environment. These statistics are available in the network configuration and device info panels. But they are also available as sensors which are disabled by default.
### Conditional entities
@ -312,7 +312,7 @@ The following features can be accessed from the integration configuration panel:
- **Add device:** Allows you to pre-provision a SmartStart device or start the inclusion process for adding a new device to your network.
- **Remove device:** Starts the exclusion process for removing a device from your network.
- **Rebuild network routes:** Forces your network to rediscover routes to the controller from each device. This is useful when devices or the controller have moved to a new location, or if you are having significant problems with your network, but it also generates a lot of network traffic and should be used sparingly.
- **[Controller statistics](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=quotstatistics-updatedquot):** Provides statistics about communication between the controller and other devices, allowing you to troubleshoot your network's RF quality.
- **[Antenna statistics](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=quotstatistics-updatedquot):** Provides statistics about communication between the antenna and other devices, allowing you to troubleshoot your network's RF quality.
- **Third-party data opt-in/out:** Allows you to opt-in or out of telemetry that the Z-Wave JS project collects to help inform development decisions, influence manufacturers, etc. This telemetry is disabled by default and has to be opted in to be activated.
### Integration menu
@ -324,16 +324,16 @@ Some features can be accessed from the menu of integration itself. As they are n
#### Network devices
The following features can be accessed from the device panel of any Z-Wave device on your network aside from the controller:
The following features can be accessed from the device panel of any Z-Wave device on your network aside from the antenna:
![Z-Wave device panel](/images/integrations/z-wave/z-wave-device-info.png)
- **Configure:** Provides an easy way to look up and update configuration parameters for the device. While there is an existing action for setting configuration parameter values, this UI may sometimes be quicker to use for one-off changes.
- **Re-interview:** Forces the device to go through the interview process again so that Z-Wave-JS can discover all of its capabilities. Can be helpful if you don't see all the expected entities for your device.
- **Rebuild routes:** Forces the device to rediscover its optimal route back to the controller. Use this if you think you are experiencing unexpected delays or RF issues with your device. Your device may be less responsive during this process.
- **Remove failed:** Forces the controller to remove the device from the controller. Can be used when a device has failed and it can't go through the normal exclusion process.
- **[Statistics](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotstatistics-updatedquot):** Provides statistics about communication between this device and the controller, allowing you to troubleshoot RF issues with the device.
- **Update:** Updates a device's firmware using a manually uploaded firmware file. Only some devices support this feature (controllers and devices with the Firmware Update Metadata Command Class).
- **Rebuild routes:** Forces the device to rediscover its optimal route back to the antenna. Use this if you think you are experiencing unexpected delays or RF issues with your device. Your device may be less responsive during this process.
- **Remove failed:** Forces the antenna to remove the device from the antenna. Can be used when a device has failed and it can't go through the normal exclusion process.
- **[Statistics](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotstatistics-updatedquot):** Provides statistics about communication between this device and the antenna, allowing you to troubleshoot RF issues with the device.
- **Update:** Updates a device's firmware using a manually uploaded firmware file. Only some devices support this feature (antennas and devices with the Firmware Update Metadata Command Class).
- **Download diagnostics:** Exports a JSON file describing the entities of this specific device.
## Actions
@ -820,7 +820,7 @@ In addition to the [standard automation trigger data](/docs/automation/templatin
### `zwave_js.event`
This trigger platform can be used to trigger automations on any Z-Wave JS controller, driver, or node event, including events that may not be handled by Home Assistant automatically. Refer to the linked [Z-Wave JS documentation](https://zwave-js.github.io/node-zwave-js/#/) to learn more about the available events and the data that is sent along with it.
This trigger platform can be used to trigger automations on any Z-Wave JS antenna, driver, or node event, including events that may not be handled by Home Assistant automatically. Refer to the linked [Z-Wave JS documentation](https://zwave-js.github.io/node-zwave-js/#/) to learn more about the available events and the data that is sent along with it.
There is strict validation in place based on all known event types, so if you come across an event type that isn't supported, please open a GitHub issue in the `home-assistant/core` repository.
@ -837,7 +837,7 @@ triggers:
- lock.back_door
config_entry_id:
# `event_source` and `event` are required
event_source: node # options are node, controller, and driver
event_source: node # options are node, antenna, and driver
event: "interview failed" # event names can be retrieved from the Z-Wave JS docs (see links above)
# `event_data` and `partial_dict_match` are optional. If `event_data` isn't included, all events of a given type for the given context will trigger the automation. When the `interview failed` event is fired, all argument live in a dictionary within the `event_data` dictionary under the `args` key. The default behavior is to require a full match of the event_data dictionary below and the dictionary that is passed to the event. By setting `partial_dict_match` to true, Home Assistant will check if the isFinal argument is true and ignore any other values in the dictionary. If this setting was false, this trigger would never fire because the dictionary always contains more keys than `isFinal` so the comparison check would never evaluate to true.
event_data:
@ -854,7 +854,7 @@ In addition to the [standard automation trigger data](/docs/automation/templatin
| ---------------------- | -------------------------------------------------------------------------------- |
| `trigger.device_id` | Device ID for the device in the device registry (only included for node events). |
| `trigger.node_id` | Z-Wave node ID (only included for node events). |
| `trigger.event_source` | Source of event (node, controller, or driver). |
| `trigger.event_source` | Source of event (node, antenna, or driver). |
| `trigger.event` | Name of event. |
| `trigger.event_data` | Any data included in the event. |
@ -894,7 +894,7 @@ This method provides the same server application and UI as the Z-Wave JS UI add-
This is considered a very advanced use case. In this case you run the Z-Wave JS Server or Z-Wave JS UI NodeJS application directly. Installation and maintaining this is out of scope for this document. See the [Z-Wave JS server](https://github.com/zwave-js/zwave-js-server) or [Z-Wave JS UI](https://github.com/zwave-js/zwave-js-ui/) GitHub repository for information.
{% note %}
[Supported Z-Wave dongle](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules). The Z-Wave controller dongle should be connected to the same host as where the Z-Wave JS server is running. In the configuration for the Z-Wave JS server, you need to provide the path to this stick. It's recommended to use the `/dev/serial-by-id/yourdevice` version of the path to your stick, to make sure the path doesn't change over reboots. The most common known path is `/dev/serial/by-id/usb-0658_0200-if00`.
[Supported Z-Wave dongle](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules). The Z-Wave antenna dongle should be connected to the same host as where the Z-Wave JS server is running. In the configuration for the Z-Wave JS server, you need to provide the path to this stick. It's recommended to use the `/dev/serial-by-id/yourdevice` version of the path to your stick, to make sure the path doesn't change over reboots. The most common known path is `/dev/serial/by-id/usb-0658_0200-if00`.
{% endnote %}
{% note %}
@ -925,9 +925,9 @@ You can also keep track of the road map for the Z-Wave integration [here](https:
## FAQ: Installation and configuration
### Which Z-Wave controller should I buy?
### Which Z-Wave antenna should I buy?
Z-Wave supports all known 500-, 700-, and 800-series Z-Wave controllers. If you are just starting out, we recommend that you purchase a 800-series controller (with firmware updated to >=7.23.2).
Z-Wave supports all known 500-, 700-, and 800-series Z-Wave antennas. If you are just starting out, we recommend that you purchase a 800-series antenna (with firmware updated to >=7.23.2).
For more information, see [Supported Z-Wave dongles](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules)
@ -1005,7 +1005,7 @@ By default, Z-Wave prefers Security S2, if supported. Security S0 is used only w
### Where can I see the security keys in the Z-Wave JS add-on?
After the initial setup of the Z-Wave controller, you can view the security keys in the Z-Wave JS add-on. Go to {% my supervisor_addon addon="core_zwave_js" title="**Settings** > **Add-ons** > **Z-Wave JS**" %} and open the **Configuration** tab. You can now see the three S2 keys and the S0 key. The network security key is a legacy configuration setting, identical to the S0 key.
After the initial setup of the Z-Wave antenna, you can view the security keys in the Z-Wave JS add-on. Go to {% my supervisor_addon addon="core_zwave_js" title="**Settings** > **Add-ons** > **Z-Wave JS**" %} and open the **Configuration** tab. You can now see the three S2 keys and the S0 key. The network security key is a legacy configuration setting, identical to the S0 key.
## FAQ: Troubleshooting topics
@ -1019,9 +1019,9 @@ After ensuring you are using an extension cable, rebuild network routes.
The combination of these two steps corrects a large number of reported difficulties.
### I have an Aeotec Gen5 controller, and it isn't detected on my Raspberry Pi 4?
### I have an Aeotec Gen5 antenna, and it isn't detected on my Raspberry Pi 4?
The first-generation Gen5 controller has a known bug when plugged into a Pi 4 and possibly other systems. Aeotec released the Gen5+ stick to correct this bug. Gen5 users can plug their sticks into a USB 2.0 hub in order to overcome the issue.
The first-generation Gen5 antenna has a known bug when plugged into a Pi 4 and possibly other systems. Aeotec released the Gen5+ stick to correct this bug. Gen5 users can plug their sticks into a USB 2.0 hub in order to overcome the issue.
### I do not see any entities created for my device in Home Assistant
@ -1031,7 +1031,7 @@ If you are certain that your device should have entities and you do not see them
### My device doesn't automatically update its status in HA if I control it manually
Your device might not send automatic status updates to the controller. While the best advice would be to update to recent Z-Wave Plus devices, there is a workaround with active polling (request the status).
Your device might not send automatic status updates to the antenna. While the best advice would be to update to recent Z-Wave Plus devices, there is a workaround with active polling (request the status).
Z-Wave does not automatically poll devices on a regular basis. Polling can quickly lead to network congestion and should be used very sparingly and only where necessary.
@ -1093,13 +1093,13 @@ Set the log level for `zwave_js_server` to a level higher than `debug`. This can
This sections lists functionality that is available in Z-Wave but that is not currently supported in Home Assistant.
### Setting the controller into learn mode to receive network information
### Setting the antenna into learn mode to receive network information
In Home Assistant, it is currently not possible to set the Z-Wave controller into learn mode to receive network information from another controller.
In Home Assistant, it is currently not possible to set the Z-Wave antenna into learn mode to receive network information from another antenna.
### Including / excluding a controller in an existing network using [classic inclusion](#classic-inclusion-versus-smartstart)
### Including / excluding an antenna in an existing network using [classic inclusion](#classic-inclusion-versus-smartstart)
A Z-Wave controller that manages an empty network can also join a different network and act as a secondary controller there. However, with Home Assistant, this is not possible. Home Assistant does not allow the Z-Wave controller to join another network, because Home Assistant acts as the central hub.
A Z-Wave antenna that manages an empty network can also join a different network and act as a secondary antenna there. However, with Home Assistant, this is not possible. Home Assistant does not allow the Z-Wave antenna to join another network, because Home Assistant acts as the central hub.
## Z-Wave association groups
@ -1107,7 +1107,7 @@ In Home Assistant, a single [association group](#association-group) is implement
- **Group 1**: This is an association group that includes only one device. It is used after a [factory reset](#controller), to send a **Device Reset Locally Notification**.
This association group is used when Home Assistant [resets the Z-Wave controller](#controller).
This association group is used when Home Assistant [resets the Z-Wave antenna](#controller).
Under normal circumstances, it is not necessary to add a device to this group.
@ -1164,7 +1164,7 @@ An _association group_ in Z-Wave terminology is a group of devices that another
### SmartStart
SmartStart enabled products can be added into a Z-Wave network by scanning the Z-Wave QR Code present on the product with a controller providing SmartStart inclusion.
SmartStart enabled products can be added into a Z-Wave network by scanning the Z-Wave QR Code present on the product with an antenna providing SmartStart inclusion.
No further action is required and the SmartStart product will be added automatically within 10 minutes of being switched on in the network vicinity. Not all devices support SmartStart. Some devices require [classic inclusion](#classic-inclusion-versus-smartstart). For documentation on adding a device to Home Assistant, refer to [adding a new device to the Z-Wave network](#adding-a-new-device-to-the-z-wave-network).
### Terminology mapping table
@ -1178,8 +1178,8 @@ This removes all paired Z-Wave devices and their entities, the Z-Wave JS add-on,
### To remove Z-Wave JS from Home Assistant
1. [Remove the device from your Z-Wave network](/integrations/zwave_js/#removing-a-device-from-the-z-wave-network).
- Do this for each device that is joined to your network so that it is no longer paired to the controller.
- You cannot add a device to a new controller while it is still paired with an old one.
- Do this for each device that is joined to your network so that it is no longer paired to the antenna.
- You cannot add a device to a new antenna while it is still paired with an old one.
- Alternatively, you can factory reset each device. Refer to the device manual to see how this is done.
- This usually involves finding the device in your household and pressing a button.
2. Remove the Z-Wave integration.
@ -1191,4 +1191,4 @@ This removes all paired Z-Wave devices and their entities, the Z-Wave JS add-on,
- Select **Uninstall**.
- Decide whether to also delete the data related to the add-on or whether to keep it.
4. Done. Z-Wave JS is now completely removed from your Home Assistant server.
- You can now use your Z-Wave devices and controller on a new server.
- You can now use your Z-Wave devices and antenna on a new server.