From b167b8f64bbaae333c7b0732396d868bd723c722 Mon Sep 17 00:00:00 2001 From: Fredrik Lindqvist Date: Sun, 18 Sep 2016 16:44:03 +0200 Subject: [PATCH] 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 --- .../asides/getting_started_navigation.html | 2 +- .../z-wave-controllers.markdown | 8 ++- .../z-wave-device-specific.markdown | 8 +-- .../getting-started/z-wave-settings.markdown | 6 +- source/getting-started/z-wave.markdown | 59 +++++++++++-------- 5 files changed, 46 insertions(+), 37 deletions(-) diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index f9b7019d0ea..77d992a1df7 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -48,7 +48,7 @@
  • {% active_link /getting-started/z-wave/ Z-Wave %} diff --git a/source/getting-started/z-wave-controllers.markdown b/source/getting-started/z-wave-controllers.markdown index 3a40dea161e..1c8c35c81d3 100644 --- a/source/getting-started/z-wave-controllers.markdown +++ b/source/getting-started/z-wave-controllers.markdown @@ -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.

    -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.

    -## {% 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/) diff --git a/source/getting-started/z-wave-device-specific.markdown b/source/getting-started/z-wave-device-specific.markdown index adfef28bee5..c96d2e853ca 100644 --- a/source/getting-started/z-wave-device-specific.markdown +++ b/source/getting-started/z-wave-device-specific.markdown @@ -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 %} diff --git a/source/getting-started/z-wave-settings.markdown b/source/getting-started/z-wave-settings.markdown index 76682705797..ce0caf178c5 100644 --- a/source/getting-started/z-wave-settings.markdown +++ b/source/getting-started/z-wave-settings.markdown @@ -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": diff --git a/source/getting-started/z-wave.markdown b/source/getting-started/z-wave.markdown index 57e8dc4c9c7..b0951255e39 100644 --- a/source/getting-started/z-wave.markdown +++ b/source/getting-started/z-wave.markdown @@ -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 @@ -110,52 +116,52 @@ Uncomment the line: