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-22 16:56:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Z-Wave JS integration rename to Z-Wave (#23382)

Browse Source 
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Zack Barett 2022-07-26 10:52:06 -05:00 committed by GitHub
parent b94b85ffa6
commit eb1d54209c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
source/_integrations/zwave_js.markdown
View File

@ -1,5 +1,5 @@
---
title: Z-Wave JS
title: Z-Wave
description: Instructions on how to integrate Z-Wave with Home Assistant via Z-Wave JS.
featured: true
ha_category:
@ -42,9 +42,9 @@ ha_integration_type: integration
ha_zeroconf: true
---
This integration allows you to control a Z-Wave network via the [Z-Wave JS](https://zwave-js.github.io/node-zwave-js/#/) driver. This is our recommended Z-Wave integration for Home Assistant. If you're migrating from the deprecated `zwave`, see [our migration instructions](#migrating-from-previous-z-wave-implementations).
This integration allows you to control a Z-Wave network via the [Z-Wave JS](https://zwave-js.github.io/node-zwave-js/#/) driver. This is our recommended Z-Wave integration for Home Assistant. If you're migrating from the legacy `zwave`, see [our migration instructions](#migrating-from-previous-z-wave-implementations).
To Run Z-Wave JS you will need a [Supported Z-Wave dongle](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules), a running Z-Wave JS server (using only **one** of the add-ons or installation methods described below), and the Z-Wave JS integration.
To Run Z-Wave you will need a [Supported Z-Wave dongle](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules), a running Z-Wave JS server (using only **one** of the add-ons or installation methods described below), and the Z-Wave integration.
{% include integrations/config_flow.md %}
@ -235,7 +235,7 @@ This service will set a value on multiple Z-Wave devices using multicast. It is
| `entity_id` | no | Entity (or list of entities) to set the value on via multicast. At least two `entity_id` or `device_id` must be resolved if not broadcasting the command. |
| `device_id` | no | Device ID (or list of device IDs) to set the value on via multicast. At least two `entity_id` or `device_id` must be resolved if not broadcasting the command. |
| `area_id` | no | Area ID (or list of area IDs) for devices/entities to set the value on via multicast. At least two `entity_id` or `device_id` must be resolved if not broadcasting the command. |
| `broadcast` | no | Boolean that indicates whether you want the message to be broadcast to all nodes on the network. If you have only one Z-Wave JS network configured, you do not need to provide a `device_id` or `entity_id` when this is set to true. When you have multiple Z-Wave JS networks configured, you MUST provide at least one `device_id` or `entity_id` so the service knows which network to target. |
| `broadcast` | no | Boolean that indicates whether you want the message to be broadcast to all nodes on the network. If you have only one Z-Wave network configured, you do not need to provide a `device_id` or `entity_id` when this is set to true. When you have multiple Z-Wave networks configured, you MUST provide at least one `device_id` or `entity_id` so the service knows which network to target. |
| `command_class` | yes | ID of Command Class that you want to set the value for. |
| `property` | yes | ID of Property that you want to set the value for. |
| `property_key` | no | ID of Property Key that you want to set the value for. |
@ -261,7 +261,7 @@ Call this service to use the Command Class API directly. In most cases, the `zwa
> NOTE: This service has been deprecated and replaced with a new button entity. The service will still work for now but will be removed in a future release. Users are advised to move their automations to use the `button.press` service with the new entity which is a like for like replacement.
Calling this service forces Z-Wave JS to try to reach a node. This can be used to update the status of the node in Z-Wave JS when you think it doesn't accurately reflect reality, e.g. reviving a failed/dead node or marking the node as asleep.
Calling this service forces Z-Wave JS to try to reach a node. This can be used to update the status of the node in the Z-Wave network when you think it doesn't accurately reflect reality, e.g. reviving a failed/dead node or marking the node as asleep.
| Service Data Attribute | Required | Description |
|------------------------ |---------- |-------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -433,7 +433,7 @@ Value Notification example:
### Value updated events
Due to some devices not following the Z-Wave spec, there are scenarios where a device will send a value update but a state change won't be detected in Home Assistant. To address the gap, the `zwave_js_value_updated` event can be listened to to capture any value updates that are received by an affected entity. This event is **enabled on a per device and per entity domain basis**, and the entities will have `assumed_state` set to `true`. This change will affect how the UI for these entities look; if you'd like the UI to match other entities of the same type where `assumed_state` is not set to `true`, you can override the setting via [entity customization](/docs/configuration/customizing-devices/#assumed_state).
Due to some devices not following the Z-Wave Specification, there are scenarios where a device will send a value update but a state change won't be detected in Home Assistant. To address the gap, the `zwave_js_value_updated` event can be listened to to capture any value updates that are received by an affected entity. This event is **enabled on a per device and per entity domain basis**, and the entities will have `assumed_state` set to `true`. This change will affect how the UI for these entities look; if you'd like the UI to match other entities of the same type where `assumed_state` is not set to `true`, you can override the setting via [entity customization](/docs/configuration/customizing-devices/#assumed_state).
The following devices currently support this event:
@ -477,11 +477,11 @@ action:
## Automations
The `Z-Wave JS` integration provides its own trigger platforms which can be used in automations.
The `Z-Wave` integration provides its own trigger platforms which can be used in automations.
### `zwave_js.value_updated`
This trigger platform can be used to trigger automations on any Z-Wave JS value update, including Z-Wave values that aren't supported in Home Assistant via entities. While they can't be authored from the automation UI, they can be authored in YAML directly in your `configuration.yaml`.
This trigger platform can be used to trigger automations on any Z-Wave JS value update, including Z-Wave JS values that aren't supported in Home Assistant via entities. While they can't be authored from the automation UI, they can be authored in YAML directly in your `configuration.yaml`.
#### Example automation trigger configuration
@ -569,15 +569,15 @@ In addition to the [standard automation trigger data](/docs/automation/templatin
## Migrating from previous Z-Wave implementations
If you are switching from the `zwave` integration to the new Z-Wave JS integration, you will not need to recreate your entire network, as the network is **stored on your stick**. A few things, such as how you receive [central scene events](#events) will work differently than they did before.
If you are switching from the legacy `zwave` integration to the new Z-Wave integration, you will not need to recreate your entire network, as the network is **stored on your stick**. A few things, such as how you receive [central scene events](#events) will work differently than they did before.
### Automatic migration wizard
If you are using the `zwave` integration, there is a migration wizard that will help you set up the Z-Wave JS integration, remove the `zwave` integration and migrate the entities and devices that can be mapped from the `zwave` integration to the Z-Wave JS integration. The migration wizard is available from the `zwave` integration configuration panel in the GUI.
If you are using the legacy `zwave` integration, there is a migration wizard that will help you set up the Z-Wave integration, remove the legacy `zwave` integration and migrate the entities and devices that can be mapped from the legacy `zwave` integration to the Z-Wave integration. The migration wizard is available from the legacy `zwave` integration configuration panel in the GUI.
Some entities may not be able to migrate automatically and you will need to rename the corresponding available Z-Wave JS entities manually. Before completing the migration you will be shown a list of entities that could not be migrated automatically, and you'll have the option to abort or continue with the migration.
Some entities may not be able to migrate automatically and you will need to rename the corresponding available Z-Wave entities manually. Before completing the migration you will be shown a list of entities that could not be migrated automatically, and you'll have the option to abort or continue with the migration.
### Manual migration path
### Manual migration path from legacy `zwave` or OpenZWave
1) Make a **backup** of your Home Assistant configuration. You should do this so you'll be able to quickly revert if you encounter unexpected problems.
@ -585,11 +585,11 @@ Some entities may not be able to migrate automatically and you will need to rena
<div class='note info'>Make a list of what node ID belongs to each device. Your network (Nodes and their config etc) is stored on the stick but the names you gave your devices and entities are not. This step is optional but will save you a lot of time later.</div>
2) Remove the Z-Wave integration from Home Assistant: Settings --> Devices & Services --> Z-Wave (or OpenZWave) --> Press the three dots and click Delete.
2) Remove the legacy `zwave` or OpenZWave integration from Home Assistant: Settings --> Devices & Services --> Z-Wave (or OpenZWave) --> Press the three dots and click Delete.
<div class='note info'>
If you have configured Z-Wave manually, make sure to also remove the `zwave:` section from your `configuration.yaml`.
If you have configured the legacy `zwave` manually, make sure to also remove the `zwave:` section from your `configuration.yaml`.
</div>
@ -599,7 +599,7 @@ Some entities may not be able to migrate automatically and you will need to rena
5) Install the Z-Wave JS Server of your choice. If you run the supervisor and you'd like to run the standard add-on, you can skip this step if you want. The add-on is installed automatically for you when you choose so in the integration set-up. Remember to fill in the network key you've saved before.
6) Set up the Z-Wave JS integration and connect it to the server. You should see your nodes being detected by Home Assistant. Carefully watch if the status of the node is "ready". This means it's been fully interviewed (and those details cached) by the Z-Wave JS driver. Battery-powered nodes will only be interviewed when they wake up (at scheduled intervals) or if you manually wakeup the device (refer to the device's manual for instructions).
6) Set up the Z-Wave integration and connect it to the server. You should see your nodes being detected by Home Assistant. Carefully watch if the status of the node is "ready". This means it's been fully interviewed (and those details cached) by the Z-Wave JS driver. Battery-powered nodes will only be interviewed when they wake up (at scheduled intervals) or if you manually wakeup the device (refer to the device's manual for instructions).
<div class='note info'>
@ -611,7 +611,7 @@ Some entities may not be able to migrate automatically and you will need to rena
8) Enjoy your super fast up-to-date Z-Wave network in Home Assistant with support for all modern devices!
#### Need more help with your migration to Z-Wave JS?
#### Need more help with your migration to Z-Wave?
Please see our [Frequently Asked Questions](#frequently-asked-questions).
@ -629,11 +629,11 @@ You can also visit the `#zwave` channel on [our discord](/join-chat/).
## Advanced installation instructions
If you are using Home Assistant Container, Home Assistant Core, or you don't want to use the built-in Z-Wave JS Server add-on, you will need to run the Z-Wave JS server yourself, to which the Z-Wave JS integration will connect.
If you are using Home Assistant Container, Home Assistant Core, or you don't want to use the built-in Z-Wave JS Server add-on, you will need to run the Z-Wave JS server yourself, to which the Z-Wave integration will connect.
### Running [Z-Wave JS Server](https://github.com/zwave-js/zwave-js-server).
This application provides the connection between your Z-Wave USB stick and Home Assistant. The Home Assistant Z-Wave JS integration connects to this server via a websocket connection. You need to run this Z-Wave server before you can use the integration.
This application provides the connection between your Z-Wave USB stick and Home Assistant. The Home Assistant Z-Wave integration connects to this server via a websocket connection. You need to run this Z-Wave JS server before you can use the integration.
There are multiple ways to run this server:
@ -641,7 +641,7 @@ There are multiple ways to run this server:
_This option is only available for Home Assistant OS (the recommended installation type) and Home Assistant Supervised installations._
This add-on can only be configured via the built-in Z-Wave JS control panel in Home Assistant.
This add-on can only be configured via the built-in Z-Wave control panel in Home Assistant.
**Option 2: The Zwavejs2Mqtt (aka "Z-Wave JS to MQTT") add-on installed from the community add-on store**
@ -649,7 +649,7 @@ _This option is only available for Home Assistant OS (the recommended installati
This add-on includes the Z-Wave JS Server as part of the Zwavejs2Mqtt application. Despite the name, MQTT is not required to run this add-on and both provide the same Z-Wave JS driver.
The Z-Wave network can be configured via the built-in Z-Wave JS control panel in Home Assistant and alternatively via the Z-Wave JS control panel built into Zwavejs2Mqtt. It provides you with a full-fledged, attractive, and feature-complete UI to manage your Z-Wave nodes and settings, which may support more advanced use cases as development continues on the Z-Wave JS control panel.
The Z-Wave network can be configured via the built-in Z-Wave control panel in Home Assistant and alternatively via the Z-Wave control panel built into Zwavejs2Mqtt. It provides you with a full-fledged, attractive, and feature-complete UI to manage your Z-Wave nodes and settings, which may support more advanced use cases as development continues on the Z-Wave control panel.
**Option 3: The Zwavejs2Mqtt Docker container**
@ -657,13 +657,13 @@ This is the recommended approach if you're running Home Assistant Container. See
This method provides the same server application and UI as the Zwavejs2Mqtt add-on. After installing the Docker image, make sure you enable the WS Server in the Home Assistant section of Settings page.
**Option 4: Run the Z-Wave server yourself**
**Option 4: Run the Z-Wave JS server yourself**
This is considered a very advanced use case. In this case you run the Z-Wave JS Server or Zwavejs2Mqtt 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 [Zwavejs2Mqtt](https://github.com/zwave-js/zwavejs2mqtt) GitHub repository for information.
<div class='note info'>
[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 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 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`.
</div>
@ -673,15 +673,15 @@ This is considered a very advanced use case. In this case you run the Z-Wave JS
For new installations, unique default keys will be auto-generated for you by the Z-Wave JS add-on. You can also generate those network keys in the Settings section of Zwavejs2Mqtt.
If migrating from the `zwave` integration, your network key from those integration should be entered as the S0 network key. Those integrations did not support S2 security, so you will not yet have S2 network keys to configure.
If migrating from the legacy `zwave` integration, your network key from those integration should be entered as the S0 network key. Those integrations did not support S2 security, so you will not yet have S2 network keys to configure.
Make sure that you keep a backup of these keys in a safe place. You will need to enter the same keys to be able to access securely paired devices.
</div>
### Installing and configuring the Z-Wave JS integration in Home Assistant
### Installing and configuring the Z-Wave integration in Home Assistant
Once you have the Z-Wave server up and running, you need to install and configure the integration in Home Assistant (as described above).
Once you have the Z-Wave JS server up and running, you need to install and configure the integration in Home Assistant (as described above).
If you're running full Home Assistant with supervisor, you will be presented with a dialog that asks if you want to use the Z-Wave JS Supervisor add-on. You **must** uncheck this box if you are running the Z-Wave JS server in any manner other than the official Z-Wave JS add-on, including using Z-Wave JS to MQTT add-on.
@ -695,19 +695,19 @@ See the [Z-Wave JS device database](https://devices.zwave-js.io/).
While there is support for the most common devices, some command classes are not yet (fully) implemented in Z-Wave JS. You can track the status [here](https://github.com/zwave-js/node-zwave-js/issues/6).
You can also keep track of the Roadmap for the Z-Wave JS integration [here](https://github.com/home-assistant-libs/zwave-js-server-python/issues/56).
You can also keep track of the roadmap for the Z-Wave integration [here](https://github.com/home-assistant-libs/zwave-js-server-python/issues/56).
### Installation and Configuration
#### Which Z-Wave controller should I buy?
Z-Wave JS supports all known 500 and 700 series Z-Wave controllers. If you are just starting out, we recommend that you purchase a 500 series controller.
Z-Wave supports all known 500 and 700 series Z-Wave controllers. If you are just starting out, we recommend that you purchase a 500 series controller.
For more information, see [Supported Z-Wave dongles](/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules)
#### Why was I (or why was I not) automatically prompted to install Z-Wave JS?
#### Why was I (or why was I not) automatically prompted to install Z-Wave?
Some Z-Wave USB sticks can be auto-discovered, which can simplify the Z-Wave JS setup process. The following devices have been tested with discovery, and offer a quick setup experience; however, these are **not** all of the devices supported by Z-Wave JS:
Some Z-Wave USB sticks can be auto-discovered, which can simplify the Z-Wave setup process. The following devices have been tested with discovery, and offer a quick setup experience; however, these are **not** all of the devices supported by Z-Wave:
| Device | Identifier | Vendor |
| -------| ---------- | ------ |
@ -743,17 +743,17 @@ You can, but you cannot run them both at the same time. Only one of them can be
Switching does not require renaming your devices.
1. Disable the Z-Wave JS integration. **Do not remove the Z-Wave JS integration or you will lose all device and entity naming.** This will automatically stop the official Z-Wave JS add-on.
1. Disable the Z-Wave integration. **Do not remove the Z-Wave integration or you will lose all device and entity naming.** This will automatically stop the official Z-Wave JS add-on.
2. Note your network security keys from the official add-on.
3. Install and configure the Z-Wave JS to MQTT add-on, including setting the location of your Z-Wave device and the network security keys.
4. Add the Z-Wave JS integration again (even though it is still installed), and uncheck the "Use the Z-Wave JS Supervisor add-on". Enter the correct address for the community add-on in the URL field in the next step.
4. Add the Z-Wave integration again (even though it is still installed), and uncheck the "Use the Z-Wave JS Supervisor add-on". Enter the correct address for the community add-on in the URL field in the next step.
5. Uninstall the official Z-Wave JS add-on.
6. Enable the Z-Wave JS integration.
6. Enable the Z-Wave integration.
#### What's the benefit of using Zwavejs2Mqtt over the official Add-On?
@ -780,11 +780,11 @@ Ultimately, this is a personal decision. If you provide a name or location for a
Names set in Home Assistant will not import into Zwavejs2Mqtt.
### Using Z-Wave JS
### Using Z-Wave
#### How can I add (include) a new device to my Z-Wave network?
1. In Home Assistant: open Settings -> Devices & Services -> Z-Wave JS -> Configure.
1. In Home Assistant: open Settings -> Devices & Services -> Z-Wave -> Configure.
2. Press `+ ADD DEVICE`.
3. The Z-Wave controller is now in inclusion mode and will not respond to other commands.
4. Put the device you want to add in inclusion mode. Refer to its manual how this is done.
@ -795,20 +795,20 @@ If your device is included using S2 security, you may be prompted to enter a PIN
**Warning:**
1. **Do not move your Z-Wave stick to include devices.** This is no longer necessary and leads to broken routes.
1. **Do not move your Z-Wave stick to include devices.** This 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.
#### Should I use `Secure Inclusion`?
That depends. There are two generations of Z-Wave security, S0, and S2.
That depends. There are two generations of Z-Wave security, S0, and S2.
S0 security imposes significant additional traffic on your mesh and is recommended only for devices that require security, such as door locks.
S2 security does not impose additional network traffic and provides additional benefits, such as detecting packet corruption. By default, Z-Wave JS attempts S2 security during inclusion if supported, falling back to S0 security only when necessary.
S2 security does not impose additional network traffic and provides additional benefits, such as detecting packet corruption. By default, Z-Wave attempts S2 security during inclusion if supported, falling back to S0 security only when necessary.
#### How do I remove (exclude) a device from my Z-Wave network?
1. In Home Assistant: open Settings -> Devices & Services -> Z-Wave JS -> Configure.
1. In Home Assistant: open Settings -> Devices & Services -> Z-Wave -> Configure.
2. Press `REMOVE DEVICE`.
3. Press `START EXCLUSION`. The Z-Wave controller is now in exclusion mode and will not respond to other commands.
4. Put the device you want to remove in exclusion mode. Refer to its manual how this is done.
@ -818,7 +818,7 @@ S2 security does not impose additional network traffic and provides additional b
#### I'm having a problem, what should I do first?
_Many_ reported issues result from RF interference caused by the system's USB ports. This can manifest in many ways, including devices that won't include at all, devices that won't include securely, sensors with erroneous values (packets corrupted), delayed control of devices, or no ability to control devices. These problems can be intermittent, and they may be newly apparent after switching from `ozw`, though they existed before, as Z-Wave JS interviews devices and reports errors differently.
_Many_ reported issues result from RF interference caused by the system's USB ports. This can manifest in many ways, including devices that won't include at all, devices that won't include securely, sensors with erroneous values (packets corrupted), delayed control of devices, or no ability to control devices. These problems can be intermittent, and they may be newly apparent after switching from `ozw`, though they existed before, as Z-Wave interviews devices and reports errors differently.
**All users are encouraged to use a USB extension cable to prevent such interference.** Please try such a cable before opening an issue or requesting support on Discord. It will nearly always be the first troubleshooting step that we ask you to take anyway.
@ -840,7 +840,7 @@ If you are certain that your device should have entities and you do not see them
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).
Z-Wave JS 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.
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.
- We provide a `zwave_js.refresh_value` service to allow you to manually poll a value, for example from an automation that only polls a device when there is motion in that same room. If you **really** need polling, you can enable this in Zwavejs2Mqtt but not in the official add-on.
@ -850,7 +850,7 @@ Z-Wave JS does not automatically poll devices on a regular basis. Polling can qu
Polling should only be used as a last resort. You must use it with care and accept the negative impact on your network. Z-Wave is a very low speed network and poll requests can easily flood your network and slow down your commands.
</div>
#### My device is recognized as Unknown Manufacturer and/or some of its functionalities do not work in Z-Wave JS
#### My device is recognized as Unknown Manufacturer and/or some of its functionalities do not work with the Z-Wave integration
When your device is not yet fully interviewed, this info will not yet be present. So make sure your device is interviewed at least once.
@ -860,16 +860,16 @@ If the interview is complete, then the device does not yet have a device file fo
When trying to determine why something isn't working as you expect, or when reporting an issue with the integration, it is helpful to know what Z-Wave JS sees as the current state of your Z-Wave network. To get a dump of your current network state, follow the menu:
{% my integrations title="**Settings** -> **Devices & Services**" %} -> **Z-Wave JS** -> **...** -> **Download diagnostics**
{% my integrations title="**Settings** -> **Devices & Services**" %} -> **Z-Wave** -> **...** -> **Download diagnostics**
### Interference issues
Many users have reported issues with interference when the USB stick was directly connected to the machine (proximity). If you are having issues try to use a short USB 2.0 A male to female extension cord.
#### How to access the Z-Wave JS logs
#### How to access the Z-Wave logs
Z-Wave JS writes details to its logs. To access these logs go to the following.
**Configuraton** -> **Devices & Services** -> **Integrations(tab)** -> **Z-Wave JS (CONFIGURE)** -> **Logs(tab)**
**Configuraton** -> **Devices & Services** -> **Integrations(tab)** -> **Z-Wave (CONFIGURE)** -> **Logs(tab)**
You need to keep this browser tab open for logging to be active.