Merge branch 'current' into next

source/_docs/z-wave/adding.markdown

@@ -9,24 +9,31 @@ sharing: true
 footer: true
 ---
 
-To add (include) a Z-Wave [device](/docs/z-wave/devices/) to your system, go to the [Z-Wave control panel](/docs/z-wave/control-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.
+## {% linkable_title Adding Non-Secure Devices %}
 
-<p class='warning'>
+To add (include) a non-secure Z-Wave [device](/docs/z-wave/devices/) to your system, go to the [Z-Wave control panel](/docs/z-wave/control-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. Don't use this for secure devices, since this is likely to limit the features the device supports.
+
+<p 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.
 </p>
 
 When you add a device, it may initially appear without a specific entity ID (eg `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.
 
-## {% linkable_title Adding Security Devices %}
+## {% linkable_title Adding Secure Devices %}
 
-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. 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.
+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. 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.
 
 An easy script to generate a random key:
 ```bash
 cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'
 ```
 
-<p class='warning'>
+On macOS, this script will generate a random key:
+```bash
+cat /dev/urandom | LC_CTYPE=C tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'
+```
+
+<p 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.
 </p>
 

source/_docs/z-wave/controllers.markdown

@@ -26,6 +26,10 @@ You need to have a [supported Z-Wave USB stick or module](https://github.com/Ope
 | Vision USB Stick        |                |                  |              |
 | ZWave.me UZB1           |   ✓     |                  |              |
 
+<p class='note'>
+  If you're using Hass.io, it's recommended to use a USB stick, not a module. Passing a module through Docker is more complicated than passing a USB stick through.
+</p>
+
 ## {% linkable_title Stick Alternatives %}
 
 The alternative to a stick is a hub that supports Z-Wave. Home Assistant supports the following hubs with Z-Wave support:

source/_docs/z-wave/device-specific.markdown

@@ -155,3 +155,4 @@ Double tap off|2|3
 Triple tap on|1|4
 Triple tap off|2|4
 Tap and hold on|1|2
+Tap and hold off|2|2

source/_docs/z-wave/entities.markdown

@@ -25,7 +25,7 @@ This is for a single purpose sensor, multi sensors are explained under Multi Sen
 
 Devices (usually sensors) that support the Alarm command class will create entities starting with `sensor`, and with some generic suffixes, and a suffix that relates to the supported alarm class. For example, the smoke detector `lounge` will have an entity `sensor.lounge_smoke`, and possibly also `sensor.lounge_alarm_type` and `sensor.lounge_alarm_level`. If the device creates a `binary_sensor` entity, it is recommended to use that rather then the `sensor` entity.
 
-### {% linkable_title Alarm Type %}
+### {% linkable_title Alarm Type Entity %}
 
 - **alarm_type**: Reports the type of the sensor
   - **0**: General purpose
@@ -36,7 +36,7 @@ Devices (usually sensors) that support the Alarm command class will create entit
   - **5**: Water leak sensor
   - **6**: Access control
 
-### {% linkable_title Alarm Level %}
+### {% linkable_title Alarm Level Entity %}
 
 The meaning of the `alarm_level` entity depends on the nature of the alarm sensor
 
@@ -111,7 +111,7 @@ The meaning of the `alarm_level` entity depends on the nature of the alarm senso
   - **1**: Wake up
   - **254**: Unknown event
 
-### {% linkable_title Access Control %}
+### {% linkable_title Access Control Entity %}
 
 - **access_control**: These *may* vary between brands
   - **22**: Open
@@ -135,7 +135,7 @@ binary_sensor:
           {%- endif -%}{% endraw %}
 ```
 
-### {% linkable_title Burglar %}
+### {% linkable_title Burglar Entity %}
 
 - **burglar**: These *may* vary between brands
    - **0**: Not active
@@ -163,7 +163,7 @@ binary_sensor:
           {%- endif -%}{% endraw %}
 ```
 
-### {% linkable_title Source Node ID %}
+### {% linkable_title Source Node ID Entity %}
 
 - **sourcenodeid**: Reports the sensor that generated the alarm - this is only valid for Zensor Net based devices
 

source/_docs/z-wave/installation.markdown

@@ -16,6 +16,8 @@ On Linux platforms (other than Hass.io) there is one dependency you will need to
 $ sudo apt-get install libudev-dev
 ```
 
+On Python 3.6 you may also have to install libpython3.6-dev, and possibly python3.6-dev.
+
 When installing on macOS you may have to also run the command below ahead of time, replace "x.x" with the version of Python (`$ python3 --version`) you have installed. 
 
 ```bash
@@ -104,7 +106,7 @@ device_config:
 
 ### {% linkable_title Finding the controller path on Linux %}
 
-<p class='note'
+<p class='note'>
 If you're using Hass.io please follow [these setup instructions](/hassio/zwave/) for finding the controller path.
 </p>