|
1 | 1 | --- |
2 | 2 | layout: page |
3 | 3 | title: "Z-Wave" |
4 | | -description: "Instructions how to integrate your existing Z-Wave within Home Assistant." |
5 | | -date: 2016-02-27 19:59 |
| 4 | +description: "Using Z-Wave with Home Assistant." |
| 5 | +date: 2017-09-21 10:59 |
6 | 6 | sidebar: true |
7 | 7 | comments: false |
8 | 8 | sharing: true |
9 | 9 | footer: true |
10 | 10 | redirect_from: /getting-started/z-wave/ |
11 | 11 | --- |
12 | 12 |
|
13 | | -[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. |
| 13 | +[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](/docs/z-wave/controllers/)) to be plugged into the host. |
14 | 14 |
|
15 | 15 | There is currently support for climate, covers, lights, locks, sensors, switches, and thermostats. All will be picked up automatically after configuring this platform. |
16 | 16 |
|
17 | | -Before configuring the Z-Wave setup, please take a moment and read [this article](https://drzwave.blog/2017/01/20/seven-habits-of-highly-effective-z-wave-networks-for-consumers/) to understand the most common pitfalls of Z-Wave networks. |
| 17 | +Before configuring the Z-Wave setup, please take a moment and read [this article](https://drzwave.blog/2017/01/20/seven-habits-of-highly-effective-z-wave-networks-for-consumers/) to understand the most common pitfalls of Z-Wave networks. |
18 | 18 |
|
19 | | -### {% linkable_title Installation %} |
| 19 | +## {% linkable_title What is Z-Wave %} |
20 | 20 |
|
21 | | -As of version 0.45, Home Assistant automatically installs python-openzwave from PyPI as needed. |
| 21 | +Z-Wave is a wireless communication protocol designed for home automation. It uses a low power, and low bandwidth, mesh network that allows devices that aren't within direct range of each other to communicate indirectly, via other nodes. Any device that's permanently powered (not battery powered) will help build the mesh, if you don't have enough powered devices, or you locate these poorly, your mesh will be unreliable. |
22 | 22 |
|
23 | | -There is one dependency you will need to have installed ahead of time (included in `systemd-devel` on Fedora/RHEL systems): |
| 23 | +There is a limit of 232 devices in a single Z-Wave network. If you need more devices then you could set up a second Home Assistant system with its own Z-Wave network and connect these with the [MQTT Eventstream](/components/mqtt_eventstream/) or [MQTT Statestream](/components/mqtt_statestream) components. |
24 | 24 |
|
25 | | -```bash |
26 | | -$ sudo apt-get install libudev-dev |
27 | | -``` |
| 25 | +The Z-Wave standard was improved with Z-Wave Plus, and if you only use Z-Wave plus devices then you will gain the full benefits. |
28 | 26 |
|
29 | | -### {% linkable_title Configuration %} |
| 27 | +## {% linkable_title What do you need to use Z-Wave %} |
30 | 28 |
|
31 | | -```yaml |
32 | | -# Example configuration.yaml entry |
33 | | -zwave: |
34 | | - usb_path: /dev/ttyUSB0 |
35 | | -``` |
| 29 | +There are 2 basic things you'll need to use Z-Wave, a Z-Wave [controller](/docs/z-wave/controllers/) and one or more [devices](/docs/z-wave/devices/). |
36 | 30 |
|
37 | | -Configuration variables: |
| 31 | +### {% linkable_title Regional differences %} |
38 | 32 |
|
39 | | -- **usb_path** (*Optional*): The port where your device is connected to your Home Assistant host. |
40 | | -- **network_key** (*Optional*): The 16-byte network key in the form `"0x01,0x02..."` used in order to connect securely to compatible devices. |
41 | | -- **config_path** (*Optional*): The path to the Python OpenZWave configuration files. Defaults to the 'config' that is installed by python-openzwave |
42 | | -- **autoheal** (*Optional*): Allows disabling auto Z-Wave heal at midnight. Defaults to True. |
43 | | -- **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. |
44 | | -- **device_config** (*Optional*): This attribute contains node-specific override values. (For releases prior to 0.39 this variable is called **customize**) See [Customizing devices and services](https://home-assistant.io/getting-started/customizing-devices/) for format: |
45 | | - - **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. |
46 | | - - **ignored** (*Optional*): Ignore this entity completely. It won't be shown in the Web Interface and no events are generated for it. |
47 | | - - **refresh_value** (*Optional*): Enable refreshing of the node value. Only the light component uses this. Defaults to False. |
48 | | - - **delay** (*Optional*): Specify the delay for refreshing of node value. Only the light component uses this. Defaults to 2 seconds. |
49 | | - - **invert_openclose_buttons** (*Optional*): Inverts function of the open and close buttons for the cover domain. Defaults to `False`. |
50 | | -- **debug** (*Optional*): Print verbose z-wave info to log. Defaults to `False`. |
51 | | -- **new_entity_ids** (*Optional*): Switch to new entity_id generation. Defaults to `True`. |
52 | | - |
53 | | -To find the path of your Z-Wave USB stick or module, run: |
54 | | - |
55 | | -```bash |
56 | | -$ ls /dev/ttyUSB* |
57 | | -``` |
58 | | - |
59 | | -Or, if there is no result, try to find detailed USB connection info with: |
60 | | -```bash |
61 | | -$ dmesg | grep USB |
62 | | -``` |
63 | | - |
64 | | -Or, on some other systems (such as Raspberry Pi), use: |
65 | | - |
66 | | -```bash |
67 | | -$ ls /dev/ttyACM* |
68 | | -
|
69 | | -# If Home Assistant (`hass`) runs with another user (e.g. *homeassistant* on Hassbian) give access to the stick with: |
70 | | -$ sudo usermod -a -G dialout homeassistant |
71 | | -``` |
72 | | - |
73 | | -Or, on some other systems (such as Pine 64), use: |
74 | | - |
75 | | -```bash |
76 | | -$ ls /dev/ttyS* |
77 | | -``` |
78 | | - |
79 | | -Or, on macOS, use: |
80 | | - |
81 | | -```bash |
82 | | -$ ls /dev/cu.usbmodem* |
83 | | -``` |
84 | | - |
85 | | -<p class='note'> |
86 | | -Depending on what's plugged into your USB ports, the name found above may change. You can lock in a name, such as `/dev/zwave`, by following [these instructions](http://hintshop.ludvig.co.nz/show/persistent-names-usb-serial-devices/). |
87 | | -</p> |
88 | | - |
89 | | -<p class='note'> |
90 | | -After installing and configuring Z-Wave, Home Assistant will try to install required Python Z-Wave libraries during startup (if they are not already installed). This process might take anywhere between 5 to 25 minutes depending upon various factors. Please be patient, and let it run! This happens only once and the subsequent restarts will have no impact in performance. |
91 | | -</p> |
92 | | - |
93 | | -### {% linkable_title Adding Devices %} |
94 | | - |
95 | | -To add a Z-Wave device to your system, go to the Z-Wave panel in the Home Assistant frontend and click the Add Node button in the Z-Wave Network Management card. This will place the controller in inclusion mode, after which you should activate your device to be included by following the instructions provided with the device. |
96 | | - |
97 | | -<p class='note'> |
98 | | -Some Z-Wave controllers, like Aeotec ZW090 Z-Stick Gen5, have ability to add devices to the network using their own contol buttons. This method should be avoided as it is prone to errors. Devices added to the Z-Wave network using this method may not function well. |
99 | | -</p> |
100 | | - |
101 | | -### {% linkable_title Adding Security Devices %} |
102 | | - |
103 | | -Security Z-Wave devices require a network key before being added to the network using the Add Secure Node button in the Z-Wave Network Management card. You must set the *network_key* configuration variable to use a network key before adding these devices. |
104 | | - |
105 | | -An easy script to generate a random key: |
106 | | -```bash |
107 | | -cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' |
108 | | -``` |
109 | | - |
110 | | -### {% linkable_title Battery Powered Devices %} |
111 | | - |
112 | | -Battery powered devices need to be awake before you can use the Z-Wave control panel to update their settings. How to wake your device is device specific, and some devices will stay awake for only a couple of seconds. Please refer to the manual of your device for more details. |
113 | | - |
114 | | -### {% linkable_title Events %} |
115 | | - |
116 | | -#### {% linkable_title zwave.network_complete %} |
117 | | - |
118 | | -Home Assistant will trigger an event when the Z-Wave network is complete, meaning all of the nodes on the network have been queried. This can take quite some time, depending on wakeup intervals on the battery-powered devices on the network. |
119 | | - |
120 | | -```yaml |
121 | | - - alias: Z-Wave network is complete |
122 | | - trigger: |
123 | | - platform: event |
124 | | - event_type: zwave.network_complete |
125 | | -``` |
126 | | -
|
127 | | -#### {% linkable_title zwave.network_ready %} |
128 | | -
|
129 | | -Home Assistant will trigger an 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. |
130 | | - |
131 | | -```yaml |
132 | | - - alias: Z-Wave network is ready |
133 | | - trigger: |
134 | | - platform: event |
135 | | - event_type: zwave.network_ready |
136 | | -``` |
137 | | - |
138 | | -#### {% linkable_title zwave.network_start %} |
139 | | - |
140 | | -Home Assistant will trigger an event when the Z-Wave network is set up to be started. |
141 | | - |
142 | | -```yaml |
143 | | - - alias: Z-Wave network is starting |
144 | | - trigger: |
145 | | - platform: event |
146 | | - event_type: zwave.network_start |
147 | | -``` |
148 | | - |
149 | | -#### {% linkable_title zwave.network_stop %} |
150 | | - |
151 | | -Home Assistant will trigger an event when the Z-Wave network is stopping. |
152 | | - |
153 | | -```yaml |
154 | | - - alias: Z-Wave network is stopping |
155 | | - trigger: |
156 | | - platform: event |
157 | | - event_type: zwave.network_stop |
158 | | -``` |
159 | | - |
160 | | -#### {% linkable_title zwave.node_event %} |
161 | | -Home Assistant will trigger an 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. |
162 | | - |
163 | | -Example: |
164 | | - |
165 | | -```yaml |
166 | | - - alias: Minimote Button Pressed |
167 | | - trigger: |
168 | | - platform: event |
169 | | - event_type: zwave.node_event |
170 | | - event_data: |
171 | | - entity_id: zwave.aeon_labs_minimote_1 |
172 | | - basic_level: 255 |
173 | | -``` |
174 | | - |
175 | | -The *object_id* and *basic_level* of all triggered events can be seen in the console output. |
176 | | - |
177 | | -#### {% linkable_title zwave.scene_activated %} |
178 | | - |
179 | | -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): |
180 | | - |
181 | | -```yaml |
182 | | -# Example configuration.yaml automation entry |
183 | | -automation: |
184 | | - - alias: Turn on Desk light |
185 | | - trigger: |
186 | | - platform: event |
187 | | - event_type: zwave.scene_activated |
188 | | - event_data: |
189 | | - entity_id: zwave.zwaveme_zme_wallcs_secure_wall_controller_8 |
190 | | - scene_id: 11 |
191 | | -``` |
192 | | - |
193 | | -Some devices (like the HomeSeer wall switches) allow you to do things like double, and triple click the up and down buttons and fire an event. These devices will also send `scene_data` to differentiate the events. This is an example of double clicking the on/up button: |
194 | | - |
195 | | -```yaml |
196 | | -# Example configuration.yaml automation entry |
197 | | -automation |
198 | | - - alias: 'Dining room dimmer - double tap up' |
199 | | - trigger: |
200 | | - - event_type: zwave.scene_activated |
201 | | - platform: event |
202 | | - event_data: |
203 | | - entity_id: zwave.dining_room_cans |
204 | | - scene_id: 1 |
205 | | - scene_data: 3 |
206 | | -``` |
207 | | - |
208 | | -The *object_id* and *scene_id* of all triggered events can be seen in the console output. |
209 | | - |
210 | | -For more information on HomeSeer devices and similar devices, please see the [device specific page](https://home-assistant.io/docs/z-wave/device-specific/#homeseer-switches). |
211 | | - |
212 | | -### {% linkable_title Services %} |
213 | | - |
214 | | -The `zwave` component exposes multiple services to help maintain the network. |
215 | | - |
216 | | -| Service | Description | |
217 | | -| ------- | ----------- | |
218 | | -| add_node | Put the Z-Wave controller in inclusion mode. Allows one to add a new device to the Z-Wave network.| |
219 | | -| 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. | |
220 | | -| cancel_command | Cancels a running Z-Wave command. If you have started a add_node or remove_node command, and decide you are not going to do it, then this must be used to stop the inclusion/exclusion command. | |
221 | | -| change_association | Add or remove an association in the Z-Wave network | |
222 | | -| heal_network | Tells the controller to "heal" the Z-Wave network. Basically asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. | |
223 | | -| print_config_parameter | Prints Z-Wave node's config parameter value to the log. | |
224 | | -| print_node | Print all state of Z-Wave node. | |
225 | | -| refresh_entity| Refresh Z-Wave entity by refreshing dependent values.| |
226 | | -| refresh_node| Refresh Z-Wave node. | |
227 | | -| remove_node | Put the Z-Wave controller in exclusion mode. Allows one to remove a device from the Z-Wave network.| |
228 | | -| rename_node | Sets a node's name. Requires a `node_id` and `name` field. | |
229 | | -| rename_value | Sets a value's name. Requires a `node_id`, `value_id`, and `name` field. | |
230 | | -| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail.| |
231 | | -| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail.| |
232 | | -| reset_node_meters | Reset a node's meter values. Only works if the node supports this. | |
233 | | -| set_config_parameter | Lets the user set a config parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g. `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g. `"value": 1`). | |
234 | | -| set_poll_intensity | Lets the user set the polling intensity of a value. Changes the polling intensity without the need of a restart. This does not persist over restarts. To keep the setting over restarts, use the Z-Wave entity-card to set the config also. |
235 | | -| 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.| |
236 | | -| start_network | Starts the Z-Wave network.| |
237 | | -| stop_network | Stops the Z-Wave network.| |
238 | | -| 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."| |
239 | | - |
240 | | -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 `autoheal` 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. |
241 | | - |
242 | | -```yaml |
243 | | -# Example configuration.yaml automation entry |
244 | | -automation: |
245 | | - - alias: soft reset at 2:30am |
246 | | - trigger: |
247 | | - platform: time |
248 | | - at: '2:30:00' |
249 | | - action: |
250 | | - service: zwave.soft_reset |
251 | | -
|
252 | | - - alias: heal at 2:31am |
253 | | - trigger: |
254 | | - platform: time |
255 | | - at: '2:31:00' |
256 | | - action: |
257 | | - service: zwave.heal_network |
258 | | -``` |
| 33 | +There are 12 different regions for Z-Wave devices, which relates to the frequency the devices use. There is overlap between the regions, but you should ensure that you buy devices for your region. Wikipedia has a list of the [frequencies used](https://en.wikipedia.org/wiki/Z-Wave#Radio_frequencies). |
0 commit comments