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-23 01:06:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite Z-Wave Adding and Removing Devices docs (#15535)

Browse Source
This commit is contained in:
Adam Ernst 2020-11-06 16:34:20 -06:00 committed by GitHub
parent bffb0499c2
commit 0372fd4860
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
source/_docs/z-wave/adding.markdown
View File

@ -3,81 +3,60 @@ title: "Z-Wave Devices - Adding and Removing"
description: "How to add and remove Z-Wave devices."
---
## Recommendation before adding any devices
## Adding Devices
Z-Wave devices behave as a mesh and can store network relationship details on the device itself. This means used devices or even brand new devices could already be enrolled in another network, for example, a test network for a brand new device or a previous network for devices that aren't new. This could cause headaches when you're attempting to add/enrol the device to your network. It is recommended that if possible, perform a factory reset AND device perform exclusion or disenroll for the device you're attempting to add to Home Assistant. Steps can found further below on this page under "Removing Devices".
To add a [Z-Wave device](/docs/z-wave/devices/):
## Adding Non-Secure Devices
1. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/).
2. Click **Add Node** in the *Z-Wave Network Management* card, or **Add Node Secure** for secure devices like locks. This puts your [Z-Wave controller](/docs/z-wave/controllers/) in "inclusion" mode.
3. Activate your device by following the instructions provided with it. Usually, this involves pressing a button.
4. Make sure the device is in its final location, then click **Heal Network**. This is optional but helps optimize network speed.
To add (include) a non-secure Z-Wave [device](/docs/z-wave/devices/) to your system:
1. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/) in the Home Assistant frontend
2. Click the **Add Node** button in the *Z-Wave Network Management* card - this will place the controller in inclusion mode
3. Activate your device to be included by following the instructions provided with the device
4. With the device in its final location, run a *Heal Network*
Don't use this for [secure devices](/docs/z-wave/adding/#adding-secure-devices), since this is likely to limit the features the device supports.
When you add a device, it may initially appear without a specific entity ID (e.g., `zwave.__`) or other identifying information. *Heal Network* should speed the process of populating this information. You *might* need to restart Home Assistant for the entity ID to appear.
<div class='note warning'>
Don't use the OpenZWave control panel (OZWCP), **or the physical button on a controller**, to add or remove devices. Many devices will only send the information about their capabilities at the time you include them. If you use the OpenZWave control panel, or the button on a device, then Home Assistant won't have that information. Using the physical button on a controller will also result in a non-security inclusion being performed, which may limit the features the device supports.
Some Z-Wave USB sticks have a physical "inclusion" button to add devices; **don't use it**. Likewise, don't add devices directly through other tools like [OpenZWave control panel](https://github.com/OpenZWave/open-zwave-control-panel). Many devices only send capabilities information at the time you add them, so if you add them outside of Home Assistant this information will be missing.
</div>
When you add a device, it may initially appear without a specific entity ID (e.g., `zwave.__`) and without other identifying information. Running a *Heal* should help speed this process up, and you'll need to run a *Heal* anyway so that all the devices in your Z-Wave network learn about the new device. You *might* need to restart Home Assistant (not reboot the system) to have the entity ID fully visible.
## Network Key
Security Z-Wave devices require a network key. Some devices only expose their full capabilities when included this way. You should always read the manual for your device to find out the recommended inclusion method. Note, secure devices that had been connected to another hub/network in the past may have a "theft protection" feature which requires to first exclude the device successfully from the previous hub using the previous hub/Software setup before it can be enrolled in a new hub/network.
A valid network key will be a 16 byte value, defined in the Z-Wave section of your configuration, such as the following example:
```yaml
zwave:
usb_path: /dev/ttyACM0
network_key: "0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10"
```
Each individual value in the defined key can be anywhere from 0x00 to 0xFF. Define your own key by making changes to the above example key or for additional security try one of the two scripts mentioned below.
### Network Key
Quickly generate a random key by running:
```bash
cat /dev/urandom | LC_ALL=C tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'
```
(remember you can run this in Home Assistant OS or Supervised, you can use the Terminal Add-on)
<div class='note warning'>
Ensure you keep a backup of this key. If you have to rebuild your system and don't have a backup of this key, you won't be able to reconnect to any security devices. This may mean you have to do a factory reset on those devices, and your controller, before rebuilding your Z-Wave network.
</div>
## Adding Secure Devices
After defining your network key, follow these steps to add (include) a secure Z-Wave device:
1. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/) in the Home Assistant frontend
2. Click the **Add Node Secure** button in the *Z-Wave Network Management* card - this will place the controller in inclusion mode
3. Activate your device to be included by following the instructions provided with the device
4. With the device in its final location, run a *Heal Network*
<div class='note warning'>
Secure devices require additional bandwidth, and too many secure devices can slow down your Z-Wave network. We recommend only using secure inclusion for devices that require it, such as locks.
Secure devices require additional bandwidth; too many secure devices can slow down your Z-Wave network. We recommend only using secure inclusion for devices that require it, like locks or garage door openers.
</div>
## Removing Devices
To remove (exclude) a Z-Wave device from your system:
To remove a [Z-Wave device](/docs/z-wave/devices/):
1. Go to the Z-Wave control panel in the Home Assistant frontend. (Home Assistant > Configuration > Integrations > Z-Wave > Configure)
2. Click the **Remove Node** button in the *Z-Wave Network Management* card - this will place the controller in exclusion mode
3. Activate your device to be excluded by following the instructions provided with the device
4. The device should now be removed, but that won't show until you restart Home Assistant. Look for a confirmation signal on the device if available, or confirm on the Home Assistant logs.
5. Run a *Heal Network* so all the other nodes learn about its removal
1. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/).
2. Click **Remove Node** in the *Z-Wave Network Management* card. This puts your [Z-Wave controller](/docs/z-wave/controllers/) in "exclusion" mode.
3. Activate your device by following the instructions provided with it. Usually, this involves pressing a button.
4. The device should now be removed, but that won't show until you restart Home Assistant. Look for a confirmation signal on the device if available, or confirm in the Home Assistant logs.
5. Click **Heal Network**. This is optional but helps optimize network speed.
If your device isn't responding to this process, possibly because you've factory reset it or it has failed, you can remove it using **Remove Failed Node**. This only works for devices marked as `"is_failed": true`, but you can trick the system into thinking that this the case:
If your device isn't responding to this process, possibly because you've factory reset it or it has failed, you can remove it using **Remove Failed Node**.
## Troubleshooting
Problems adding or removing devices?
### Already Added
If your device was previously added to another controller but not removed from it, **you must remove it before adding it to Home Assistant**.
1. **Remove the device from the old controller**, if possible. If your device was added to a different system (SmartThings, Wink, etc.) follow that system's instructions to remove the device. Then try adding the device to Home Assistant again.
2. If you can't remove it from the old controller, **try removing the device using Home Assistant**. Follow the instructions in [Removing Devices](#removing-devices); even though it hasn't been added to Home Assistant yet, most Z-Wave devices will respond to exclusion mode from *any* controller. Then try adding the device to Home Assistant again. (Secure devices with a theft protection feature may not allow this.)
3. If removing the device doesn't help, **try a factory reset** as a last resort. Check your device's manual for instructions.
### Range Issues
Normally you can add and remove devices as long as they are within range of any Z-Wave Plus device in your network, using a feature called [network-wide inclusion](https://z-wavealliance.org/z-wave_plus_certification/).
If you are using older non-Z-Wave Plus devices, your device may need to be within the range of your [controller](/docs/z-wave/controllers/) to be added or removed. If you cannot move the device (e.g., wall switches), you can try temporarily relocating your controller to be near your device. See the [Z-Wave Alliance documentation on Z-Wave Plus](https://z-wavealliance.org/z-wave_plus_certification/) for more information on how to determine if your devices support Z-Wave Plus.
### Forcibly Removing Devices
You can use the **Remove Failed Node** button to remove a failed device (e.g., because it is broken). In rare cases, you may want to remove a device that has *not* failed. This is not recommended but can help when a device has not been recognized as failed.
1. Go to the *States* menu under *Developer tools* in the Home Assistant frontend
2. Click on the name of the `zwave.` entity you want to remove
@ -90,13 +69,6 @@ If your device isn't responding to this process, possibly because you've factory
```
5. Click **Set State**
6. Go to the Z-Wave control panel in the Home Assistant frontend
7. Click the **Remove Failed Node** button in the *Z-Wave Node Management* card
6. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/)
7. Click **Remove Failed Node** in the *Z-Wave Node Management* card
8. The device will now be removed, but that won't show until you restart Home Assistant
## Troubleshooting
Sometimes devices won't add to Home Assistant. There are a couple of possible problems.
1. You're not using all Z-Wave Plus devices, in which case the device can't use the mesh to be added, and must be in the same room as your controller.
2. The device was previously added to another controller, and not removed. You'll need to follow the process above for removing devices first, then try adding it again.