mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-21 08:16:53 +00:00
Cleanup and update of Z-Wave documenation (#935)
* Update z-wave.markdown (#917) - Notes added to Z-wave `soft-reset` about known issues by @sgauche - Fixed usage of `zwave` component, Z-Wave for references to a Z-Wave network, and OpenZWave as a project name by @sgauche
This commit is contained in:
Fredrik Lindqvist
GitHub
parent
20c56ad641
commit
b167b8f64b
@ -48,7 +48,7 @@
|
||||
<li>
|
||||
{% active_link /getting-started/z-wave/ Z-Wave %}
|
||||
<ul>
|
||||
<li>{% active_link /getting-started/z-wave-controllers/ USB Controllers %}</li>
|
||||
<li>{% active_link /getting-started/z-wave-controllers/ Controllers %}</li>
|
||||
<li>{% active_link /getting-started/z-wave-settings/ Modifying Settings %}</li>
|
||||
<li>{% active_link /getting-started/z-wave-device-specific/ Device Specific %}</li>
|
||||
</ul>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Z-Wave USB Controllers"
|
||||
title: "Z-Wave Controllers"
|
||||
description: "Extended instructions how to setup Z-Wave."
|
||||
date: 2016-03-24 08:49 -0700
|
||||
sidebar: true
|
||||
@ -12,15 +12,16 @@ footer: true
|
||||
Z-Wave is a popular home automation protocol that is not always straightforward to setup. This page will try to help you make sense of it all.
|
||||
|
||||
<p class='note'>
|
||||
Upon first run, the z-wave component will take time to initialize entities and entities may appear with incomplete names. Running a network heal may expidite this proccess.
|
||||
Upon first run, the `zwave` component will take time to initialize entities and entities may appear with incomplete names. Running a network heal may expidite this proccess.
|
||||
</p>
|
||||
|
||||
## {% linkable_title Supported Z-Wave Sticks %}
|
||||
## {% linkable_title Supported Z-Wave USB Sticks & Hardware Modules %}
|
||||
|
||||
| Device | Works on Linux | Works on Windows | Works on OSX |
|
||||
|-------------------------|----------------|------------------|--------------|
|
||||
| Aeotec Z-Stick Series 2 | ✓ | | |
|
||||
| Aeotec Z-Stick Series 5 | ✓ | | |
|
||||
| Pine64 Z-Wave Module | ✓ | | |
|
||||
| Razberry GPIO Module | ✓ | | |
|
||||
| ZWave.me UZB1 | ✓ | | |
|
||||
|
||||
@ -29,3 +30,4 @@ Upon first run, the z-wave component will take time to initialize entities and e
|
||||
The alternative to a stick is a hub that supports Z-Wave. Home Assistant supports the following hubs with Z-Wave support:
|
||||
|
||||
- [Vera](/components/vera/)
|
||||
- [Wink](/components/wink/)
|
||||
|
||||
@ -11,16 +11,16 @@ footer: true
|
||||
|
||||
##### {% linkable_title Motion or alarm sensors %}
|
||||
|
||||
In order for Home Assistant to recognize well the sensor, you will need to change its configuration from `Basic Set (default)` to `Binary Sensor report` or `Alarm report`. Currently there's no way to do this in Home Assistant but you can use ozwcp (OpenZWave control panel), Domoticz or similar to do it
|
||||
In order for Home Assistant to recognize well the sensor, you will need to change its configuration from `Basic Set (default)` to `Binary Sensor report` or `Alarm report`. Currently there's no way to do this in Home Assistant but you can use ozwcp (OpenZWave control panel), Domoticz or similar to do it.
|
||||
These devices will either show as a binary sensor or a sensor called `Alarm xxxx` and will report a numeric value. Test to see what value is what. Sometimes this is noted in the device manual.
|
||||
|
||||
|
||||
##### {% linkable_title Locks and other secure devices %}
|
||||
|
||||
These devices require a network key to be set for the zwave network before they are paired. This key is set in OpenZwave's `options.xml` which is located in Open Zwave's directory. This should also be the same directory as `config_path:` in your `configuration.yaml`. If it's not, make sure you have the same values in all the files you are using.
|
||||
These devices require a network key to be set for the Z-Wave network before they are paired. This key is set in OpenZwave's `options.xml` which is located in OpenZWave's directory. This should also be the same directory as `config_path:` in your `configuration.yaml`. If it's not, make sure you have the same values in all the files you are using.
|
||||
The option is commented out by default in `options.xml` and is a default key. Make your own unique key. The key is in Hexadecimals.
|
||||
It is best to pair these devices in Open Zwave Control Panel or other Zwave tool that can show you logs while pairing. Test the device before you save the configuration.
|
||||
Make sure you copy the newly saved `zwcfg_[home_id].xml`into your HomeAssistant config directory.
|
||||
It is best to pair these devices in OpenZWave Control Panel or other Z-wave tool that can show you logs while pairing. Test the device before you save the configuration.
|
||||
Make sure you copy the newly saved `zwcfg_[home_id].xml`into your Home Assistant configuration directory.
|
||||
|
||||
|
||||
##### {% linkable_title Aeon Minimote %}
|
||||
|
||||
@ -9,13 +9,13 @@ sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
You may wish to modify the Z-Wave settings in your `ozw*.xml` file stored in the `.homeassistant` directory, or certain situations/devices may require it (i.e. Aeon Multisensor 6). To do this, utilize [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel). Alternatively, use [Domoticz](https://www.domoticz.com/), which incorporates the Open-Zwave Control Panel project into an easy to use Raspberry Pi image.
|
||||
You may wish to modify the Z-Wave settings in your `ozw*.xml` file stored in the `.homeassistant` configuration directory, or certain situations/devices may require it (i.e. Aeon Multisensor 6). To do this, utilize [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel). Alternatively, use [Domoticz](https://www.domoticz.com/), which incorporates the Open-Zwave Control Panel project into an easy to use Raspberry Pi image.
|
||||
|
||||
The reasoning for using these tools is that your Z-Wave controller stores the values and data that are used to control the network. The XML file in the `.homeassistant` folder acts as a settings/values cache for the Z-Wave network, so modifying it directly won't change the network values. The Open-Zwave Control Panel writes values directly to the network and will provide you with an updated `.xml` file to overwrite in your `.homeassistant` folder. This is the most foolproof way to make modifications to your Z-Wave devices.
|
||||
The reasoning for using these tools is that your Z-Wave controller stores the values and data that are used to control the network. The XML file in the `.homeassistant` configuration directory acts as a settings/values cache for the Z-Wave network, so modifying it directly won't change the network values. The [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel) writes values directly to the network and will provide you with an updated `.xml` file to overwrite in your `.homeassistant` configuration directory. This is the most foolproof way to make modifications to your Z-Wave devices.
|
||||
|
||||
Although totally normal for your Z-Wave stick (Aeon Aeotec Z-Stick Gen5 for example) to cycle through its LEDs (Yellow, Blue and Red) while plugged into your system. If you don like this behaviour then you could turn it off.
|
||||
|
||||
Use the following commands from a terminal session to your Pi where your Z-Wave stick is connected as an example.
|
||||
Use the following commands from a terminal session on your Pi where your Z-Wave stick is connected as an example.
|
||||
|
||||
Turn off "Disco lights":
|
||||
|
||||
|
||||
@ -9,9 +9,9 @@ sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
[Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Z-Wave support requires a [supported Z-Wave USB stick](https://github.com/OpenZWave/open-zwave/wiki/Controller-Compatibility-List) to be plugged into the host.
|
||||
[Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Z-Wave support requires a [supported Z-Wave USB stick or module](https://github.com/OpenZWave/open-zwave/wiki/Controller-Compatibility-List) to be plugged into the host.
|
||||
|
||||
There is currently support for switches, lights and sensors. All will be picked up automatically after configuring this platform.
|
||||
There is currently support for climate, covers, lights, locks, sensors, switches and thermostats. All will be picked up automatically after configuring this platform.
|
||||
|
||||
### {% linkable_title Installation %}
|
||||
|
||||
@ -68,13 +68,13 @@ zwave:
|
||||
Configuration variables:
|
||||
|
||||
- **usb_path** (*Required*): The port where your device is connected to your Home Assistant host.
|
||||
- **config_path** (*Optional*): The path to the Python Open Z-Wave configuration files.
|
||||
- **autoheal** (*Optional*): Allows disabling auto ZWave heal at midnight. Defaults to True.
|
||||
- **config_path** (*Optional*): The path to the Python OpenZWave configuration files.
|
||||
- **autoheal** (*Optional*): Allows disabling auto Z-Wave heal at midnight. Defaults to True.
|
||||
- **polling_interval** (*Optional*): The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the zwave network and cause problems.
|
||||
- **customize** (*Optional*): This attribute contains node-specific override values:
|
||||
- **polling_intensity** (*Optional*): Enables polling of a value and sets the frequency of polling (0=none, 1=every time through the list, 2-every other time, etc). If not specified then your device will not be polled.
|
||||
|
||||
To find the path of your Z-Wave stick, run:
|
||||
To find the path of your Z-Wave USB stick or module, run:
|
||||
|
||||
```bash
|
||||
$ ls /dev/ttyUSB*
|
||||
@ -86,6 +86,12 @@ Or, on some other systems (such as Raspberry Pi), use:
|
||||
$ ls /dev/ttyACM*
|
||||
```
|
||||
|
||||
Or, on some other systems (such as Pine 64), use:
|
||||
|
||||
```bash
|
||||
$ ls /dev/ttyS*
|
||||
```
|
||||
|
||||
Or, on macOS, use:
|
||||
|
||||
```bash
|
||||
@ -98,9 +104,9 @@ Depending on what's plugged into your USB ports, the name found above may change
|
||||
|
||||
### {% linkable_title Adding Security Devices %}
|
||||
|
||||
Security Z-Wave devices require a network key before being added to the network using the zwave.add_node_secure service. You must edit the options.xml file, located in your python-openzwave config_path to use a network key before adding these devices.
|
||||
Security Z-Wave devices require a network key before being added to the network using the `zwave.add_node_secure` service. You must edit the `options.xml` file, located in your `python-openzwave config_path` to use a network key before adding these devices.
|
||||
|
||||
Edit your options.xml file:
|
||||
Edit your `options.xml` file:
|
||||
|
||||
```bash
|
||||
<!-- <Option name="NetworkKey" value="0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F 0x10" /> -->
|
||||
@ -110,52 +116,52 @@ Uncomment the line:
|
||||
<Option name="NetworkKey" value="0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10" />
|
||||
```
|
||||
|
||||
You can replace these values with your own 16 byte network key. For more information on this process see the [Open-Zwave](https://github.com/OpenZWave/open-zwave) wiki article [Adding Security Devices to OZW](https://github.com/OpenZWave/open-zwave/wiki/Adding-Security-Devices-to-OZW)
|
||||
You can replace these values with your own 16 byte network key. For more information on this process see the [OpenZwave](https://github.com/OpenZWave/open-zwave) wiki article [Adding Security Devices to OZW](https://github.com/OpenZWave/open-zwave/wiki/Adding-Security-Devices-to-OZW)
|
||||
|
||||
### {% linkable_title Events %}
|
||||
|
||||
#### {% linkable_title zwave.network_complete %}
|
||||
HomeAssistant will trigger a event when the zwave network is complete. Meaning all of the nodes on the network have been queried. This can take quite som time, depending on wakeup intervals on the battery powered devices on the network.
|
||||
Home Assistant will trigger a event when the Z-Wave network is complete. Meaning all of the nodes on the network have been queried. This can take quite som time, depending on wakeup intervals on the battery powered devices on the network.
|
||||
|
||||
```yaml
|
||||
- alias: ZWave network is complete
|
||||
- alias: Z-Wave network is complete
|
||||
trigger:
|
||||
platform: event
|
||||
event_type: zwave.network_complete
|
||||
```
|
||||
|
||||
#### {% linkable_title zwave.network_ready %}
|
||||
HomeAssistant will trigger a event when the zwave network is ready for use. Between `zwave.network_start` and `zwave.network_ready` HomeAssistant will feel sluggish when trying to send commands to zwave nodes. This is because the controller is requesting information from all of the nodes on the network. When this is triggered all awake nodes have been queried and sleeping nodes will be queried when they awake.
|
||||
Home Assistant will trigger a event when the Z-Wave network is ready for use. Between `zwave.network_start` and `zwave.network_ready` Home Assistant will feel sluggish when trying to send commands to Z-Wave nodes. This is because the controller is requesting information from all of the nodes on the network. When this is triggered all awake nodes have been queried and sleeping nodes will be queried when they awake.
|
||||
|
||||
```yaml
|
||||
- alias: ZWave network is ready
|
||||
- alias: Z-Wave network is ready
|
||||
trigger:
|
||||
platform: event
|
||||
event_type: zwave.network_ready
|
||||
```
|
||||
|
||||
#### {% linkable_title zwave.network_start %}
|
||||
HomeAssistant will trigger a event when the zwave network is set up to be started.
|
||||
Home Assistant will trigger a event when the Z-Wave network is set up to be started.
|
||||
|
||||
```yaml
|
||||
- alias: ZWave network is starting
|
||||
- alias: Z-Wave network is starting
|
||||
trigger:
|
||||
platform: event
|
||||
event_type: zwave.network_start
|
||||
```
|
||||
|
||||
#### {% linkable_title zwave.network_stop %}
|
||||
HomeAssistant will trigger a event when the zwave network stopping.
|
||||
Home Assistant will trigger a event when the Z-Wave network stopping.
|
||||
|
||||
```yaml
|
||||
- alias: ZWave network is stopping
|
||||
- alias: Z-Wave network is stopping
|
||||
trigger:
|
||||
platform: event
|
||||
event_type: zwave.network_stop
|
||||
```
|
||||
|
||||
#### {% linkable_title zwave.node_event %}
|
||||
HomeAssistant will trigger a event when command_class_basic changes value on a node.
|
||||
Home Assistant will trigger a event when command_class_basic changes value on a node.
|
||||
This can be virtually anything, so tests have to be made to determine what value equals what.
|
||||
You can use this for automations.
|
||||
|
||||
@ -173,7 +179,7 @@ Example:
|
||||
|
||||
The *object_id* and *basic_level* of all triggered events can be seen in the console output.
|
||||
|
||||
**zwave.scene_activated**
|
||||
#### {% linkable_title zwave.scene_activated %}
|
||||
Some devices can also trigger scene activation events, which can be used in automation scripts (for example the press of a button on a wall switch):
|
||||
|
||||
```yaml
|
||||
@ -192,21 +198,22 @@ The *object_id* and *scene_id* of all triggered events can be seen in the consol
|
||||
|
||||
### {% linkable_title Services %}
|
||||
|
||||
The Z-Wave component exposes seven services to help maintain the network.
|
||||
The `zwave` component exposes ten services to help maintain the network.
|
||||
|
||||
| Service | Description |
|
||||
| ------- | ----------- |
|
||||
| add_node | Put the zwave controller in inclusion mode. Allows one to add a new device to the zwave network.|
|
||||
| add_node_secure | Put the zwave controller in secure inclusion mode. Allows one to add a new device with secure communications to the zwave network. |
|
||||
| cancel_command | Cancels a running zwave command. If you have started a add_node or remove_node command, and decides you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
|
||||
| heal_network | Tells the controller to "heal" the network. Bascially asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. |
|
||||
| remove_node | Put the zwave controller in exclusion mode. Allows one to remove a device from the zwave network.|
|
||||
| add_node | Put the Z-Wave controller in inclusion mode. Allows one to add a new device to the Z-Wave network.|
|
||||
| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows one to add a new device with secure communications to the Z-Wave network. |
|
||||
| cancel_command | Cancels a running Z-Wave command. If you have started a add_node or remove_node command, and decides you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
|
||||
| heal_network | Tells the controller to "heal" the Z-Wave network. Bascially asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. |
|
||||
| remove_node | Put the Z-Wave controller in exclusion mode. Allows one to remove a device from the Z-Wave network.|
|
||||
| soft_reset | Tells the controller to do a "soft reset". This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.|
|
||||
| start_network | Starts the Z-Wave network.|
|
||||
| stop_network | Stops the Z-Wave network.|
|
||||
| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead".|
|
||||
| rename_node | Sets a node's name. Requires an `entity_id` and `name` field. |
|
||||
|
||||
The soft_reset and heal_network commands can be used as part of an automation script
|
||||
to help keep a zwave network running relliably. For example:
|
||||
The `soft_reset` and `heal_network` commands can be used as part of an automation script to help keep a Z-Wave network running reliably as shown in the example below. By default, Home Assistant will run a `heal_network` at midnight. This is a configuration option for the `zwave` component, the option defaults to `true` but can be disabled by setting `auto_heal` to false. Using the `soft_reset` function with some Z-Wave controllers can cause the Z-Wave network to hang. If you're having issues with your Z-Wave network try disabling this automation.
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml automation entry
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user