Add link to a video of a talk at foss-north 2018

I gave a talk at foss-north, which is a free / open source conference
covering both software and hardware from the technical perspective.
They recorded it and put it on YouTube.

This patch adds a link to that talk on the help page under "Videos,
talks, workshops and alike".

_config.yml

@@ -139,14 +139,14 @@ social:
 
 # Home Assistant release details
 current_major_version: 0
-current_minor_version: 66
-current_patch_version: 1
-date_released: 2018-04-01
+current_minor_version: 69
+current_patch_version: 0
+date_released: 2018-05-11
 
 # Either # or the anchor link to latest release notes in the blog post.
 # Must be prefixed with a # and have double quotes around it.
 # Major release:
-patch_version_notes: "#release-0661---april-1"
+patch_version_notes: "#"
 # Minor release (Example #release-0431---april-25):
 
 # Date we moved to Discourse for comments

plugins/configuration.rb

@@ -2,7 +2,7 @@ module Jekyll
   class ConfigurationBlock < Liquid::Block
     TYPE_LINKS = {
       'action'       => '/docs/scripts/',
-      'device_class' => '/components/%{component}/#device_class',
+      'device_class' => '/components/%{component}/#device-class',
       'template'     => '/docs/configuration/templating/',
     }
 

plugins/environment_variables.rb

@@ -0,0 +1,17 @@
+module Jekyll
+  class EnvironmentVariablesGenerator < Generator
+    def generate(site)
+      # https://www.netlify.com/docs/continuous-deployment/#build-environment-variables
+      repo_url = ENV['REPOSITORY_URL'] || 'https://github.com/home-assistant/home-assistant.github.io'
+
+      # Rewrite urls if repo url is the ssh format.
+      if repo_url.start_with? 'git@github.com:'
+        repo_url = repo_url.sub 'git@github.com:', 'https://github.com/'
+      end
+
+      # These values will be available as {{ site.NLY_REPOSITORY_URL }}
+      site.config['NLY_REPOSITORY_URL'] = repo_url
+      site.config['NLY_HEAD'] = ENV['HEAD'] || 'current'
+    end
+  end
+end

sass/custom/_paulus.scss

@@ -4,6 +4,10 @@ $primary-color: #049cdb;
 
 .site-header {
   position: relative;
+
+  .site-title {
+    font-weight: normal;
+  }
 }
 
 .search-container {
@@ -377,18 +381,26 @@ p.note {
 }
 
 .copyright {
-  text-align: center;
+  text-align: left;
 
-  i {
-    font-size: 3em;
-    margin-right: 8px;
-    position: relative;
-    top: -5px;
+  .company {
+    .title {
+      font-size: 1.5em;
+    }
+
+    img {
+      vertical-align: middle;
+    }
+
+    i {
+      font-size: 2em;
+      padding: 0 5px;
+    }
   }
-  .credit {
-    text-align: left;
-    display: inline-block;
-    font-size: .8em;
+
+  ul {
+    margin: 0;
+    list-style: none;
   }
 }
 

source/_addons/duckdns.markdown

@@ -26,10 +26,10 @@ featured: true
 
 Configuration variables:
 
+- **lets_encrypt.accept_terms** (*Optional*): If you accept the [Let's Encrypt Subscriber Agreement][le], it will generate and update Let's Encrypt certificates for your DuckDNS domain.
 - **token** (*Required*): Your Duck DNS API key.
 - **domains** (*Required*): A list of domains to update DNS.
-- **seconds** (*Optional*): Seconds between updates to Duck DNS.
-- **lets_encrypt.accept_terms** (*Optional*): If you accept the [Let's Encrypt Subscriber Agreement][le], it will generate & update Let's Enrypt certificates for your DuckDNS domain.
+- **seconds** (*Required*): Seconds between updates to Duck DNS.
 
 [le]: https://letsencrypt.org/repository/
 
@@ -51,3 +51,5 @@ If you use a port other than `8123` or an SSL proxy, change the port number acco
 You'll need to forward the port you listed in your configuration (8123 in the example above) on your router to your Home Assistant system. You can find guides on how to do this on [Port Forward](https://portforward.com/) - noting that you'll only need to forward the TCP port.
 
 Ensure that you allocate the Home Assistant system a fixed IP on your network before you configure port forwarding. You can do this either on the computer itself (see the [install guide](/hassio/installation/) or via a static lease on your router.
+
+Restart Home Assistant for the configured changes to take effect. When you access the Home Assistant frontend you will now need to use `https`, even when accessing local instances, for example at `https://192.168.0.1:8123`. 

source/_addons/lets_encrypt.markdown

@@ -2,7 +2,7 @@
 layout: page
 title: "Let's Encrypt"
 description: "Automatically manage your SSL certificate using Let's Encrypt."
-date: 2017-04-30 13:28
+date: 2018-04-18 10:55
 sidebar: true
 comments: false
 sharing: true
@@ -41,4 +41,24 @@ http:
 
 If you use another port such as `8123` or an SSL proxy, change the port number.
 
+## {% linkable_title Enabling auto-renewals %}
+
+Out of the box, the add-on will not automatically renew your certificate. In fact, it only starts, tries to get/renew your certificte, and then stops. It's up to you to manually start it again whenever your certificate comes close to expiry.
+
+However, you can automate this process using Home Assistant.
+
+Use this in your `automations.yaml` to attempt certificate renewal each day at midnight:
+
+```yaml
+- id: letsencrypt-renewal
+  alias: "Let's Encrypt Renewal"
+  trigger:
+  - platform: time
+    at: '00:00:00'
+  action:
+  - service: hassio.addon_restart
+    data:
+      addon: core_letsencrypt
+```
+
 [DuckDNS add-on]: /addons/duckdns/

source/_addons/snips.markdown

@@ -2,14 +2,14 @@
 layout: page
 title: "Snips.ai"
 description: "Enhance your Hass.io installation with a local voice assistant."
-date: 2018-03-22 13:28
+date: 2018-05-02 13:28
 sidebar: true
 comments: false
 sharing: true
 footer: true
 ---
 
-[Snips.ai] is an AI-powered voice assistant that runs on the Raspberry Pi 3 and x86 platforms. It runs on-device and is Private by Design.
+[Snips.ai](https://snips.ai/) is an AI-powered voice assistant that runs on the Raspberry Pi 3 and x86 platforms. It runs on-device and is Private by Design.
 
 The Snips add-on depends on the Mosquitto add on to bridge to Home Assistant, so make sure that is installed.
 
@@ -17,7 +17,7 @@ HomeAssistant comes with certain Intents builtin to handle common tasks. A compl
 
 The Snips addon by default comes with an assistant that allows you to turn on lights or switches, open covers, or add and list items to a shopping list if that component is enabled.
 
-If using a USB microphone and speakers plugged into the raspberry pi output, Snips will work without any change to the configuration. Trying saying things like:
+If using a USB microphone and speakers plugged into the Raspberry Pi output, Snips will work without any change to the configuration. Trying saying things like:
 
 ```
 Turn on kitchen light
@@ -25,42 +25,16 @@ Open garage door
 What is on my shopping list
 ```
 
-To get started creating your own configuration, follow [their tutorial](https://github.com/snipsco/snips-platform-documentation/wiki/2.-Create-an-assistant-using-an-existing-bundle) to create an assistant and download the training data. You can add the HomeAssistant bundle to your assistant to enable the built-in intents, and add or create your own intents to do more complex tasks.
+To get started creating your own configuration, follow [their tutorial](https://snips.gitbook.io/documentation/console) to create an assistant and download the training data. You can also add the HomeAssistant Skill to your assistant to enable the built-in intents, and add or create your own intents to do more complex tasks.
 
-Now install and activate the [Samba] add-on so you can upload your training data. Connect to the "share" Samba share and copy your training data over. Name the file `assistant.zip`.
+Now install and activate the [Samba](/addons/samba/) add-on so you can upload your training data. Connect to the "share" Samba share and copy your assistant over. Name the file `assistant.zip` or whatever you have configured in the configuration options.
 
-Now it's time to start Snips for the first time. When the Snips add-on starts, it will output your audio devices. If you are using a USB mic and the raspberry pi output, you won't need to change anything:
+Now it's time to start Snips for the first time. You can configure the microphone and sound card using the Add-on interface. Now start the add-on.
 
-```text
-**** List of PLAYBACK Hardware Devices ****
-card 0: ALSA [bcm2835 ALSA], device 0: bcm2835 ALSA [bcm2835 ALSA]
-  Subdevices: 8/8
-  Subdevice #0: subdevice #0
-  Subdevice #1: subdevice #1
-  Subdevice #2: subdevice #2
-  Subdevice #3: subdevice #3
-  Subdevice #4: subdevice #4
-  Subdevice #5: subdevice #5
-  Subdevice #6: subdevice #6
-  Subdevice #7: subdevice #7
-card 0: ALSA [bcm2835 ALSA], device 1: bcm2835 ALSA [bcm2835 IEC958/HDMI]
-  Subdevices: 1/1
-  Subdevice #0: subdevice #0
-```
-
-You need to use this information to point the add-on at the right speakers and microphone. The information describes different cards and devices. On a Raspberry Pi 3, card 0 - device 0 is the built-in headset port, card 0 - device 1 is the HDMI port. In the example above, the USB microphone showed up as card 1 - device 0.
-
-Find the microphone and speakers that you want to use and note down their device and card number. We will need that to configure the add-on options `mic` (microphone to use) and `speaker` (speaker to use). The format for these options is `<card #>,<device #>`. Change the configuration options and click save.
-
-Now start the add-on.
-
-### Add-On configuration
+### {% linkable_title Add-On configuration %}
 
 ```json
 {
-  "mic": "1,0",
-  "speaker": "1,0",
-  "assistant": "assistant.zip",
   "mqtt_bridge": {
     "active": true,
     "host": "172.17.0.1",
@@ -68,23 +42,76 @@ Now start the add-on.
     "user": "",
     "password": ""
   },
+  "assistant": "assistant.zip",
+  "language": "en",
+  "custom_tts": false,
+  "tts_platform": "amazon_polly"
 }
 ```
 
 Configuration variables:
 
-- **mqtt_bridge** : Snips uses MQTT to communicate and defaults to their own broker. Use this config option to bridge their broker to your the Mosquitto add-on.
-- **mic**: This is the hardware address of your microphone. Look at the Snips output if you are using different hardware.
+- **mqtt_bridge**: Snips uses MQTT to communicate and defaults to their own broker. Use this config option to bridge their broker to your the Mosquitto add-on.
+- **assistant**: The name of your custom assistant in `/share`. If no assistant is found then a default assistant will be used.
+- **language**: Language. This is used to select the default custom assistant, Currently `en`, `de` and `fr` are supported.
+- **custom_tts**: Whether to use a TTS provider from Home Assistant for a variety of voices.
+- **tts_platform**: Which TTS platform to use.
 
 ### {% linkable_title Home Assistant configuration %}
 
-Use the Home Assistant [Snips.ai component][comp] to integrate the add-on into Home Assistant.
+A simple configuration just requires this. Consult [Snips.ai component](/components/snips/) for more options.
 
 ```yaml
 snips:
 ```
 
-[Snips.ai]: https://snips.ai/
+### {% linkable_title Home Assistant configuration %}
+
+There is an active [discord](https://discordapp.com/invite/3939Kqx) channel for further support.
+
+### {% linkable_title Examples %}
+
+So now you can turn lights on and off, let's check the weather. Log on to the [console](https://console.snips.ai/). If this is your first time, create a new assistant and add the Home Assistant skill, along with the Weather skill by snips. Download your assistant manually and copy it to the `/share` folder on your HassIO installation using the Samba addon.
+
+Next create a weather sensor, e.g., one for (Dark Sky)[/components/sensor.darksky/] and put the `api_key` in your `secrets.yaml` file.
+
+```yaml
+- platform: darksky
+  name: "Dark Sky Weather"
+  api_key: !secret dark_sky_key
+  update_interval:
+    minutes: 10
+  monitored_conditions:
+    - summary
+    - hourly_summary
+    - temperature
+    - temperature_max
+    - temperature_min
+```
+Next add this to your `configuration.yaml` file to reference a new `intent_script` component. This is a good practice to [split your configuration files](/docs/configuration/splitting_configuration/) up.
+
+```yaml
+intent_script: !include intent_script.yaml
+```
+
+Finally, create this `intent_script.yaml` file in your configuration directory.
+
+{% raw %}
+```yaml
+searchWeatherForecast:
+  speech:
+    type: plain
+    text: >
+      The weather is currently
+      {{ states('sensor.dark_sky_weather_temperature') | round(0) }}
+      degrees outside and {{ states('sensor.dark_sky_weather_summary') }}.
+      The high today will be
+      {{ states('sensor.dark_sky_weather_daily_high_temperature') | round(0)}}
+      and {{ states('sensor.dark_sky_weather_hourly_summary') }}
+```
+{% endraw %}
+
+Now just restart HassIO and ask it what the weather is like.
+
 [their tutorial]: https://github.com/snipsco/snips-platform-documentation/wiki/2.-Create-an-assistant-using-an-existing-bundle
-[Samba]: /addons/samba/
-[comp]: /components/snips/
+

source/_components/abode.markdown

@@ -24,7 +24,7 @@ There is currently support for the following device types within Home Assistant:
 - [Camera](/components/camera.abode/): Reports on `Camera` devices and will download and show the latest captured still image.
 - [Cover](/components/cover.abode/): Reports on `Secure Barriers` and can be used to open and close the cover.
 - [Lock](/components/cover.abode/): Reports on `Door Locks` and can be used to lock and unlock the door.
-- [Light](/components/light.abode/): Reports on `Dimmer` lights and can be used to dim, change color, or turn the light on and off.
+- [Light](/components/light.abode/): Reports on `Dimmer` lights and can be used to dim or turn the light on and off.
 - [Switch](/components/switch.abode/): Reports on `Power Switch` devices and can be used to turn the power switch on and off. Also reports on `Automations` set up in the Abode system and allows you to activate or deactivate them.
 - [Sensor](/components/sensor.abode/): Reports on `Temperature`, `Humidity`, and `Light` sensors.
 

source/_components/alarm_control_panel.alarmdecoder.markdown

@@ -27,7 +27,9 @@ The Alarm Decoder component gives you access to several services for you to cont
 - `alarm_disarm`: Disarms the alarm from any state. Also clears a `check_zone` flag after an alarm was triggered.
 - `alarmdecoder_alarm_toggle_chime`: Toggles the alarm's chime state.
 
-**Note**: `alarm_arm_custom_bypass` and `alarm_trigger`, while available in the services list in Home Assistant, are not currently implemented in the Alarm Decoder component.
+<p class='note'>
+`alarm_arm_custom_bypass` and `alarm_trigger`, while available in the services list in Home Assistant, are not currently implemented in the Alarm Decoder platform. 
+</p>
 
 ### {% linkable_title Attributes %}
 

source/_components/amcrest.markdown

@@ -28,6 +28,9 @@ amcrest:
     sensors:
       - motion_detector
       - sdcard
+    switches:
+      - motion_detection
+      - motion_recording
 
  - host: IP_ADDRESS_CAMERA_2
    username: YOUR_USERNAME
@@ -54,6 +57,9 @@ Configuration variables:
   - **motion_detector**: Return True/False when a motion is detected
   - **sdcard**: Return the SD card usage by reporting the total and used space
   - **ptz_preset**: Return the number of PTZ preset positions configured for the given camera
+- **switches** array (*Optional*): Switches to display in the frontend. By default, *none* of the switches are shown. The following switches can be monitored.
+  - **motion_detection**: Enable/disable motion detection setting 
+  - **motion_recording**: Enable/disable recording on motion detection setting
 
 **Note:** Amcrest cameras with newer firmware no longer have the ability to stream `high` definition video with MJPEG encoding. You may need to use `low` resolution stream or the `snapshot` stream source instead.  If the quality seems too poor, lower the `Frame Rate (FPS)` and max out the `Bit Rate` settings in your camera's configuration manager. If you defined the *stream_source* to **mjpeg**, make sure your camera supports *Basic* HTTP authentication. Newer Amcrest firmware may not work, then **rtsp** is recommended instead.
 

source/_components/august.markdown

@@ -15,6 +15,10 @@ ha_iot_class: "Cloud Polling"
 
 The `august` component allows you to integrate your [August](http://august.com) devices in Home Assistant. Currently this component supports August Lock and Doorbell.
 
+<p class='note'>
+August Lock 2nd Gen will need either August Connect or Doorbell to connect to Home Assistant.
+</p>
+
 ## {% linkable_title Configuration %}
 
 You will need your August login information (username (either phone# or email), and password) to use this module.

source/_components/binary_sensor.bmw_connected_drive.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
-title: "BMW connected drive"
-description: "Instructions on how to setup your BMW connected drive account with Home Assistant."
+title: "BMW Connected Drive Binary Sensor"
+description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant."
 date: 2018-02-22 23:00
 sidebar: true
 comments: false
@@ -15,6 +15,6 @@ ha_release: 0.66
 
 The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant.
 
-The binary sensors will be automatically configured if 'bmw_connected_drive' component is configured.
+The binary sensors will be automatically configured if `bmw_connected_drive` component is configured.
 
-For more configuration information see the [bmw_connected_drive component](/components/bmw_connected_drive/) documentation.
+For more configuration information see the [`bmw_connected_drive` component](/components/bmw_connected_drive/) documentation.

source/_components/binary_sensor.hive.markdown

@@ -14,11 +14,12 @@ ha_iot_class: "Cloud Polling"
 ---
 
 
-The 'hive' binary sensor component integrates your Hive sensors into Home Assistant.
+The `hive` binary sensor component integrates your Hive sensors into Home Assistant.
 
-The Hive sensor component supports the following Hive products:
-- **Hive Window or Door Sensor**
-- **Hive Motion Sensor**
+The platform supports the following Hive products:
+
+- Hive Window or Door Sensor
+- Hive Motion Sensor
 
 
 <p class='note'>

source/_components/binary_sensor.markdown

@@ -11,6 +11,8 @@ footer: true
 
 Binary sensors gather information about the state of devices which have a "digital" return value (either 1 or 0). These can be switches, contacts, pins, etc. These sensors only have two states: **0/off/low/closed/false** and **1/on/high/open/true**.  Knowing that there are only two states allows Home Assistant to represent these sensors in a better way in the frontend according to their functionality.
 
+### {% linkable_title Device Class %}
+
 The way these sensors are displayed in the frontend can be modified in the [customize section](/getting-started/customizing-devices/). The following device classes are supported for binary sensors:
 
 - **None**: Generic on/off. This is the default and doesn't need to be set.
@@ -39,3 +41,8 @@ The way these sensors are displayed in the frontend can be modified in the [cust
 - **window**: `On` means open, `Off` means closed
 
 For analog sensors please check the [component overview](/components/#sensor).
+
+<p class='img'>
+<img src='/images/screenshots/binary_sensor_classes_icons.png' />
+Example of various device classes icons in `On` and `Off` state.
+</p>

source/_components/binary_sensor.modbus.markdown

@@ -15,10 +15,12 @@ ha_iot_class: "Local Push"
 
 The `modbus` binary sensor allows you to gather data from [Modbus](http://www.modbus.org/) coils.
 
+## {% linkable_title Configuration %}
+
 To use your Modbus binary sensors in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 binary_sensor:
   - platform: modbus
     coils:
@@ -39,7 +41,7 @@ Configuration variables:
   
 It's possible to change the default 30 seconds scan interval for the sensor updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation.
 
-### {% linkable_title Full example %}
+## {% linkable_title Full example %}
 
 Example a sensor with a 10 seconds scan interval:
 

source/_components/binary_sensor.mqtt.markdown

@@ -133,7 +133,7 @@ The configuration will look like the example below:
 
 {% raw %}
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 binary_sensor:
   - platform: mqtt
     name: Bathroom

source/_components/binary_sensor.pilight.markdown

@@ -15,10 +15,12 @@ ha_iot_class: "Local Polling"
 
 The `pilight` binary sensor platform implement the [pilight hub](/components/pilight/) binary sensor functionality. Two type of Pilight binary sensor configuration available. A normal sensor which send the on and off state cyclical and a trigger sensor which send only a trigger when an event happened (for example lots of cheap PIR motion detector).
 
+
+
 To enable a Pilight binary sensor in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 binary_sensor:
   - platform: pilight
     variable: 'state'

source/_components/binary_sensor.qwikswitch.markdown

@@ -0,0 +1,18 @@
+---
+layout: page
+title: "QwikSwitch Binary Sensor"
+description: "Instructions on how to integrate Qwikswitch dimmers and relays as sensors into Home Assistant."
+date: 2016-05-04 00:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: qwikswitch.png
+ha_category: Sensor
+ha_iot_class: "Local Push"
+ha_release: "0.68"
+---
+
+The `qwikswitch` binary_sensor platform allows you to use your [QwikSwitch](http://www.qwikswitch.co.za/) sensors within Home Assistant.
+
+The platform is configured through the [QwikSwitch component](/components/qwikswitch/).

source/_components/binary_sensor.random.markdown

@@ -16,6 +16,8 @@ ha_release: 0.57
 
 The `random` binary sensor platform is creating random states (`True`, 1, `on` or `False`, 0, `off`). This can be useful if you want to test automation rules. It generates a new state every time it is polled.
 
+## {% linkable_title Configuration %}
+
 To enable the random binary sensor, add the following lines to your `configuration.yaml`:
 
 ```yaml

source/_components/binary_sensor.workday.markdown

@@ -15,6 +15,10 @@ ha_release: 0.41
 
 The `workday` binary sensor indicates, whether the current day is a workday or not. It allows specifying, which days of the week counts as workdays and also uses the python module [holidays](https://pypi.python.org/pypi/holidays) to incorporate information about region-specific public holidays.
 
+## {% linkable_title Configuration %}
+
+Check the [country list](https://github.com/dr-prodigy/python-holidays#available-countries) for available province. 
+
 To enable the `workday` sensor in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
@@ -22,14 +26,14 @@ To enable the `workday` sensor in your installation, add the following to your `
 binary_sensor:
   - platform: workday
     country: DE
-    workdays: [ mon, wed, fri ]
+    workdays: [mon, wed, fri]
 ```
 
 Configuration variables:
 
 - **name** (*Optional*): A name for this sensor. Defaults to *Workday Sensor*
-- **country** (*Required*): Country code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.3) notation.
-- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.3) notation. Defaults to None.
+- **country** (*Required*): Country code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation.
+- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. Defaults to None.
 - **workdays** (*Optional*): List of workdays. Defaults to `mon`, `tue`, `wed`, `thu`, `fri`.
 - **excludes** (*Optional*): List of workday excludes. Defaults to `sat`, `sun`, `holiday`.
 - **days_offset** (*Optional*): Set days offset. Defaults to `0`.

source/_components/bmw_connected_drive.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
-title: "BMW connected drive"
-description: "Instructions on how to setup your BMW connected drive account with Home Assistant."
+title: "BMW Connected Drive"
+description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant."
 date: 2018-01-10 23:00
 sidebar: true
 comments: false
@@ -12,7 +12,7 @@ ha_category: Hub
 ha_release: 0.64
 ---
 
-This component lets you retrieve data on your BMW vehicle from the BMW Connected Drive portal. You need to have a working BMW Connected Drive account and a Connected Drive enabled vehicle for this to work.
+This component lets you retrieve data on your BMW vehicle from the BMW Connected Drive portal. You need to have a working BMW Connected Drive account, and a Connected Drive enabled vehicle for this to work.
 
 For compatibility with your BMW vehicle check the [bimmer_connected page](https://github.com/m1n3rva/bimmer_connected) on github.
 
@@ -25,7 +25,7 @@ bmw_connected_drive:
   name:
     username: USERNAME_BMW_CONNECTED_DRIVE
     password: PASSWORD_BMW_CONNECTED_DRIVE
-    country: COUNTRY_BMW_CONNECTED_DRIVE
+    region: one of "north_america", "china" , "rest_of_world"
 ```
 
 {% configuration %}
@@ -46,12 +46,44 @@ bmw_connected_drive:
       description: Your BMW Connected Drive password.
       required: true
       type: string
-    country:
-      description: "The country of your Connected Drive account. Please use the exact names for the country as listed on the [Connected Drive website](https://www.bmw-connecteddrive.com/)."
+    region:
+      description: "The region of your Connected Drive account. Please use of these values: `north_america`, `china`, `rest_of_world`"
       required: true
       type: string
 {% endconfiguration %}
 
+## {% linkable_title Services %}
+
+The `bmw_connected_drive` component offers several services. In case you need to provide the vehicle identification number (VIN) as a parameter, you can see the VIN in the attributes of the device tracker for the vehicle. The VIN is a 17 digit alphanumeric string, e.g., `WBANXXXXXX1234567`.
+
+Using these services will impact the state of your vehicle. So use these services with care!
+
+### {% linkable_title Locking and unlocking %}
+
+The vehicle can be locked and unlocked via the lock component that is created automatically for each vehicle. Before invoking these services, make sure it's safe to lock/unlock the vehicle in the current situation.
+
+### {% linkable_title Air condition %}
+
+The air condition of the vehicle can be activated with the service `bmw_connected_drive.activate_air_conditioning`.
+
+What exactly is started here depends on the type of vehicle. It might range from just ventilation over auxiliary heating to real air conditioning. If your vehicle is equipped with auxiliary heating, only trigger this service if the vehicle is parked in a location where it is safe to use it (e.g., not in an underground parking or closed garage). 
+
+The vehicle is identified via the parameter `vin`.
+
+### {% linkable_title Sound the horn %}
+
+The service `bmw_connected_drive.sound_horn` sounds the horn of the vehicle. Use this feature responsibly, as it might annoy your neighbors. The vehicle is identified via the parameter `vin`. 
+
+### {% linkable_title Flash the lights %}
+
+The service `bmw_connected_drive.light_flash' flashes the lights of the vehicle. The vehicle is identified via the parameter `vin`.
+
+### {% linkable_title Update the state %}
+
+The service `bmw_connected_drive.update_state`fetches the last state of the vehicles of all your accounts from the BMW server. This does *not* trigger an update from the vehicle; it gets the data from the BMW servers. So this service does *not* interact with your vehicles. 
+
+This service does not require any attributes.
+
 ## {% linkable_title Disclaimer %}
 
 This software is not affiliated with or endorsed by BMW Group. 

source/_components/calendar.google.markdown

@@ -16,7 +16,7 @@ ha_release: 0.33
 
 The `google` calendar platform allows you to connect to your [Google Calendars](https://calendar.google.com) and generate binary sensors. The sensors created can trigger based on any event on the calendar or only for matching events. When you first setup this component it will generate a new configuration file `google_calendars.yaml` that will contain information about all of the calendars you can see.
 
-### {% linkable_title Prerequisites %}
+## {% linkable_title Prerequisites %}
 
 Generate a Client ID and Client Secret on [Google Developers Console](https://console.developers.google.com/start/api?id=calendar).
 
@@ -30,7 +30,7 @@ Generate a Client ID and Client Secret on [Google Developers Console](https://co
 1. Save the client ID and secret as you will need to put these in your `configuration.yaml` file.
 1. Click on "Library", search for "Google Calendar API" and enable it.
 
-### {% linkable_title Basic Setup %}
+## {% linkable_title Configuration %}
 
 To integrate Google Calendar in Home Assistant, add the following section to your `configuration.yaml` file:
 
@@ -61,7 +61,7 @@ The next steps will require you to have Home Assistant running.
 
 After you have it running complete the Google authentication that pops up. It will give you a URL and a code to enter. This will grant your Home Assistant service access to all the Google Calendars that the account you authenticate with can read. This is a Read-Only view of these calendars.
 
-### {% linkable_title Calendar Configuration %}
+## {% linkable_title Calendar Configuration %}
 
 Editing the `google_calendars.yaml` file.
 
@@ -95,7 +95,8 @@ Variables:
   - **track**: (*Required*): Should we create a sensor `True` or ignore it `False`?
   - **search**: (*Optional*): If set will only trigger for matched events.
   - **offset**: (*Optional*): A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. (Default: `!!`)
-  
+  - **ignore_availablilty**: (*Optional*): Should we respect `free`/`busy` flags? (Defaults to `true`)
+  
 From this we will end up with the binary sensors `calendar.test_unimportant` and `calendar.test_important` which will toggle themselves on/off based on events on the same calendar that match the search value set for each. You'll also have a sensor `calendar.test_everything` that will not filter events out and always show the next event available.
 
 But what if you only wanted it to toggle based on all events? Just leave out the *search* parameter.

source/_components/calendar.todoist.markdown

@@ -111,7 +111,7 @@ Home Assistant does its best to determine what task in each project is "most" im
 
 Todoist also comes with access to a service, `calendar.todoist_new_task`. This service can be used to create a new Todoist task. You can specify labels and a project, or you can leave them blank, and the task will go to your "Inbox" project.
 
-Here's an example JSON payload:
+Here are two example JSON payloads resulting in the same task:
 
 ```json
 {
@@ -123,6 +123,17 @@ Here's an example JSON payload:
 }
 ```
 
+```json
+{
+    "content": "Pick up the mail",
+    "project": "Errands",
+    "labels":"Homework,School",
+    "priority":3,
+    "due_date_string":"tomorrow at 14:00",
+    "due_date_lang":"en"
+}
+```
+
 - **content** (*Required*): The name of the task you want to create.
 
 - **project** (*Optional*): The project to put the task in.
@@ -131,6 +142,11 @@ Here's an example JSON payload:
 
 - **priority** (*Optional*): The priority of the task, from 1-4. Again, 1 means least important, and 4 means most important.
 
-- **due_date** (*Optional*): When the task should be due, in either YYYY-MM-DD format or YYYY-MM-DD HH:MM format.
+- **due_date_string** (*Optional*): When the task should be due, in [natural language](https://support.todoist.com/hc/en-us/articles/205325931-Dates-and-Times). Mutually exclusive with `due_date`
+
+- **due_date_lang** (*Optional*): When `due_date_string` is set, it is posisble to set the language. 
+  Valid languages are: `en`, `da`, `pl`, `zh`, `ko`, `de`, `pt`, `ja`, `it`, `fr`, `sv`, `ru`, `es`, `nl` 
+
+- **due_date** (*Optional*): When the task should be due, in either YYYY-MM-DD format or YYYY-MM-DD HH:MM format. Mutually exclusive with `due_date_string`.
 
 Note that there's (currently) no way to mark tasks as done through Home Assistant; task names do not necessarily have to be unique, so you could find yourself in a situation where you close the wrong task.

source/_components/camera.local_file.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
 title: "Local File"
-description: "Instructions on how to use Local File as a Camera within Home Assistant."
+description: "Instructions how to use Local File as a Camera within Home Assistant."
 date: 2016-06-12 17:00
 sidebar: true
 comments: false
@@ -13,9 +13,9 @@ ha_iot_class: "Local Polling"
 ha_release: 0.22
 ---
 
-The `local_file` camera platform allows you to integrate any readable image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated.
+The `local_file` camera platform allows you to integrate an image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated. The service `local_file_update_file_path` can be used to update the image using an automation.
 
-This can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodically and will then be displayed in Home Assistant.
+The `local_file` camera can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodically and will then be displayed in Home Assistant.
 
 To enable this camera in your installation, add the following to your `configuration.yaml` file:
 
@@ -31,7 +31,11 @@ Configuration variables:
  - **file_path** (*Required*): File to serve as the camera.
  - **name** (*Optional*): Name of the camera
 
-<p class='note'>
-The given `file_path` must be an existing file because the camera platform setup make a readable check on it.
-</p>
+### {% linkable_title Service `camera.local_file_update_file_path` %}
 
+Use this service to change the file displayed by the camera.
+
+| Service data attribute | Description |
+| -----------------------| ----------- |
+| `entity_id` | String of the `entity_id` of the camera to update. |
+| `file_path` | The full path to the new image file to be displayed. |

source/_components/camera.yi.markdown

@@ -34,6 +34,10 @@ Once installed, please ensure that you have enabled FTP and Telnet on your devic
 Currently, version 0.1.4-beta2 of the custom firmware is the highest supported. Firmwares higher than this version use [Pure-FTPd](https://www.pureftpd.org/project/pure-ftpd), which has a bug that prevents FFmpeg from correctly rendering video files.
 </p>
 
+<p class='note warning'>
+Hassbian users: don't forget to install ffmpeg support on your platform, otherwise, you'll not see video.
+</p>
+
 <p class='note warning'>
 Some alternative Yi firmwares enable an experimental RTSP server, which will allow you to connect to your camera via other Home Assistant camera platforms. However, this RTSP server disables the ability to use the supremely-useful Yi Home app. In order to maintain both Home Assistant compatibility _and_ the native app, this platform retrieves videos via FTP.
 </p>

source/_components/climate.fritzbox.markdown

@@ -0,0 +1,28 @@
+---
+layout: page
+title: "Fritzbox Thermostat"
+description: "Instructions on how to integrate the AVM Fritzbox thermostat."
+date: 2017-11-12 17:10
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: avm.png
+ha_category: Climate
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+<p class='note'>
+To get AVM fritzbox thermostat follow the instructions for the general [Fritzbox](/components/fritzbox/).
+</p>
+
+### {% linkable_title Attributes %}
+
+The are several attributes that can be useful for automations and templates.
+
+| Attribute | Description |
+| --------- | ----------- |
+| `device_locked` | The state of the key lock at the device.
+| `locked` | The state of the lock for configuring the device via the app or the Fritzbox web interface.
+| `low_battery` | The low battery state indication.

source/_components/climate.hive.markdown

@@ -14,13 +14,15 @@ ha_iot_class: "Cloud Polling"
 ---
 
 
-The 'hive' climate component integrates your Hive thermostat and hot water into Home Assistant, enabling control of setting the **mode** and setting the **target temperature**.
+The `hive` climate platform integrates your Hive thermostat and hot water into Home Assistant, enabling control of setting the **mode** and setting the **target temperature**.
+
 A short boost for Hive Heating or Hive Hot water can be set by using the **Aux Heat** function, this will turn on the boost feature for Hive Heating or Hive Hot water for 30 minutes at 0.5 degrees higher than the current temperature.
 
-The Hive climate component supports the following Hive products:
-- **Hive Active Heating**
-- **Hive Multizone**
-- **Hot water control**
+The platform supports the following Hive products:
+
+- Hive Active Heating
+- Hive Multizone
+- Hot water control
 
 
 <p class='note'>

source/_components/climate.modbus.markdown

@@ -0,0 +1,71 @@
+---
+layout: page
+title: "Modbus"
+description: "Instructions how to integrate a Modbus thermostat within Home Assistant."
+date: 2018-01-29 9:35
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: modbus.png
+ha_category: Thermostat
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+
+The `modbus` thermostat allows you to use a sensor value (current temperature) and target value (target temperature) from [Modbus](http://www.modbus.org/) registers.
+
+## {% linkable_title Configuration %}
+
+To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+climate:
+  - platform: modbus
+    name: Watlow F4T
+    slave: 1
+    target_temp_register: 2782
+    current_temp_register: 27586
+```
+
+{% configuration %}
+name:
+  description: Name of the device
+  required: true
+  type: string
+slave:
+  description: The number of the slave (Optional for tcp and upd Modbus, use 1).
+  required: true
+  type: int
+target_temp_register:
+  description: Register number for target temperature (Setpoint).
+  required: true
+  type: int
+current_temp_register:
+  description: Register number for current temperature (Process value).
+  required: true
+  type: int
+data_type:
+  description: Response representation (int, uint, float, custom). If float selected, value will converted to IEEE 754 floating point format.
+  required: false
+  type: string
+  default: float
+count:
+  description: Number of registers to read.
+  required: false
+  type: int
+precision:
+  description: Number of valid decimals.
+  required: false
+  type: int
+  default: 0
+{% endconfiguration %}
+
+
+### {% linkable_title Services %}
+
+| Service | Description |
+| ------- | ----------- |
+| set_temperature | Set Temperature. Requires `value` to be passed in, which is the desired target temperature. `value` should be in the same type as `data_type` |

source/_components/conversation.markdown

@@ -87,3 +87,9 @@ intent_script:
           - "{% if color == 'blue' %}255{% else %}0{% endif %}"
 {% endraw %}
 ```
+
+#### {% linkable_title Service `conversation.process` %}
+
+| Service data attribute | Optional | Description                                      |
+|------------------------|----------|--------------------------------------------------|
+| `text`                 |      yes | Transcribed text                                 |

source/_components/cover.gogogate2.markdown

@@ -0,0 +1,49 @@
+---
+layout: page
+title: "Gogogate2 Cover"
+description: "Instructions on how to integrate Gogogate2-Enabled garage door covers into Home Assistant."
+date: 2018-03-26 20:02
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: gogogate2.png
+ha_category: Cover
+ha_release: 0.67
+ha_iot_class: Local Polling
+---
+
+The `gogogate2` cover platform lets you control Gogogate2-Enabled garage doors through Home Assistant. Device names in Home Assistant are generated based on the names defined in your Gogogate2 mobile app.
+
+## {% linkable_title Configuration %}
+
+To use your Gogogate2 cover in your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+cover:
+  - platform: gogogate2
+    username: email@email.com
+    password: password
+    ip_address: 192.168.1.200
+```
+
+{% configuration %}
+username:
+  description: Your Gogogate2 account username.
+  required: true
+  type: string
+password:
+  description: Your Gogogate2 account password.
+  required: true
+  type: string
+ip_address:
+  description: The IP Address of your Gogogate2 device.
+  required: true
+  type: string
+name:
+  description: Allows you to override the default name.
+  default: gogogate2
+  required: false
+  type: string
+{% endconfiguration %}

source/_components/cover.mqtt.markdown

@@ -15,6 +15,8 @@ ha_release: 0.18
 
 The `mqtt` cover platform allows you to control an MQTT cover (such as blinds, a rollershutter, or a garage door).
 
+## {% linkable_title Configuration %}
+
 The device state (`open` or `closed`) will be updated only after a new message is published on `state_topic` matching `state_open` or `state_closed`. If these messages are published with the `retain` flag set, the cover will receive an instant state update after subscription and Home Assistant will display the correct state on startup. Otherwise, the initial state displayed in Home Assistant will be `unknown`.
 
 There is an attribute that stores the relative position of the device, where 0 means the device is `closed` and all other intermediate positions means the device is `open`.
@@ -164,7 +166,7 @@ In this section you will find some real life examples of how to use this platfor
 The example below shows a full configuration for a cover without tilt.
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 cover:
   - platform: mqtt
     name: "MQTT Cover"
@@ -188,8 +190,9 @@ cover:
 
 The example below shows a full configuration for a cover.
 
+{% raw %}
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 cover:
   - platform: mqtt
     name: "MQTT Cover"
@@ -206,7 +209,7 @@ cover:
     payload_available: "online"
     payload_not_available: "offline"
     optimistic: false
-    value_template: '{% raw %}{{ value.x }}{% endraw %}'
+    value_template: '{{ value.x }}'
     tilt_command_topic: 'home-assistant/cover/tilt'
     tilt_status_topic: 'home-assistant/cover/tilt-state'
     tilt_min: 0
@@ -214,6 +217,7 @@ cover:
     tilt_closed_value: 70
     tilt_opened_value: 180
 ```
+{% endraw %}
 
 To test, you can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. This allows you to operate your cover manually:
 

source/_components/cover.myq.markdown

@@ -15,10 +15,12 @@ ha_iot_class: Cloud Polling
 
 The `myq` cover platform lets you control MyQ-Enabled garage doors through Home Assistant. Device names in Home Assistant are generated based on the names defined in your MyQ Device mobile app.
 
+## {% linkable_title Configuration %}
+
 To use your MyQ cover in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 cover:
   - platform: myq
     username: YOUR_USERNAME

source/_components/cover.wink.markdown

@@ -13,24 +13,20 @@ ha_release: 0.13
 ha_iot_class: "Cloud Polling"
 ---
 
-Wink cover/garage door functionality depends on the product you're using.  With GoControl/Linear Home Assistant can open, close, and view state.  Chamberlain is currently limited to view only.  Meaning Home Assistant will only show the current state of the door and control has been disabled (by Chamberlain).  If you have a Chamberlain garage door, and would like to control it via Home Assistant, please contact Chamberlain and request that they re-enabled third-party control.
+Wink Cover garage door functionality varies on the product. Home Assistant can open, close, and view state of GoControl/Linear openers. For Chamberlain MyQ-enabled openers, Home Assistant is limited to show current state (open or closed) only using this Wink cover. This restriction was imposed by Chamberlain for third party control. Wink suggests that MyQ customers should contact Chamberlain directly to inquire about expanding permissions.
 
-The following quote is from Wink.
-
-> As part of our agreement with Chamberlain, third-party access to control Chamberlain garage doors has been restricted. Please contact Chamberlain directly to inquire about permissions.
+The [MyQ Cover](/components/cover.myq/) does provide full functionality for opening and closing Chamberlain MyQ-enabled garage doors. If installed along with the Wink Component, a duplicate garage door entity may exist. In that case, the semi-functional Wink garage door entity can be hidden via customize.yaml.
 
 The requirement is that you have setup [Wink](/components/wink/).
 
-
 ### {% linkable_title Supported cover devices %}
 
 - Bali window treatments
 - Lutron shades
 - Pella motorized blinds and shades
 - GoControl garage door opener
-- Chamberlain (Limited functionality) (No Wink hub required)
+- Chamberlain MyQ (Limited functionality) (No Wink hub required)
 
 <p class='note'>
 The above devices are confirmed to work, but others may work as well.
 </p>
-

source/_components/deconz.markdown

@@ -34,7 +34,7 @@ ha_iot_class: "Local Push"
 
 Home Assistant will automatically discover deCONZ presence on your network, if `discovery:` is present in your `configuration.yaml` file.
 
-If you don't have the API key, you can generate an API key for deCONZ by using the one-click functionality similar to Philips Hue. Go to **Menu** -> **Settings** -> **Unlock Gateway** in deCONZ and then use the deCONZ configurator in Home Assistant frontend to create an API key. When you've generated the API key from Home Assistant, the API key will be stored in `deconz.conf` inside the `.homeassistant` folder.
+If you don't have the API key, you can generate an API key for deCONZ by using the one-click functionality similar to Philips Hue. Go to **Menu** -> **Settings** -> **Unlock Gateway** in deCONZ and then use the deCONZ configurator in Home Assistant frontend to create an API key. When you've generated the API key from Home Assistant, the API key will be stored in `.config_entries.json` inside the `.homeassistant` folder.
 
 You can add the following to your configuration.yaml file if you are not using the `discovery:` component:
 

source/_components/device_tracker.asuswrt.markdown

@@ -19,6 +19,8 @@ The `asuswrt` platform offers presence detection by looking at connected devices
 This platform is **NOT** available for [Microsoft Windows installations](http://pexpect.readthedocs.io/en/stable/overview.html#pexpect-on-windows).
 </p>
 
+### {% linkable_title Configuration %}
+
 To use an ASUSWRT router in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
@@ -29,15 +31,44 @@ device_tracker:
     username: YOUR_ADMIN_USERNAME
 ```
 
-Configuration variables:
-
-- **host** (*Required*): The IP address of your router, eg. `192.168.1.1`.
-- **username** (*Required*: The username of an user with administrative privileges, usually `admin`.
-- **password** (*Optional*): The password for your given admin account (use this if no SSH key is given).
-- **protocol** (*Optional*): The protocol (`ssh` or `telnet`) to use. Defaults to `ssh`.
-- **port** (*Optional*): SSH port to use. Defaults to `22`.
-- **mode** (*Optional*): The operating mode of the router (`router` or `ap`). Defaults to `router`.
-- **ssh_key** (*Optional*): The path to your SSH private key file associated with your given admin account (instead of password).
+{% configuration %}
+host:
+  description: "The IP address of your router, eg. `192.168.1.1`."
+  required: true
+  type: string
+username:
+  description: "The username of an user with administrative privileges, usually `admin`."
+  required: true
+  type: string
+password:
+  description: "The password for your given admin account (use this if no SSH key is given)."
+  required: false
+  type: string
+protocol:
+  description: "The protocol (`ssh` or `telnet`) to use."
+  required: false
+  type: string
+  default: ssh
+port:
+  description: SSH port to use.
+  required: false
+  type: int
+  default: 22
+mode:
+  description: "The operating mode of the router (`router` or `ap`)."
+  required: false
+  type: string
+  default: router
+ssh_key:
+  description: The path to your SSH private key file associated with your given admin account (instead of password).
+  required: false
+  type: string
+require_ip:
+  description: If the router is in access point mode.
+  required: false
+  type: boolean
+  default: true
+{% endconfiguration %}
 
 <p class='note warning'>
 You need to [enable telnet](https://www.asus.com/support/faq/1005449/) on your router if you choose to use `protocol: telnet`. 

source/_components/device_tracker.bluetooth_tracker.markdown

@@ -27,6 +27,14 @@ device_tracker:
   - platform: bluetooth_tracker
 ```
 
+{% configuration %}
+request_rssi:
+  description: Performs a request for the "Received signal strength indication" (RSSI) of each tracked device
+  required: false
+  type: boolean
+  default: False
+{% endconfiguration %}
+
 In some cases it can be that your device is not discovered. In that case let your phone scan for Bluetooth devices while you restart Home Assistant. Just hit `Scan` on your phone all the time until Home Assistant is fully restarted and the device should appear in `known_devices.yaml`.
 
 For additional configuration variables check the [Device tracker page](/components/device_tracker/).

source/_components/device_tracker.bmw_connected_drive.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
-title: "BMW connected drive"
-description: "Instructions on how to setup your BMW connected drive account with Home Assistant."
+title: "BMW Connected Drive Device Tracker"
+description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant."
 date: 2018-01-10 23:00
 sidebar: true
 comments: false

source/_components/device_tracker.fritz.markdown

@@ -15,6 +15,8 @@ ha_release: "0.10"
 
 The `fritz` platform offers presence detection by looking at connected devices to a [AVM Fritz!Box](http://avm.de/produkte/fritzbox/) based router.
 
+## {% linkable_title Configuration %}
+
 <p class='note warning'>
 It might be necessary to install additional packages: <code>$ sudo apt-get install libxslt-dev libxml2-dev python3-lxml</code>
 If you are working with the All-in-One installation, you may also need to execute also within your virtual environment the command <code> pip install lxml</code>; be patient this will take a while.</p>

source/_components/device_tracker.google_maps.markdown

@@ -0,0 +1,46 @@
+---
+layout: page
+title: "Google Maps Location Sharing"
+description: "Instructions how to use Google Maps Location Sharing to track devices in Home Assistant."
+date: 2017-02-12 10:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: google_maps.png
+ha_release: 0.67
+ha_category: Presence Detection
+ha_iot_class: "Cloud Polling"
+---
+
+The `google_maps` platform allows you to detect presence using the unofficial API of [Google Maps Location Sharing](https://myaccount.google.com/locationsharing). 
+
+You first need to create an additional Google account and share your location with that account. This platform will use that account to fetch the location of your device(s). You have to setup sharing through the Google Maps app on your mobile phone. You can find more information [here](https://support.google.com/accounts?p=location_sharing).
+
+This platform will create a file named `google_maps_location_sharing.conf` where it caches your login session.
+
+<p class='note warning'>
+Since this platform is using an unofficial API with the help of [locationsharinglib](https://github.com/costastf/locationsharinglib), Google seems to block access to your data the first time you've logged in with this component.
+This issue can be fixed by logging in with your new account and approving your login on the [Device Activity](https://myaccount.google.com/device-activity) page.
+</p>
+
+To integrate Google Maps Location Sharing in Home Assistant, add the following section to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+device_tracker:
+  - platform: google_maps
+    username: YOUR_USERNAME
+    password: YOUR_PASSWORD
+```
+
+{% configuration %}
+username:
+  description: The email address for the Google account that has access to your shared location.
+  required: true
+  type: string
+password:
+  description: The password for your given username.
+  required: true
+  type: string
+{% endconfiguration %}

source/_components/device_tracker.icloud.markdown

@@ -33,9 +33,11 @@ Configuration variables:
 - **username** (*Required*): The username for the iCloud account.
 - **password** (*Required*): The password for your given username.
 - **account_name** (*Optional*): The friendly name for the account_name. If this isn't given, it will use the account_name of the username (so the part before the `@` in the email address).
+- **max_interval** (*Optional*): Maximum interval in minutes between subsequent location upates. This tracker uses dynamic intervals for requesting location updates. When iphone is stationary, interval will eventually be set to `max_interval` to save battery. When iphone starts moving again interval will be dynamically updated to 1 min. Note that updating interval to 1 min might be delayed by maximum `max_interval` minutes. Default is 30 min. Minimum value is 1 min.
+- **gps_accuracy_threshold** (*Optional*): iCloud location updates come with some gps_accuracy varying from 10 to 5000 meters. This setting defines the accuracy threshold in meters for a location update. Less accurate updates will be discarded by this tracker. This allows more precise location monitoring and fewer false positive zone changes. Default is 1000 meters.
 
 <p class='note warning'>
-This may cause battery drainage as it wakes up your device to get the current location.
+Low `max_interval` may cause battery drainage as it wakes up your device to get the current location.
 </p>
 
 <p class='note warning'>
@@ -48,7 +50,7 @@ To disable the drainage of the battery, a dynamic interval is being used for eac
 2 Factor Authentication is the improved version of 2 Steps Authentication, this is still not supported by the pyicloud library. Therefore it's not possible to use it with the device_tracker yet.
 
 4 services are available for this component:
-- **icloud_update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional.
+- **icloud_update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional. Request will result in new Home Assistant [state_changed](/docs/configuration/events/#event-state_changed) event describing current iphone location. Can be used in automations when manual location update is needed, e.g. to check if anyone is home when door's been opened.
 - **icloud_lost_iphone**: This service will play the Lost iPhone sound on a certain iDevice. The `account_name` and `device_name` are optional.
 - **icloud_set_interval**: This service will change the dynamic interval of an iDevice. The `account_name` and `device_name` are optional. If `interval` is used in the service_data, the iDevice will be updated with that new interval. That interval will be fixed until the iDevice changes zone or if this service is called again. If `interval` isn't used in the service_data, the interval for that iDevice will revert back to its default dynamic interval based on its current zone, its distance towards home and its battery level.
 - **icloud_reset_account**: This service can be used to reset an iCloud account. This is helpful when not all devices are being found by the component or if you have added a new iDevice to your account. The `account_name` is optional.

source/_components/device_tracker.markdown

@@ -40,6 +40,10 @@ The following optional parameters can be used with any platform. However device
 | `consider_home`      | 180     | Seconds to wait till marking someone as not home after not being seen. This parameter is most useful for households with Apple iOS devices that go into sleep mode while still at home to conserve battery life. iPhones will occasionally drop off the network and then re-appear. `consider_home` helps prevent false alarms in presence detection when using IP scanners such as Nmap. `consider_home` accepts various time representations, (e.g., the following all represents 3 minutes: `180`, `0:03`, `0:03:00`)  |
 | `new_device_defaults`|         | Default values for new discovered devices. Available options `track_new_devices` (default: `True`), `hide_if_away` (default: `False`)                                                                                                                                                                                                                                                     |
 
+<p class='note'>
+  Note that setting `track_new_devices: False` will still result in new devices being recorded in `known_devices.yaml`, but they won't be tracked (`track: no`).
+</p>
+
 The extended example from above would look like the following sample:
 
 ```yaml

source/_components/device_tracker.meraki.markdown

@@ -11,8 +11,21 @@ logo: meraki.png
 ha_category: Presence Detection
 ha_release: "0.60"
 ---
-Use your `Meraki AP` as device tracker. Note that Meraki will see all devices, not only connected to the network.
-Follow instructions [here](https://meraki.cisco.com/technologies/location-analytics-api) how to enable Location Analytics. 
+
+Use your Meraki AP as device tracker. Note that Meraki will see all devices, not only connected to the network.
+
+### {% linkable_title Prerequisites %}
+
+1. Go to Network-wide/General page, and find the Location and scanning section.
+1. Make sure analytics and Scanning API are both enabled.
+1. Make note of the Validator string, which will be used in the `device_tracker` configuration.
+1. Click **Add a Post URL**:
+  1. Set the Post URL to `https://YOUR_HOSTNAME/api/meraki?api_password=YOUR_HASS_PASSWORD`
+  1. Set the Secret to a randomly generated string, and make note of it for the `device_tracker` configuration.
+  1. Make sure the API Version is set to `2.0`.
+  1. Hit **Save** in the bottom right of the page.
+
+## {% linkable_title Configuration %}
 
 After you configure access to the Meraki CMX API, add the following to your `configuration.yaml` file:
 
@@ -24,14 +37,13 @@ device_tracker:
     validator: meraki_validator
 ```
 
-
 {% configuration %}
   secret:
-    description: Secret code added in Meraki
+    description: Secret code added in Meraki.
     required: true
     type: string
   validator:
-    description: Validation string from Meraki
+    description: Validation string from Meraki.
     required: true
     type: string
 {% endconfiguration %}

source/_components/device_tracker.netgear.markdown

@@ -13,7 +13,6 @@ ha_iot_class: "Local Polling"
 ha_release: pre 0.7
 ---
 
-
 This platform allows you to detect presence by looking at connected devices to a [Netgear](http://www.netgear.com/) device.
 
 To use this device tracker in your installation, add the following to your `configuration.yaml` file:
@@ -29,10 +28,18 @@ device_tracker:
 
 Configuration variables:
 
-- **host** (*Optional*): The IP address of your router, e.g., `192.168.1.1`. If not provided `routerlogin.net` will be used.
-- **username** (*Optional*): The username of an user with administrative privileges. If not provided `admin` will be used.
-- **port** (*Optional*): The port your router communicates with (defaults to `5000`, but `80` is also known to be used on some models).
+- **url** (*Optional*): The base URL, e.g., `http://routerlogin.com:5000` for example. If not provided `host` and `port` are used. If none provided autodetection of the URL will be used.
+- **host** (*Optional*): The IP address of your router, e.g., `192.168.1.1`.
+- **port** (*Optional*): The port your router communicates with.
+- **username** (*Optional*): The username of a user with administrative privileges. If not provided `admin` will be used.
 - **password** (*Required*): The password for your given admin account.
+- **devices** (*Optional*): If provided only specified devices will be reported. Can be MAC address or the device name as reported in the Netgear UI.
+- **exclude** (*Optional*): Devices to exclude from the scan.
+- **accesspoints** (*Optional*): Also track devices on the specified APs. Only supports MAC address.
+
+When `accesspoints` is specified an extra device will be reported for each device connected to the APs specified here, as `MY-LAPTOP on RBS40`. `Router` will be reported as AP name for the main AP. Only tested with Orbi.
+
+The use of `devices` or `exclude` is recommended when using `accesspoints` to avoid having a lot of entries.
 
 List of models that are known to use port 80:
 - Nighthawk X4S - AC2600 (R7800)

source/_components/device_tracker.owntracks_http.markdown

@@ -32,5 +32,21 @@ Open OwnTracks and go to Connection preferences:
  - Mode: Select **Private HTTP**
  - Host: [Home Assistant URL]:[port]/api/owntracks/[your name]/[device name]
  - Identification: Turn **Authentication** on, username `homeassistant` and password is your API password that you use to login to Home Assistant.
- 
+
 Host example: If I host my Home Assistant at `https://example.duckdns.org`, my name is Paulus and my phone is a Pixel I would set the host to be `https://example.duckdns.org/api/owntracks/paulus/pixel`. This will result in an entity with an ID of `device_tracker.paulus_pixel`. You can pick any name for the user and the device.
+
+Since the battery data is available as an attribute of the device tracker entity, it can be tracked with a [`template` sensor](/components/sensor.template/).
+
+{% raw %}
+```yaml
+# Example configuration.yaml entry
+sensor:
+  - platform: template
+    sensors:
+      pixel_battery:
+        friendly_name: Pixel of Paulus
+        unit_of_measurement: "%"
+        value_template: '{{ states.device_tracker.paulus_pixel.attributes.battery|int }}'
+        device_class: battery
+```
+{% endraw %}

source/_components/device_tracker.tplink.markdown

@@ -41,7 +41,7 @@ For Archer C9 models running firmware version 150811 or later please use the enc
 2. Type in the password you use to login into the password field.
 3. Click somewhere else on the page so that the password field is not selected anymore.
 4. Open the JavaScript console of your browser (usually by pressing F12 and then clicking on "Console").
-5. Type ```document.getElementById("login-password").value;```.
+5. Type `document.getElementById("login-password").value;` or `document.getElementById("pcPassword").value;`, depending on your firmware version.
 6. Copy the returned value to your Home Assistant configuration as password.
 
 See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.

source/_components/device_tracker.unifi.markdown

@@ -80,7 +80,7 @@ The Unifi controller allows you to create multiple users on it besides the main
 
 The Unifi controller can either be a dedicated hardware device (Unifi's cloud key), or as software any Linux system. If you run the the Unifi controller on the same operating system as Home Assistant there may be conflicts in ports if you have the MQTT component as well.
 
-It is recommended that you run the Unifi controller in a dedicate virtual machine to avoid that situation.
+It is recommended that you run the Unifi controller in a dedicated virtual machine to avoid that situation.
 
 ### {% linkable_title Troubleshooting and Time Synchronization %}
 

source/_components/device_tracker.xiaomi_miio.markdown

@@ -0,0 +1,38 @@
+---
+layout: page
+title: "Xiaomi Mi WiFi Repeater 2"
+description: "Instructions how to integrate your Xiaomi Mi WiFi Repeater 2 within Home Assistant."
+date: 2018-04-01 21:06
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: xiaomi.png
+ha_category: Presence Detection
+ha_version: 0.67
+ha_iot_class: "Local Polling"
+---
+
+The `xiaomi_miio` device tracker platform is observing your Xiaomi Mi WiFi Repeater 2 and reporting all associated WiFi clients.
+
+Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token.
+
+To add a Xiaomi Mi Air Quality Monitor to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+device_tracker:
+  - platform: xiaomi_miio
+    host: 192.168.130.73
+    token: YOUR_TOKEN
+```
+
+{% configuration %}
+host:
+  description: The IP address of your miio device.
+  required: true
+  type: string
+token:
+  description: The API token of your miio device.
+  required: true
+  type: string
+{% endconfiguration %}

source/_components/discoverable.markdown

@@ -23,7 +23,7 @@ for state in hass.states():
 To enable `discovery` in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 discoverable:
   expose_password: yes
 ```

source/_components/discovery.markdown

@@ -23,6 +23,7 @@ Home Assistant can discover and automatically configure [zeroconf](https://en.wi
  * [DirecTV receivers](/components/media_player.directv/)
  * [Frontier Silicon internet radios](/components/media_player.frontier_silicon/)
  * [Google Cast](/components/media_player.cast/)
+ * [HomeKit](/components/homekit_controller/)
  * [IKEA Trådfri (Tradfri)](/components/tradfri/)
  * [Linn / Openhome](/components/media_player.openhome/)
  * [Logitech Harmony Hub](/components/remote.harmony/)
@@ -50,6 +51,8 @@ discovery:
   ignore:
     - sonos
     - samsung_tv
+  enable:
+    - homekit
 ```
 
 Configuration variables:
@@ -85,6 +88,12 @@ Valid values for ignore are:
  * `yamaha`: Yamaha media player
  * `yeelight`: Yeelight Sunflower bulb
 
+- **enable** (*Optional*): A list of platforms not enabled by default that `discovery` should discover.
+
+Valid values for enable are:
+
+ * `homekit`: HomeKit accessories
+
 <p class='note'>
 Home Assistant must be on the same network as the devices for uPnP discovery to work.
 If running Home Assistant in a [Docker container](/docs/installation/docker/) use switch `--net=host` to put it on the host's network.

source/_components/doorbird.markdown

@@ -20,9 +20,10 @@ To connect your device, add the following to your `configuration.yaml` file:
 ```yaml
 # Example configuration.yaml entry
 doorbird:
-  host: IP_OR_HOSTNAME
+  host: DOORBIRD_IP_OR_HOSTNAME
   username: YOUR_USERNAME
   password: YOUR_PASSWORD
+  hass_url_override: HASS_IP
 ```
 
 Configuration variables:
@@ -31,7 +32,77 @@ Configuration variables:
 - **username** (*Required*): The username of a non-administrator user account on the device.
 - **password** (*Required*): The password for the user specified.
 - **doorbell_events** (*Optional*): Setting this to `true` this will register a callback URL with the device so that events can be published to the event bus when the doorbell rings.
+- **hass_url_override** (*Optional*): If your DoorBird cannot connect to the machine running Home Assistant because you are using dynamic DNS or some other HTTP configuration (such as HTTPS), specify the LAN IP of the machine here to force a LAN connection.
 
 <p class="note warning">
 Enabling `doorbell_events` will delete all other registered push notification services with the device every time Home Assistant starts. This will not affect notifications delivered by the DoorBird mobile app.
 </p>
+
+### Doorbell Sound Examples
+
+You can create an automation that triggers on event `doorbird_doorbell` to play a doorbell sound when the Doorbird button is pressed. This should work with any media player.
+
+#### Example using SONOS
+
+[`SONOS`](http://www.sonos.com) players have features allowing for "snapshotting" the current state of some or all players so those state(s) can be "restored" at a later time. This feature is perfect for implementing a doorbell sound (from Doorbird or any other Doorbell setup for that matter). The [`media_player.sonos`](/components/media_player.sonos/) platform includes the [`SONOS_SNAPSHOT`](/components/media_player.sonos/#service-sonos_snapshot) and [`SONOS_RESTORE`](/components/media_player.sonos/#service-sonos_restore) features. The result of not using these features is any currently playing songs or media will not continue playing after the doorbell sound has played and you will be left with the doorbell sound queued as the last played song. This setup allows for seamless ringing of the doorbell and all SONOS devices continuing nicely on as if nothing had happened.
+
+The example script below takes a snapshot of three SONOS players that are not currently grouped together, joins the three players in a group (so the sound plays at the same time on all players), plays the doorbell MP3 sound, unjoins the players from the group and finally restores the players to their original state. When the players are grouped they are controlled by refering to the `master`.
+
+Automation file:
+
+```yaml
+- alias: Doorbird ring
+  trigger:
+    platform: event
+    event_type: doorbird_doorbell
+  action:
+    service: script.turn_on
+      entity_id: script.doorbell
+```
+
+Script file:
+
+```yaml
+doorbell:
+  alias: Ring Doorbell
+  sequence:
+    - service: media_player.sonos_snapshot
+      data:
+        entity_id:
+          - media_player.kitchen
+          - media_player.master_bedroom
+          - media_player.study
+    - service: media_player.sonos_join
+      data:
+        master: media_player.study
+        entity_id:
+          - media_player.kitchen
+          - media_player.master_bedroom
+          - media_player.study
+    - service: media_player.play_media
+      data:
+        entity_id: media_player.study   # the group master
+        media_content_id: http://10.1.1.10/sounds/doorbell.mp3   # this is on a NAS but could be HASS local
+        media_content_type: music
+    - service: media_player.volume_set
+      data:
+        entity_id:   # can still control the volume of grouped players indivdually
+          - media_player.study
+          - media_player.kitchen
+          - media_player.master_bedrom
+        volume_level: 0.50
+    - delay:
+        seconds: 4   # wait while the sound plays
+    - service: media_player.sonos_unjoin
+      data:
+        entity_id:
+          - media_player.kitchen
+          - media_player.master_bedroom
+          - media_player.study
+    - service: media_player.sonos_restore
+      data:
+        entity_id:
+          - media_player.kitchen
+          - media_player.master_bedroom
+          - media_player.study
+```

source/_components/dyson.markdown

@@ -26,9 +26,9 @@ dyson:
   password: YOUR_DYSON_PASSWORD
   language: YOUR_DYSON_ACCOUNT_LANGUGAGE
   devices:
-    - device_id: DEVICE_ID_1 # eg: Pure Cool Link device
+    - device_id: DEVICE_ID_1 # eg. Serial number: XXX-XX-XXXXXXXX
       device_ip: DEVICE_ID_1
-    - device_id: DEVICE_ID_2 # eg: Eye 360 robot vacuum
+    - device_id: DEVICE_ID_2
       device_ip: DEVICE_ID_2
 ```
 
@@ -38,7 +38,7 @@ Configuration variables:
 - **password** (*Required*): Dyson account password.
 - **language** (*Required*): Dyson account language country code. Known working codes: `FR`, `NL`, `GB`, `AU`. But others codes should work.
 - **devices** (*Optional*): List of devices.
-  - **device_id** (*Required*): Device ID. Available in the mobiles applications (*Settings* page).
+  - **device_id** (*Required*): Device ID. The Serial Number of the device. Found in the mobiles applications device settings page.
   - **device_ip** (*Required*): Device IP address.
 
 `devices` list is optional but you'll have to provide them if discovery is not working (warnings in the logs and the devices are not available in Home Assistant web interface).

source/_components/eufy.markdown

@@ -0,0 +1,54 @@
+---
+layout: page
+title: "Eufy"
+description: "Instructions on how to integrate Eufy devices into Home Assistant."
+date: 2018-04-09 19:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: eufy.png
+ha_category: Hub
+ha_release: 0.68
+---
+
+The `eufy` component is the main component to integrate various [eufy](https://www.eufylife.com/) devices with Home Assistant.
+
+Supported devices will be discovered after the `eufy` component is configured:
+
+```yaml
+# Example configuration.yaml entry
+eufy:
+  username: testuser@domain
+  password: p4ssw0rd
+```
+
+where username and password are the ones configured in the EufyHome app. Alternately, Eufy devices that are not discoverable can be statically configured.
+
+```yaml
+eufy:
+  devices:
+    - address: 192.168.1.10
+      access_token: 1234567890abcdef
+      type: T1012
+      name: Smart Light
+    - address: 192.168.1.11
+      access_token: abcdef1234567890
+      type: T1201
+      name: Smart Switch
+```
+
+access_token can be obtained by running:
+
+```
+curl -H "Content-Type: application/json" -d '{"client_id":"eufyhome-app", "client_Secret":"GQCpr9dSp3uQpsOMgJ4xQ", "email":"USERNAME", "password":"PASSWORD"}' https://home-api.eufylife.com/v1/user/email/login | jq
+```
+
+replacing USERNAME and PASSWORD with the Eufy username and password. This will give an access_token. Then run:
+
+```
+curl -H token:TOKEN -H category:Home https://home-api.eufylife.com/v1/device/list/devices-and-groups | jq
+```
+
+replacing TOKEN with the access_token from the previous command. This will provide the local_code for each device.
+

source/_components/fan.mqtt.markdown

@@ -15,6 +15,8 @@ ha_iot_class: depends
 
 The `mqtt` fan platform lets you control your MQTT enabled fans.
 
+## {% linkable_title Configuration %}
+
 In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT fan will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the fan will be `false` / `off`.
 
 When a `state_topic` is not available, the fan will work in optimistic mode. In this mode, the fan will immediately change state after every command. Otherwise, the fan will wait for state confirmation from the device (message from `state_topic`).
@@ -24,7 +26,7 @@ Optimistic mode can be forced even if a `state_topic` is available. Try to enabl
 To enable MQTT fans in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 fan:
   - platform: mqtt
     command_topic: "bedroom_fan/on/set"
@@ -155,7 +157,7 @@ In this section you find some real life examples of how to use this fan.
 The example below shows a full configuration for a MQTT fan.
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 fan:
   - platform: mqtt
     name: "Bedroom Fan"

source/_components/fan.template.markdown

@@ -0,0 +1,96 @@
+---
+layout: page
+title: "Template Fan"
+description: "Instructions how to setup the Template fans within Home Assistant."
+date: 2018-05-03 09:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_category: Fan
+ha_release: 0.69
+ha_iot_class: "Local Push"
+logo: home-assistant.png
+---
+
+The `template` platform creates fans that combine components and provides the
+ability to run scripts or invoke services for each of the turn_on, turn_off, set_speed, and
+set_oscillating commands of a fan.
+
+To enable Template Fans in your installation, add the following to your
+`configuration.yaml` file:
+
+{% raw %}
+```yaml
+# Example configuration.yaml entry
+fan:
+  - platform: template
+    fans:
+      bedroom_fan:
+        friendly_name: "Bedroom fan"
+        value_template: "{{ states('input_boolean.state') }}"
+        speed_template: "{{ states('input_select.speed') }}"
+        oscillating_template: "{{ states('input_select.osc') }}"
+        turn_on:
+          service: script.fan_on
+        turn_off:
+          service: script.fan_off
+        set_speed:
+          service: script.fan_speed
+          data_template:
+            speed: "{{ speed }}"
+        set_oscillating:
+          service: script.fan_oscillating
+          data_template:
+            oscillating: "{{ oscillating }}"
+        speeds:
+          - '1'
+          - '2'
+          - '3'
+```
+{% endraw %}
+
+{% configuration %}
+  fans:
+    description: List of your fans.
+    required: true
+    type: map
+    keys:
+      friendly_name:
+        description: Name to use in the frontend.
+        required: false
+        type: string
+      value_template:
+        description: "Defines a template to get the state of the fan. Valid value: 'on'/'off'"
+        required: true
+        type: template
+      speed_template:
+        description: Defines a template to get the speed of the fan.
+        required: false
+        type: template
+      oscillating_template:
+        description: "Defines a template to get the osc state of the fan. Valid value: True/False"
+        required: false
+        type: template
+      turn_on:
+        description: Defines an action to run when the fan is turned on.
+        required: true
+        type: action
+      turn_off:
+        description: Defines an action to run when the fan is turned off.
+        required: true
+        type: action
+      set_speed:
+        description: Defines an action to run when the fan is given a speed command.
+        required: false
+        type: action
+      set_oscillating:
+        description: Defines an action to run when the fan is given a osc state command.
+        required: false
+        type: action
+      speeds:
+        description: List of speeds the fan is capable of running at.
+        required: false
+        type: string list
+        default: ['low', 'medium', 'high']
+{% endconfiguration %}

source/_components/fan.xiaomi_miio.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
 title: "Xiaomi Air Purifier"
-description: "Instructions on how to integrate your Xiaomi Air Purifier within Home Assistant."
+description: "Instructions on how to integrate your Xiaomi Air Purifier and Xiaomi Air Humidifier within Home Assistant."
 date: 2017-10-13 12:35
 sidebar: true
 comments: false
@@ -13,35 +13,161 @@ ha_version: 0.57
 ha_iot_class: "Local Polling"
 ---
 
-The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier 2, Air Purifier 2S and Air Purifier Pro.
+The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier and Xiaomi Air Humidifier.
 
-Currently, the supported features are:
+## Features
 
-* On, Off
+### Air Purifier 2 et al.
+
+* Power (on, off)
 * Operation modes (auto, silent, favorite, idle)
 * Buzzer (on, off)
 * Child lock (on, off)
 * LED (on, off), LED brightness (bright, dim, off)
 * Favorite Level (0...16)
 * Attributes
-  - power
-  - aqi
-  - average_aqi
-  - humidity
+  - model
   - temperature
+  - humidity
+  - aqi
   - mode
+  - filter_hours_used
+  - filter_life_remaining
   - favorite_level
+  - child_lock
   - led
+  - motor_speed
+  - average_aqi
+  - purify_volume
+  - learn_mode
+  - sleep_time
+  - sleep_mode_learn_count
+  - extra_features
+  - turbo_mode_supported
+  - auto_detect
+  - use_time
+  - button_pressed
+  - buzzer
   - led_brightness
+  - sleep_mode
+
+### Air Purifier Pro (zhimi.airpurifier.v6)
+
+* Power (on, off)
+* Operation modes (auto, silent, favorite)
+* Child lock (on, off)
+* LED (on, off)
+* Favorite Level (0...16)
+* Attributes
+  - model
+  - temperature
+  - humidity
+  - aqi
+  - mode
+  - filter_hours_used
+  - filter_life_remaining
+  - favorite_level
+  - child_lock
+  - led
+  - motor_speed
+  - average_aqi
+  - purify_volume
+  - learn_mode
+  - sleep_time
+  - sleep_mode_learn_count
+  - extra_features
+  - turbo_mode_supported
+  - auto_detect
+  - use_time
+  - button_pressed
+  - filter_rfid_product_id
+  - filter_rfid_tag
+  - filter_type
+  - illuminance
+  - motor2_speed
+  - volume
+
+### Air Purifier V3 (zhimi.airpurifier.v3)
+
+* Power (on, off)
+* Operation modes (auto, silent, favorite, idle, medium, high, strong)
+* Child lock (on, off)
+* LED (on, off)
+* Attributes
+  - model
+  - aqi
+  - mode
+  - led
   - buzzer
   - child_lock
-  - purify_volume
-  - filter_life_remaining
+  - illuminance
   - filter_hours_used
+  - filter_life_remaining
   - motor_speed
+  - average_aqi
+  - volume
+  - motor2_speed
+  - filter_rfid_product_id
+  - filter_rfid_tag
+  - filter_type
+  - purify_volume
+  - learn_mode
+  - sleep_time
+  - sleep_mode_learn_count
+  - extra_features
+  - auto_detect
+  - use_time
+  - button_pressed
 
+### Air Humidifier (zhimi.humidifier.v1)
 
-Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token.
+* On, Off
+* Operation modes (silent, medium, high)
+* Buzzer (on, off)
+* Child lock (on, off)
+* LED brightness (bright, dim, off)
+* Target humidity (30, 40, 50, 60, 70, 80)
+* Attributes
+  - model
+  - temperature
+  - humidity
+  - mode
+  - buzzer
+  - child_lock
+  - trans_level
+  - target_humidity
+  - led_brightness
+  - button_pressed
+  - use_time
+  - hardware_version
+
+### Air Humidifier CA (zhimi.humidifier.ca1)
+
+* On, Off
+* Operation modes (silent, medium, high, auto)
+* Buzzer (on, off)
+* Child lock (on, off)
+* LED brightness (bright, dim, off)
+* Target humidity (30, 40, 50, 60, 70, 80)
+* Dry mode (on, off)
+* Attributes
+  - model
+  - temperature
+  - humidity
+  - mode
+  - buzzer
+  - child_lock
+  - trans_level
+  - target_humidity
+  - led_brightness
+  - button_pressed
+  - use_time
+  - hardware_version
+  - speed
+  - depth
+  - dry
+
+Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
 
 To add a Xiaomi Air Purifier to your installation, add the following to your `configuration.yaml` file:
 
@@ -67,6 +193,10 @@ name:
   required: false
   type: string
   default: Xiaomi Air Purifier
+model:
+  description: The model of your device.
+  required: false
+  type: string
 {% endconfiguration %}
 
 ## {% linkable_title Platform Services %}
@@ -80,37 +210,37 @@ Set the fan speed/operation mode.
 | `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.              |
 | `speed`                   |       no | Fan speed. Valid values are 'Auto', 'Silent', 'Favorite' and 'Idle' |
 
-### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_on` %}
+### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_on` %} (Air Purifier Pro excluded)
 
 Turn the buzzer on.
 
-| Service data attribute    | Optional | Description                                           |
-|---------------------------|----------|-------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 
-### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_off` %}
+### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_off` %} (Air Purifier Pro excluded)
 
 Turn the buzzer off.
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 
-### {% linkable_title Service `fan.xiaomi_miio_set_led_on` %}
+### {% linkable_title Service `fan.xiaomi_miio_set_led_on` %} (Air Purifier only)
 
 Turn the led on.
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 
-### {% linkable_title Service `fan.xiaomi_miio_set_led_off` %}
+### {% linkable_title Service `fan.xiaomi_miio_set_led_off` %} (Air Purifier only)
 
 Turn the led off.
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 
 ### {% linkable_title Service `fan.xiaomi_miio_set_child_lock_on` %}
 
@@ -118,7 +248,7 @@ Turn the child lock on.
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 
 ### {% linkable_title Service `fan.xiaomi_miio_set_child_lock_off` %}
 
@@ -126,23 +256,105 @@ Turn the child lock off.
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 
-### {% linkable_title Service `fan.xiaomi_miio_set_led_brightness` %}
+### {% linkable_title Service `fan.xiaomi_miio_set_led_brightness` %} (Air Purifier Pro excluded)
 
 Set the led brightness. Supported values are 0 (Bright), 1 (Dim), 2 (Off).
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 | `brightness`              |       no | Brightness, between 0 and 2.                            |
 
-### {% linkable_title Service `fan.xiaomi_miio_set_favorite_level` %}
+### {% linkable_title Service `fan.xiaomi_miio_set_favorite_level` %} (Air Purifier only)
 
 Set the favorite level of the operation mode "favorite".
 
 | Service data attribute    | Optional | Description                                             |
 |---------------------------|----------|---------------------------------------------------------|
-| `entity_id`               |      yes | Only act on a specific air purifier. Else targets all.  |
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
 | `level`                   |       no | Level, between 0 and 16.                                |
 
+### {% linkable_title Service `fan.xiaomi_miio_set_auto_detect_on` %} (Air Purifier Pro only)
+
+Turn the auto detect on.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_auto_detect_off` %} (Air Purifier Pro only)
+
+Turn the auto detect off.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_learn_mode_on` %} (Air Purifier 2 only)
+
+Turn the learn mode on.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_learn_mode_off` %} (Air Purifier 2 only)
+
+Turn the learn mode off.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_volume` %} (Air Purifier Pro only)
+
+Set the sound volume.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+| `volume`                  |       no | Volume, between 0 and 100.                              |
+
+### {% linkable_title Service `fan.xiaomi_miio_reset_filter` %} (Air Purifier 2 only)
+
+Reset the filter lifetime and usage.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_extra_features` %} (Air Purifier only)
+
+Set the extra features.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+| `features`                |       no | Integer, known values are 0 and 1.                      |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_target_humidity` %} (Air Humidifier only)
+
+Set the target humidity.
+
+| Service data attribute    | Optional | Description                                                     |
+|---------------------------|----------|-----------------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+| `humidity`                |       no | Target humidity. Allowed values are 30, 40, 50, 60, 70 and 80   |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_dry_on` %} (Air Humidifier CA only)
+
+Turn the dry mode on.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |
+
+### {% linkable_title Service `fan.xiaomi_miio_set_dry_off` %} (Air Humidifier CA only)
+
+Turn the dry mode off.
+
+| Service data attribute    | Optional | Description                                             |
+|---------------------------|----------|---------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. |

source/_components/folder_watcher.markdown

@@ -0,0 +1,81 @@
+---
+layout: page
+title: "Folder Watcher"
+description: "Component for monitoring changes within the filesystem."
+date: 2018-03-11 14:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: home-assistant.png
+ha_category: System Monitor
+ha_iot_class: "Local Polling"
+ha_release: 0.67
+---
+
+This component adds [Watchdog](https://pythonhosted.org/watchdog/) file system monitoring, publishing events on the Home Assistant bus on the creation/deletion/modification of files within configured folders. The monitored `event_type` are:
+
+* `created`
+* `deleted`
+* `modified`
+* `moved`
+
+Configured folders must be added to [whitelist_external_dirs](/docs/configuration/basic/). Note that by default folder monitoring is recursive, meaning that the contents of sub-folders are also monitored.
+
+To enable the Folder Watcher component in your installation, add the following to your `configuration.yaml` file:
+
+{% raw %}
+```yaml
+folder_watcher:
+  - folder: /config
+```
+{% endraw %}
+
+{% configuration %}
+folder:
+  description: The folder path
+  required: true
+  type: string
+patterns:
+  description: Pattern matching to apply
+  required: false
+  default: "*"
+  type: string
+{% endconfiguration %}
+
+## Patterns
+
+Pattern matching using [fnmatch](https://docs.python.org/3.6/library/fnmatch.html) can be used to limit filesystem monitoring to only files which match the configured patterns. The following example shows the configuration required to only monitor filetypes `.yaml` and `.txt`.
+
+{% raw %}
+```yaml
+folder_watcher:
+  - folder: /config
+    patterns:
+      - '*.yaml'
+      - '*.txt'
+```
+{% endraw %}
+
+## Automations
+
+Automations can be triggered on filesystem event data using a `data_template`. The following automation will send a notification with the name and folder of new files added to that folder:
+
+{% raw %}
+```yaml
+- action:
+  - data_template:
+      message: 'Created {{ trigger.event.data.file }} in {{ trigger.event.data.folder }}'
+      title: New image captured!
+      data:
+        file: " {{ trigger.event.data.path }} "
+    service: notify.pushbullet
+  alias: New file alert
+  condition: []
+  id: '1520092824697'
+  trigger:
+  - event_data: {"event_type":"created"}
+    event_type: folder_watcher
+    platform: event
+```
+{% endraw %}

source/_components/freedns.markdown

@@ -0,0 +1,49 @@
+---
+layout: page
+title: "freedns.afraid.org"
+description: "Keep your DNS record up to date with FreeDNS."
+date: 2018-03-27 21:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_category: Utility
+ha_release: 0.67
+---
+
+With the `freedns` component you can keep your [FreeDNS](https://freedns.afraid.org) record up to date.
+
+## {% linkable_title Configuration %}
+
+You need to determine your update URL or your access token.
+
+1. Head over to the [FreeDNS](https://freedns.afraid.org) website and login to your account.
+2. Select the menu "Dynamic DNS"
+3. You should now see your update candiates in a table at the bottom of the page.
+4. Copy the link target of the "Direct URL".
+5. The access token is the part at the end of the link: `https://freedns.afraid.org/dynamic/update.php?YOUR_UPDATE_TOKEN`
+6. Either put the token as `access_token` _or_ the whole URL into the `url` attribute.
+
+To use the component in your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+freedns:
+  access_token: YOUR_TOKEN
+```
+
+{% configuration %}
+  access_token:
+    description: Your access token. This is exclusive to `url`.
+    required: false
+    type: string
+  url:
+    description: The full update URL. This is exclusive to `access_token`.
+    required: false
+    type: string
+  update_interval:
+    description: How often to call the update service.
+    required: false
+    type: time period
+    default: 10 minutes
+{% endconfiguration %}

source/_components/fritzbox.markdown

@@ -0,0 +1,55 @@
+---
+layout: page
+title: "Fritzbox"
+description: "Instructions on how to integrate the AVM Fritzbox Smart Home components."
+date: 2018-02-18 17:10
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: avm.png
+ha_category: Hub
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+The [AVM](https://en.avm.de) Fritzbox component for Home Assistant allows you to integrate the switch and climate devices.
+
+#### {% linkable_title Tested Devices %}
+
+- [FRITZ!Box 6490 Cable](https://en.avm.de/products/fritzbox/fritzbox-6490-cable/)
+- [FRITZ!Box 7590](https://en.avm.de/products/fritzbox/fritzbox-7590/)
+- [FRITZ!DECT 200](https://en.avm.de/products/fritzdect/fritzdect-200/)
+- [Eurotronic Comet DECT](https://www.eurotronic.org/en/products/comet-dect.html)
+
+
+## {% linkable_title Setup %}
+
+```yaml
+# Example configuration.yaml entry
+fritzbox:
+  devices:
+    - host: fritz.box
+      username: YOUR_USERNAME
+      password: YOUR_PASSWORD
+```
+
+{% configuration %}
+devices:
+  description: A list of Fritzbox devices.
+  required: true
+  type: map
+  keys:
+    host:
+      description: The hostname or IP address of the Fritzbox.
+      required: true
+      type: optional
+    username:
+      description: The username for Smart Home access.
+      required: true
+      type: string
+    password:
+      description: The password of the user.
+      required: true
+      type: string
+{% endconfiguration %}

source/_components/google_assistant.markdown

@@ -13,6 +13,10 @@ featured: true
 ha_release: 0.56
 ---
 
+<p class='note'>
+  Use [Home Assistant Cloud](/cloud/) to integrate with Google Assistant without any effort.
+</p>
+
 The `google_assistant` component allows you to control things via Google Assistant (on your mobile or tablet) or a Google Home device.
 
 The Google Assistant component requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.
@@ -21,6 +25,8 @@ The Google Assistant component requires a bit more setup than most due to the wa
 To use Google Assistant, your Home Assistant configuration has to be externally accessible with a hostname and SSL certificate. If you haven't already configured that, you should do so before continuing.
 </p>
 
+## {% linkable_title Configuration %}
+
 To enable this, add the following lines to your `configuration.yaml` file:
 
 ```yaml
@@ -102,7 +108,7 @@ entity_config:
           required: false
           type: list
         room:
-          description: Allows for associating this device to a Room in Google Assistant.  This is currently non-functional, but will be enabled in the near future.
+          description: Allows for associating this device to a Room in Google Assistant.
           required: false
           type: string
 {% endconfiguration %}
@@ -134,7 +140,7 @@ If you're not using Linux, you can use sites such as [this one](https://www.brow
 1. Create a new project in the [developer console](https://console.actions.google.com/).
   a. Add/Import project
   b. Click on `BUILD` on the `Smart home` card
-  c. Type in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable. 
+  c. Type in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable.
   d. Click `Done`. Then click on `Overview`, which will lead you to the app details screen.
 2. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant.
 3. The final item on that page `Account linking` is required for your app to interact with Home Assistant.

source/_components/hive.markdown

@@ -14,11 +14,13 @@ ha_iot_class: "Cloud Polling"
 ---
 
 
-This Hive component is the main component to set up and integrate all supported Hive devices. Once configured with the minimum required details it will detect and add all your Hive devices into Home Assistant, including support for multizone heating.
+The `hive` component is the main component to set up and integrate all supported Hive devices. Once configured with the minimum required details it will detect and add all your Hive devices into Home Assistant, including support for multizone heating.
 
 This component uses the unofficial API used in the official Hive website [https://my.hivehome.com](https://my.hivehome.com), and you will need to use the same Username and Password you use on the Hive website to configure this Hive component in Home Assistant.
 
-To add your Hive devices into your Home Assistant installation, using the default scan_interval, add the following to your 'configuration.yaml' file:
+
+
+To add your Hive devices into your Home Assistant installation, add the following to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry

source/_components/homekit.markdown

@@ -12,10 +12,10 @@ ha_release: 0.64
 logo: apple-homekit.png
 ---
 
-The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later.
+The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they can be controlled from Apple's `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later.
 
 <p class="note warning">
-  It might be necessary to install an additional package:  
+  It might be necessary to install an additional package:
   `$ sudo apt-get install libavahi-compat-libdnssd-dev`
 </p>
 
@@ -39,6 +39,10 @@ The `HomeKit` component allows you to forward entities from Home Assistant to Ap
         required: false
         type: int
         default: 51827
+      ip_address:
+        description: The local network IP address. Only necessary if the default from Home Assistant does not work.
+        required: false
+        type: string
       filter:
         description: Filter entities to available in the `Home` app. ([Configure Filter](#configure-filter))
         required: false
@@ -77,6 +81,9 @@ The `HomeKit` component allows you to forward entities from Home Assistant to Ap
                 default: ''
 {% endconfiguration %}
 
+<p class='note'>
+  If you use Z-Wave, or `discovery:` you'll need to disable auto-start, see the [section below](#disable-auto-start) for details on how to do this. You'll then need to start the HomeKit component once Z-Wave is ready, or an appropriate delay to allow your entities to be discovered.
+</p>
 
 ## {% linkable_title Setup %}
 
@@ -87,7 +94,7 @@ To enable the `HomeKit` component in Home Assistant, add the following to your c
 homekit:
 ```
 
-After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if the are [supported](#supported-components). To add them:
+After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if they are [supported](#supported-components). To add them:
 1. Open the Home Assistant frontend. A new card will display the `pin code`.
 1. Open the `Home` app.
 2. Choose `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and enter the `pin code`.
@@ -107,7 +114,7 @@ Currently this component uses the `entity_id` to generate a unique `accessory id
 
 ### {% linkable_title Persistence Storage %}
 
-Unfortunately `HomeKit` doesn't support any kind of persistence storage, only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)
+Unfortunately `HomeKit` doesn't support any kind of persistent storage - only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)
 
 A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable `auto start` and `turn off` the `Start HomeKit` automation (if you have one).
 
@@ -116,7 +123,7 @@ A common situation might be if you decide to disable parts of the configuration
 
 Depending on your individual setup, it might be necessary to disable `Auto Start` for all accessories to be available for `HomeKit`. Only those entities that are fully setup when the `HomeKit` component is started, can be added. To start `HomeKit` when `auto_start: False`, you can call the service `homekit.start`.
 
-This can be automated using an `automation`.
+If you have Z-Wave entities you want exposed to HomeKit then you'll need to disable auto start and then start it after the Z-Wave mesh is ready. This is because the Z-Wave entities won't be fully set up until then. This can be automated using an automation:
 
 {% raw %}
 ```yaml
@@ -134,6 +141,8 @@ automation:
 ```
 {% endraw %}
 
+For a general delay where your component doesn't generate an event, you can also do:
+
 {% raw %}
 ```yaml
 # Example using a delay after start of Home Assistant
@@ -154,7 +163,7 @@ automation:
 
 ## {% linkable_title Configure Filter %}
 
-By default no entity will be excluded. To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. Keep in mind only [supported components](#supported-components) can be added. 
+By default no entity will be excluded. To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. Keep in mind only [supported components](#supported-components) can be added.
 
 {% raw %}
 ```yaml
@@ -184,7 +193,7 @@ Filters are applied as follows:
       - if both include and exclude domains specified, the exclude domains are ignored
    * Neither include or exclude domain specified
       - if entity is included, pass (as #2 above)
-      - if entity include and exclude, the entity exclude is ignored 
+      - if entity include and exclude, the entity exclude is ignored
 
 
 ## {% linkable_title Supported Components %}
@@ -194,11 +203,20 @@ The following components are currently supported:
 | Component | Type Name | Description |
 | --------- | --------- | ----------- |
 | alarm_control_panel | SecuritySystem | All security systems. |
+| binary_sensor | Sensor | Support for `co2`, `door`, `garage_door`, `gas`, `moisture`, `motion`, `occupancy`, `opening`, `smoke` and `window` device classes. Defaults to the `occupancy` device class for everything else. |
 | climate | Thermostat | All climate devices. |
+| cover | GarageDoorOpener | All covers that support `open` and `close` and have `garage` as their `device_class`. |
 | cover | WindowCovering | All covers that support `set_cover_position`. |
+| cover | WindowCovering | All covers that support `open_cover` and `close_cover` through value mapping. (`open` -> `>=50`; `close` -> `<50`) |
+| cover | WindowCovering | All covers that support `open_cover`, `stop_cover` and `close_cover` through value mapping. (`open` -> `>70`; `close` -> `<30`; `stop` -> every value in between) |
+| device_tracker | Sensor | Support for `occupancy` device class. |
 | light | Light | Support for `on / off`, `brightness` and `rgb_color`. |
-| sensor | TemperatureSensor | All sensors that have `Celsius` and `Fahrenheit` as their `unit_of_measurement`. |
-| sensor | HumiditySensor | All sensors that have `%` as their `unit_of_measurement` |
+| lock | DoorLock | Support for `lock / unlock`. |
+| sensor | TemperatureSensor | All sensors that have `Celsius` or `Fahrenheit` as their `unit_of_measurement` or `temperature` as their `device_class`. |
+| sensor | HumiditySensor | All sensors that have `%` as their `unit_of_measurement` and `humidity` as their `device_class`. |
+| sensor | AirQualitySensor | All sensors that have `pm25` as part of their `entity_id` or `pm25` as their `device_class` |
+| sensor | CarbonDioxideSensor | All sensors that have `co2` as part of their `entity_id` or `co2` as their `device_class` |
+| sensor | LightSensor | All sensors that have `lm` or `lx` as their `unit_of_measurement` or `illuminance` as their `device_class` |
 | switch / remote / input_boolean / script | Switch | All represented as switches. |
 
 
@@ -212,6 +230,7 @@ logger:
   default: warning
   logs:
        homeassistant.components.homekit: debug
+       pyhap: debug
 ```
 2. Reproduce the bug / problem you have encountered.
 3. Stop Home Assistant and copy the log from the log file. That is necessary since some errors only get logged, when Home Assistant is being shutdown.

source/_components/homekit_controller.markdown

@@ -0,0 +1,36 @@
+---
+layout: page
+title: "HomeKit controller support"
+description: "Instructions how to integrate your HomeKit devices within Home Assistant."
+date: 2018-03-19 21:04
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: apple-homekit.png
+ha_category: Hub
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+[HomeKit](https://developer.apple.com/homekit/) controller integration for Home Assistant allows you to connect HomeKit accessories to Home Assistant. This component should not be confused with the [HomeKit](/components/homekit/) component, which allows you to control Home Assistant devices via HomeKit.
+
+<p class="note warning">
+ You may need additional packages to support the HomeKit Python module:
+ `$ sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev`
+</p>
+
+There is currently support for the following device types within Home Assistant:
+
+- [Light](/components/light.homekit_controller/)
+- [Switch](/components/switch.homekit_controller/)
+
+The component will be automatically configured if the [`discovery:`](/components/discovery/) component is enabled and an enable entry added for HomeKit:
+
+```yaml
+discovery:
+  enable:
+    - homekit
+```
+
+For each detected HomeKit accessory, a configuration prompt will appear in the web front end. Use this to provide the HomeKit PIN. Note that HomeKit accessories can only be paired to one device at once. If your device is currently paired with Siri, you will need to reset it in order to pair it with Home Assistant. Once Home Assistant is configured to work with the device, you can export it back to Siri with the [`HomeKit`](/components/homekit/) component.

source/_components/http.markdown

@@ -90,7 +90,7 @@ Please note, that sources from `trusted_networks` won't be banned automatically.
 
 ## {% linkable_title Hosting files %}
 
-If you want to use Home Assistant to host or serve static files then create a directory called `www` under the configuration path (`/config` on Hass.io, `.homeassistant` elswhere). The static files in `www/` can be accessed by the following URL `http://your.domain:8123/local/`, for example `audio.mp3` would be accessed as `http://your.domain:8123/local/audio.mp3`.
+If you want to use Home Assistant to host or serve static files then create a directory called `www` under the configuration path (`/config` on Hass.io, `.homeassistant` elsewhere). The static files in `www/` can be accessed by the following URL `http://your.domain:8123/local/`, for example `audio.mp3` would be accessed as `http://your.domain:8123/local/audio.mp3`.
 
 <p class='note'>
   If you've had to create the `www/` folder for the first time, you'll need to restart Home Assistant.

source/_components/insteon_plm.markdown

@@ -63,26 +63,52 @@ a responder or a controller.
 
 In order for any two Insteon devices to talk with one another, they must be 
 linked. For an overview of device linking please read the Insteon page on
-[understanding linking]. Currently Insteon PLM does not support software
-linking of devices. If you need software that can link your devices (if you 
-are using a USB Stick PLM for example), you can download [HouseLinc] which runs
-on any Windows PC, or you can use [Insteon Terminal] which is open source and 
-runs on most platforms. HouseLinc is no longer supported by SmartHome but it 
-still works. Insteon Terminal is a very useful tool but please read the 
-disclaimers carefully, they are important.
+[understanding linking]. The Insteon PLM module supports All-Linking through 
+[Development Tools] service calls. The following services are available:
+
+In order for any two Insteon devices to talk with one another, they must be 
+linked. For an overview of device linking, please read the Insteon page on
+[understanding linking]. The Insteon PLM module supports All-Linking through 
+[Development Tools] service calls. The following services are available:
+- **insteon_plm.add_all_link**: Tells the Insteon Modem (IM) start All-Linking 
+mode. Once the IM is in All-Linking mode, press the link button on the device 
+to complete All-Linking.
+- **insteon_plm.delete_all_link**: Tells the Insteon Modem (IM) to remove an 
+All-Link record from the All-Link Database of the IM and a device. Once the IM 
+is set to delete the link, press the link button on the corresponding device 
+to complete the process.
+- **insteon_plm.load_all_link_database**: Load the All-Link Database for a 
+device. WARNING - Loading a device All-Link database is very time consuming 
+and inconsistent. This may take a LONG time and may need to be repeated to 
+obtain all records.
+- **insteon_plm.print_all_link_database**: Print the All-Link Database for a 
+device. Requires that the All-Link Database is loaded into memory.
+- **insteon_plm.print_im_all_link_database**: Print the All-Link Database for 
+the INSTEON Modem (IM).
+
+If you are looking for more advanced options, you can use the 
+[insteonplm_interactive] command line tool that is distributed with the 
+[insteonplm] Python module. Please see the documentation on the [insteonplm] 
+GitHub site. Alternatively, you can download [HouseLinc] which runs on any 
+Windows PC, or you can use [Insteon Terminal] which is open source and runs 
+on most platforms. SmartHome no longer supports HouseLinc, but it still 
+works. Insteon Terminal is a very useful tool but please read the disclaimers 
+carefully, they are important.
 
 [understanding linking]: http://www.insteon.com/support-knowledgebase/2015/1/28/understanding-linking
+[Development Tools]: https://www.home-assistant.io/docs/tools/dev-tools/
 [HouseLinc]: https://www.smarthome.com/houselinc.html
 [Insteon Terminal]: https://github.com/pfrommerd/insteon-terminal
+[insteonplm_interactive]: https://github.com/nugget/python-insteonplm#command-line-interface
 
 ### {% linkable_title Customization %} 
 
-The only configuration item that is absolutely necessary is the port so that
-Home Assistant can connect to the PLM.  This will expose all the supported INSTEON
-devices which exist in the modem's ALL-Link database.  However, devices will
-only be shown by their INSTEON hex address (e.g., "1A.2B.3C") which can be a bit
-unwieldy.  As you link and unlink devices using the 'Set' buttons, they'll be
-added and removed from Home Assistant automatically.
+The only configuration item that is absolutely necessary is the port so that 
+Home Assistant can connect to the PLM. This will expose all the supported 
+INSTEON devices which exist in the modem’s ALL-Link database. However, devices 
+will only be shown by their INSTEON hex address (e.g., “1A.2B.3C”) which can 
+be a bit unwieldy. As you link and unlink devices using the ‘Set’ buttons, 
+they’ll be added and removed from Home Assistant automatically.
 
 You can use the normal Home Assistant [device customization] section of your
 configuration to assign friendly names and special icons to your devices.  This
@@ -123,7 +149,9 @@ insteon_plm:
       cat: 0x10
       subcat: 0x11     
 ```
+
 ### {% linkable_title What NOT to do %}
+
 Insteon PLM is a top level component and device discovery will identify 
 the Home Assistant platform the device belongs in. As such, do not 
 declare Insteon devices in other platforms. For example, this configuration
@@ -134,4 +162,3 @@ light:
   - platform: insteon_plm
     address: 1a2b3c
 ```
-

source/_components/ios.markdown

@@ -0,0 +1,17 @@
+---
+layout: page
+title: "iOS"
+description: "Instructions on how to use the iOS companion app with Home Assistant."
+date: 2018-04-06 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: apple.png
+ha_category: Hub
+featured: false
+ha_release: 0.31
+ha_iot_class: depends
+---
+
+The `ios` component is the Home Assistant part for using the iOS companion app. For further details please check the [iOS section](/docs/ecosystem/ios/) in the documentation for further details.

source/_components/juicenet.markdown

@@ -15,10 +15,12 @@ ha_release: 0.47
 
 The `juicenet` sensor platform pulls data from a [JuiceNet](https://emotorwerks.com/products/juicenet/) charging station equipped with a wifi connection. It will access and make available all of the devices attached to your account.
 
+## {% linkable_title Configuration %}
+
 To enable the platform in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 juicenet:
     access_token: ACCESS_TOKEN
 ```

source/_components/light.eufy.markdown

@@ -0,0 +1,19 @@
+---
+layout: page
+title: "Eufy Lights"
+description: "Instructions on how to integrate Eufy LED lights into Home Assistant."
+date: 2018-04-09 19:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: eufy.png
+ha_category: Light
+ha_iot_class: "Local Polling"
+ha_release: 0.68
+---
+
+The `eufy` platform allows you to control your [Eufy](http://www.eufylife.com) lights from within Home Assistant.
+
+They will be automatically discovered if the [Eufy](/components/eufy/) component is enabled.
+

source/_components/light.hive.markdown

@@ -14,12 +14,13 @@ ha_iot_class: "Cloud Polling"
 ---
 
 
-The 'hive' light component integrates your Hive lights into Home Assistant, enabling control of various settings, depending on the model light.
+The `hive` light platform integrates your Hive lights into Home Assistant, enabling control of various settings, depending on the model light.
 
-The Hive light component supports the following Hive products:
-- **Hive Active Light Dimmable**
-- **Hive Active Light Cool to Warm White**
-- **Hive Active Light Color Changing**
+The platform supports the following Hive products:
+
+- Hive Active Light Dimmable
+- Hive Active Light Cool to Warm White
+- Hive Active Light Color Changing
 
 
 <p class='note'>

source/_components/light.homekit_controller.markdown

@@ -0,0 +1,16 @@
+---
+layout: page
+title: "HomeKit Light"
+description: "Instructions how to setup HomeKit lights within Home Assistant."
+date: 2017-03-19 21:08
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: apple-homekit.png
+ha_category: Light
+ha_iot_class: "Local Polling"
+ha_release: 0.68
+---
+
+To get your HomeKit lights working with Home Assistant, follow the instructions for the general [HomeKit controller component](/components/homekit_controller/).

source/_components/light.mochad.markdown

@@ -11,13 +11,14 @@ ha_category: Light
 ha_release: 0.51
 ---
 
-The `mochad` light platform lets you control an X10 enabled dimmer/light
-device.
+The `mochad` light platform lets you control an X10 enabled dimmer/light device.
+
+
 
 To enable this sensor, you first have to set up the [mochad component](/components/mochad/) and then add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 light:
   - platform: mochad
     devices:

source/_components/light.mqtt.markdown

@@ -14,6 +14,8 @@ ha_iot_class: depends
 
 The `mqtt` light platform lets you control your MQTT enabled lights. It supports setting brightness, color temperature, effects, flashing, on/off, RGB colors, transitions, XY colors and white values.
 
+## {% linkable_title Configuration %}
+
 In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT light will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the switch will be `false` / `off`.
 
 When a state topic is not available, the light will work in optimistic mode. In this mode, the light will immediately change state after every command. Otherwise, the light will wait for state confirmation from the device (message from `state_topic`).
@@ -21,7 +23,7 @@ When a state topic is not available, the light will work in optimistic mode. In
 Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect light operation.
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 light:
   - platform: mqtt
     command_topic: "office/rgb1/light/switch"
@@ -194,6 +196,7 @@ payload_not_available:
 | RGB Color         | ✔                                                          | ✔                                                                    | ✔                                                                            |
 | Transitions       | ✘                                                          | ✔                                                                    | ✔                                                                            |
 | XY Color          | ✔                                                          | ✔                                                                    | ✘                                                                            |
+| HS Color          | ✘                                                          | ✔                                                                    | ✘                                                                            |
 | White Value       | ✔                                                          | ✔                                                                    | ✔                                                                            |
 
 ## {% linkable_title Examples %}
@@ -204,8 +207,9 @@ In this section you will find some real life examples of how to use this sensor.
 
 To enable a light with brightness and RGB support in your installation, add the following to your `configuration.yaml` file:
 
+{% raw %}
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 light:
   - platform: mqtt
     name: "Office Light RGB"
@@ -215,21 +219,22 @@ light:
     brightness_command_topic: "office/rgb1/brightness/set"
     rgb_state_topic: "office/rgb1/rgb/status"
     rgb_command_topic: "office/rgb1/rgb/set"
-    state_value_template: "{% raw %}{{ value_json.state }}{% endraw %}"
-    brightness_value_template: "{% raw %}{{ value_json.brightness }}{% endraw %}"
-    rgb_value_template: "{% raw %}{{ value_json.rgb | join(',') }}{% endraw %}"
+    state_value_template: "{{ value_json.state }}"
+    brightness_value_template: "{{ value_json.brightness }}"
+    rgb_value_template: "{{ value_json.rgb | join(',') }}"
     qos: 0
     payload_on: "ON"
     payload_off: "OFF"
     optimistic: false
 ```
+{% endraw %}
 
 ### {% linkable_title Brightness and no RGB support %}
 
 To enable a light with brightness (no RGB version) in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 light:
   - platform: mqtt
     name: "Office light"
@@ -248,7 +253,7 @@ light:
 To enable a light that sends only brightness topics to turn it on, add the following to your `configuration.yaml` file. The `command_topic` is only used to send an off command in this case:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 light:
   - platform: mqtt
     name: "Brightness light"
@@ -260,7 +265,6 @@ light:
     on_command_type: 'brightness'
 ```
 
-
 ### {% linkable_title Implementations %}
 
 - A [basic example](https://github.com/mertenats/open-home-automation/tree/master/ha_mqtt_light) using a nodeMCU board (ESP8266) to control its built-in LED (on/off).

source/_components/light.mqtt_json.markdown

@@ -23,10 +23,12 @@ This platform supports on/off, brightness, RGB colors, XY colors, color temperat
   "color_temp": 155,
   "color": {
     "r": 255,
-    "g": 255,
-    "b": 255,
-    "x": 0.123,
-    "y": 0.123
+    "g": 180,
+    "b": 200,
+    "x": 0.406,
+    "y": 0.301,
+    "h": 344.0,
+    "s": 29.412
   },
   "effect": "colorloop",
   "state": "ON",
@@ -126,6 +128,11 @@ xy:
   required: false
   type: boolean
   default: false
+hs:
+  description: Flag that defines if the light supports HS colors.
+  required: false
+  type: boolean
+  default: false
 availability_topic:
   description: The MQTT topic subscribed to receive availability (online/offline) updates.
   required: false
@@ -147,7 +154,7 @@ payload_not_available:
 </p>
 
 <p class='note warning'>
-  XY and RGB can not be used at the same time. If both are provided, XY overrides RGB.
+  RGB, XY and HSV can not be used at the same time in `state_topic` messages. Make sure that only one of the color models is in the "color" section of the state MQTT payload.
 </p>
 
 ## {% linkable_title Comparison of light MQTT platforms %}
@@ -161,6 +168,7 @@ payload_not_available:
 | RGB Color         | ✔                                                          | ✔                                                                    | ✔                                                                            |
 | Transitions       | ✘                                                          | ✔                                                                    | ✔                                                                            |
 | XY Color          | ✔                                                          | ✔                                                                    | ✘                                                                            |
+| HS Color          | ✘                                                          | ✔                                                                    | ✘                                                                            |
 | White Value       | ✔                                                          | ✔                                                                    | ✔                                                                            |
 
 ## {% linkable_title Examples %}
@@ -215,7 +223,32 @@ Home Assistant will then convert its 8bit value in the message to and from the d
 ```json
 {
   "brightness": 4095,
+  "state": "ON"
+}
+```
+
+### {% linkable_title HS Color %}
+
+To use a light with hue+saturation as the color model, set `hs` to `true` in the platform configuration:
+
+```yaml
+light:
+  - platform: mqtt_json
+    name: mqtt_json_hs_light
+    state_topic: "home/light"
+    command_topic: "home/light/set"
+    hs: True
+```
+
+Home Assistant expects the hue values to be in the range 0 to 360 and the saturation values to be scaled from 0 to 100. For example, the following is a blue color shade:
+
+```json
+{
   "state": "ON",
+  "color": {
+    "h": 24.0,
+    "s": 100.0
+  }
 }
 ```
 
@@ -228,3 +261,5 @@ Home Assistant will then convert its 8bit value in the message to and from the d
 - [MQTT JSON Light](https://github.com/mertenats/Open-Home-Automation/tree/master/ha_mqtt_rgbw_light_with_discovery) is another implementation for ESP8266 including [MQTT discovery](/docs/mqtt/discovery/).
 
 - [esphomelib](https://github.com/OttoWinter/esphomelib) is a library for ESP8266 and ESP32 boards that has many of Home Assistant's MQTT features (like [discovery](/docs/mqtt/discovery/)) pre-implemented and provides high-level abstractions for components such as lights or sensors.
+
+- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/components/light.mqtt_json/) platform and supports ON/OFF, RGBW colours, brightness, colour temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/docs/mqtt/discovery/)) and the MQTT Last Will and Testament is enabled as well.

source/_components/light.mqtt_template.markdown

@@ -132,6 +132,7 @@ payload_not_available:
 | RGB Color         | ✔                                                          | ✔                                                                    | ✔                                                                            |
 | Transitions       | ✘                                                          | ✔                                                                    | ✔                                                                            |
 | XY Color          | ✔                                                          | ✔                                                                    | ✘                                                                            |
+| HS Color          | ✘                                                          | ✔                                                                    | ✘                                                                            |
 | White Value       | ✔                                                          | ✔                                                                    | ✔                                                                            |
 
 ## {% linkable_title Examples %}

source/_components/light.nanoleaf_aurora.markdown

@@ -0,0 +1,52 @@
+---
+layout: page
+title: "Nanoleaf Aurora Light Panel"
+description: "Instructions how to integrate Nanoleaf Aurora Light Panels into Home Assistant."
+date: 2018-01-04 20:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: nanoleaf_aurora_light.png
+ha_category: Light
+ha_iot_class: "Local Polling"
+featured: false
+ha_release: 0.67
+---
+
+### {% linkable_title Configuration Sample %}
+
+To enable the Aurora lights, add the following lines to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+light:
+  - platform: nanoleaf_aurora
+    host: 192.168.1.10
+    token: xxxxxxxxxxxxxxxxxxxxx
+```
+
+{% configuration %}
+host:
+  description: IP address or host-name of the device, e.g., 192.168.1.10.
+  required: true
+  type: string
+token:
+  description: The *auth* token that you get via *POST* to */api/v1/new*
+  required: true
+  type: string
+name:
+  description: Name of the component, make this unique if you have multiple Light Panels
+  required: false
+  type: string
+  default: Aurora
+{% endconfiguration %}
+
+### {% linkable_title Getting The Auth Token %}
+
+1. Make sure that your Nanoleaf Aurora Panel is fully patched (as of the time of writing the latest version was 2.2.0)
+2. Hold down the *ON* button on the Panel for 5 seconds; the LED will start flashing
+3. Issue a *POST* request to the API endpoint, e.g., via `$ curl -i -X POST http://192.168.1.155:16021/api/v1/new`
+4. The output should include the auth token like *{"auth_token":"xxxxxxxxxxxxxxxxxxxxx"}*, copy the resulting token into your configuration
+
+If you get a 403 Forbidden message, you probably did not press the *ON* button long enough. The time-frame to get a valid token is only 30 seconds, so you have to be quick to issue the curl request.

source/_components/light.yeelight.markdown

@@ -35,7 +35,7 @@ light:
 
 Configuration variables:
 
-- **ip** (*Required*): IP(s) of your wifi bulbs
+- **ip** (*Required*): IP(s) of your Wifi bulbs
 - **name** (*Optional*): A friendly name for the device.
 - **transition** (*Optional*, default 350): Smooth transitions over time (in ms).
 - **use_music_mode** (*Optional*, default False): Enable music mode.
@@ -63,3 +63,17 @@ This component is tested to work with the following models. If you have a differ
 - **YLDD02YL**: Lightstrip (Color)
 - **MJCTD01YL**: Xiaomi Mijia Bedside Lamp - WIFI Version!
 - **MJTD01YL**: Xiaomi Mijia Smart LED Desk Lamp (autodiscovery isn't possible because the device doesn't support mDNS due to the small amount of RAM)
+- **YLXD02YL**: Yeelight Ceiling Light 4 (Jiaoyue 650)
+- **YLXD01YL**: Yeelight Smart LED Ceiling Light - Youth Version
+
+
+## {% linkable_title Platform Services %}
+
+### {% linkable_title Service `light.yeelight_set_mode` %}
+
+Set a operation mode.
+
+| Service data attribute    | Optional | Description                                                                                 |
+|---------------------------|----------|---------------------------------------------------------------------------------------------|
+| `entity_id`               |      yes | Only act on a specific yeelight. Else targets all.                                          |
+| `mode`                    |       no | Operation mode. Valid values are 'last', 'normal', 'rgb', 'hsv', 'color_flow', 'moonlight'. |

source/_components/lock.bmw_connected_drive.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
-title: "BMW connected drive"
-description: "Instructions on how to setup your BMW connected drive account with Home Assistant."
+title: "BMW Connected Drive Lock"
+description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant."
 date: 2018-02-22 23:00
 sidebar: true
 comments: false
@@ -15,6 +15,6 @@ ha_release: 0.66
 
 The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant.
 
-The lock will be automatically configured if 'bmw_connected_drive' component is configured.
+The lock will be automatically configured if `bmw_connected_drive` component is configured.
 
-For more configuration information see the [bmw_connected_drive component](/components/bmw_connected_drive/) documentation.
+For more configuration information see the [`bmw_connected_drive` component](/components/bmw_connected_drive/) documentation.

source/_components/lock.homematic.markdown

@@ -1,8 +1,8 @@
 ---
 layout: page
-title: "Homematic Lock"
-description: "Instructions on how to integrate Homematic locks within Home Assistant."
-date: 2016-06-28 08:30
+title: "Homematic Lock (KeyMatic)"
+description: "Instructions how to integrate Homematic locks (KeyMatic) within Home Assistant."
+date: 2018-01-28 03:00
 sidebar: true
 comments: false
 sharing: true
@@ -13,7 +13,6 @@ ha_release: 0.66
 ha_iot_class: "Local Push"
 ---
 
+The `homematic` lock platform lets you observe and control the state of the HomeMatic  [Homematic](http://www.homematic.com/) KeyMatic lock through Home Assistant.
 
-The `homematic` lock platform lets you control [Homematic](http://www.homematic.com/) locks through Home Assistant.
-
-Devices will be configured automatically. Please refer to the [component](/components/homematic/) configuration on how to setup Homematic.
+Devices will be configured automatically. Please refer to the [component](/components/homematic/) configuration on how to setup Homematic.

source/_components/lock.mqtt.markdown

@@ -24,7 +24,7 @@ Optimistic mode can be forced, even if state topic is available. Try to enable i
 To enable MQTT locks in your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
 lock:
   - platform: mqtt
     command_topic: "home/frontdoor/set"

source/_components/matrix.markdown

@@ -0,0 +1,136 @@
+---
+layout: page
+title: "Matrix"
+description: "Matrix chatbot support"
+date: 2018-03-25 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: matrix.png
+ha_category: Hub
+ha_version: 0.69
+---
+
+This component allows you to send messages to matrix rooms, as well as to react to messages in matrix rooms. Reacting to commands is accomplished by firing an event when one of the configured commands is triggered.
+
+```yaml
+# Example configuration.yaml entry
+matrix:
+  homeserver: https://matrix.org
+  username: "@my_matrix_user:matrix.org"
+  password: supersecurepassword
+  rooms:
+    - "#hasstest:matrix.org"
+  commands:
+    - word: my_command
+      name: my_command
+```
+
+Configuration variables:
+
+{% configuration %}
+username:
+  description: "The matrix username that home assistant should use to log in. *Note*: You must specify a full matrix ID here, including the homeserver domain, e.g. '@my_matrix_bot:matrix.org'. Please note also that the '@' character has a special meaning in YAML, so this must always be given in quotes."
+  required: true
+  type: string
+password:
+  description: The password for your Matrix account.
+  required: true
+  type: string
+homeserver:
+  description: "The full URL for your homeserver. If you use the defauls matrix.org homeserver, this is 'https://matrix.org'."
+  required: true
+  type: string
+verify_ssl:
+  description: Verify the homeservers certificate.
+  required: false
+  type: string
+  default: true
+rooms:
+  description: "The list of rooms that the bot should join and listen for commands (see below) in. While you can limit the list of rooms that a certain command applies to on a per-command basis (see below), you must still list all rooms here that commands should be received in. Rooms can be given either by their internal ID (e.g., '!cURbafjkfsMDVwdRDQ:matrix.org') or any of their aliases (e.g., '#matrix:matrix.org')."
+  required: false
+  type: [string]
+  default: empty
+commands:
+  description: "A list of commands that the bot should listen for. If a command is triggered (via its *word* or *expression*, see below), an event is fired that you can handle using automations. Every command consists of these possible configuration options:"
+  required: false
+  type: map
+  default: empty
+  keys:
+    word:
+      description: "Specifies a word that the bot should listen for. If you specify 'my_command' here, the bot will react to any message starting with '!my_command'."
+      required: false
+      type: string
+    expression:
+      description: "Specifies a regular expression (in python regexp syntax) that the bot should listen to. The bot will react to any message that matches the regular expression."
+      required: false
+      type: string
+    name:
+      description: "The name of the command. This will be an attribute of the event that is fired when this command triggers."
+      required: true
+      type: string
+    rooms:
+      description: "A list of rooms that the bot should listen for this command in. If this is not given, the *rooms* list from the main config is used. Please note that every room in this list must also be in the main *room* config."
+      required: false
+      type: [string]
+      default: empty
+{% endconfiguration %}
+
+### {% linkable_title Event Data %}
+
+If a command is triggered, a `matrix_command` event is fired. The event contains the name of the command in the `name` field. If the command is a word command that has no name set, the `name` field contains the word instead.
+
+If the command is a word command, the `data` field contains a list of the command's arguments, i.e., everything that stood behind the word, split at spaces. If the command is an expression command, the `data` field contains the [group dictionary](https://docs.python.org/3.6/library/re.html?highlight=re#re.match.groupdict) of the regular expression that matched the message.
+
+### {% linkable_title Comprehensive Configuration Example %}
+
+This example also uses the [matrix `notify` platform](/components/notify.matrix/).
+
+```yaml
+# The Matrix component
+matrix:
+  homeserver: https://matrix.org
+  username: "@my_matrix_user:matrix.org"
+  password: supersecurepassword
+  rooms:
+    - "#hasstest:matrix.org"
+    - "#someothertest:matrix.org"
+  commands:
+    - word: testword
+      rooms:
+        - "#someothertest:matrix.org"
+    - expression: "My name is (?P<name>.*)"
+      name: introduction
+
+notify:
+  - name: matrix_notify
+    platform: matrix
+    default_room: "#hasstest:matrix.org"
+
+automation:
+  - alias: 'React to !testword'
+    trigger:
+      platform: event
+      event_type: matrix_command
+      event_data:
+        command: testword
+    action:
+      service: notify.matrix_notify
+      data:
+        message: 'It looks like you wrote !testword'
+  - alias: 'React to an introduction'
+    trigger:
+      platform: event
+      event_type: matrix_command
+      event_data:
+        command: introduction
+    action:
+      service: notify.matrix_notify
+      data_template:
+        message: "Hello {{trigger.event.data.name}}"
+```
+
+This configuration will:
+- Listen for "!testword" in the room "#someothertest:matrix.org" (and *only*) there. If such a message is encountered, it will answer with "It looks like you wrote !testword" into the "#hasstest:matrix.org" channel.
+- Listen in both rooms for any message matching "My name is <any string>" and answer with "Hello <the string>" into "#hasstest:matrix.org".

source/_components/maxcube.markdown

@@ -25,13 +25,42 @@ Supported Devices:
 - MAX! Window Sensor (tested)
 - MAX! Wall Thermostat (tested)
 
+### {% linkable_title One Gateway %}
+
 A `maxcube` section must be present in the `configuration.yaml` file and contain the following options as required:
 
 ```yaml
 # Example configuration.yaml entry
 maxcube:
-  host: 192.168.0.20
+  gateways:
+    - host: 192.168.0.20
 ```
-Configuration variables:
-- **host** (*Required*): The IP address of the eQ-3 MAX! Cube to use.
-- **port** (*Optional*): The UDP port number. Defaults to `62910`.
+
+### {% linkable_title Multiple Gateways %}
+
+```yaml
+# Example configuration.yaml entry
+maxcube:
+  gateways:
+    - host: 192.168.0.20
+      port: 62910
+    - host: 192.168.0.21
+      port: 62910
+```
+
+{% configuration %}
+  host:
+    description: The IP address of the eQ-3 MAX! Cube to use.
+    required: true
+    type: string
+  port:
+    description: The UDP port number.
+    required: false
+    type: int
+    default: 62910
+  scan_interval:
+    description: The update interval in seconds
+    required: false
+    type: int
+    default: 300
+{% endconfiguration %}

source/_components/media_player.blackbird.markdown

@@ -0,0 +1,70 @@
+---
+layout: page
+title: "Blackbird 8x8 HDMI Matrix Switch"
+description: "Instructions on how to integrate Monoprice Blackbird 4k 8x8 HDBaseT Matrix Switch into Home Assistant."
+date: 2018-03-29 16:35
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: monoprice.svg
+ha_category: Media Player
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+The `blackbird` platform allows you to control [Monoprice Blackbird Matrix Switch](https://www.monoprice.com/product?p_id=21819) using a serial connection.
+
+To add a Blackbird device to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+  - platform: blackbird
+    type: serial
+    port: /dev/ttyUSB0
+    zones:
+      1:
+        name: Living Room
+    sources:
+      3: 
+        name: BluRay
+```
+
+{% configuration %}
+type:
+  description: The type of device connection - serial or socket
+  required: true
+  type: string
+port: 
+  description: The serial port to which Blackbird matrix switch is connected. Either port or host must be defined.
+  required: optional
+  type: string
+host:
+  description: The IP address of the Blackbird matrix switch. Either port or host must be defined.
+  required: optional
+  type: string
+zones:
+  description: This is the list of zones available. Valid zones are 1,2,3,4,5,6,7,8. Each zone must have a name assigned to it.
+  required: true
+  type: int
+  keys:
+    name:
+      description: The name of the zone.
+sources:
+  description: The list of sources available. Valid source numbers are 1,2,3,4,5,6,7,8. Each source number corresponds to the input number on the Blackbird matrix switch. Similar to zones, each source must have a name assigned to it.
+  required: true
+  type: int
+  keys:
+    name:
+      description: The name of the source.
+{% endconfiguration%}
+
+### {% linkable_title Service `BLACKBIRD_SETALLZONES` %}
+
+Set all zones to the same input source. This service allows you to immediately synchronize all the TVs in your home. Regardless of `entity_id` provided, all zones will be updated. 
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String that points at an `entity_id` of a zone.
+| `source` | no | String of source name to activate.

source/_components/media_player.kodi.markdown

@@ -17,7 +17,9 @@ ha_iot_class: "Local Push"
 
 The `kodi` platform allows you to control a [Kodi](http://kodi.tv/) multimedia system from Home Assistant.
 
-To add Kodi to your installation, add the following to your `configuration.yaml` file:
+The preferred way to set up the Kodi platform is by enabling the [discovery component](https://www.home-assistant.io/components/discovery/) which requires enabled [web interface](https://kodi.wiki/view/Web_interface) on your Kodi installation.
+
+In case the discovery does not work, or you need specific configuration variables, you can add the following to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry

source/_components/media_player.onkyo.markdown

@@ -16,6 +16,8 @@ ha_iot_class: "Local Polling"
 
 The `onkyo` platform allows you to control a [Onkyo](http://www.onkyo.com/) and some recent [Pioneer](http://www.pioneerelectronics.com) receivers from Home Assistant. Please be aware that you need to enable "Network Standby" for this component to work in your Hardware.
 
+## {% linkable_title Configuration %}
+
 To add an Onkyo or Pioneer receiver to your installation, add the following to your `configuration.yaml` file:
 
 ```yaml
@@ -28,11 +30,28 @@ media_player:
       pc: 'HTPC'
 ```
 
-Configuration variables:
-
-- **host** (*Optional*): IP address of the device. Example:`192.168.1.2`. If not specified, the platform will load any discovered receivers.
-- **name** (*Required if host is specified*): Name of the device.
-- **sources** (*Optional*): A list of mappings from source to source name. Valid sources can be found below. A default list will be used if no source mapping is specified.
+{% configuration %}
+host:
+  description: IP address of the device. Example:`192.168.1.2`. If not specified, the platform will load any discovered receivers.
+  required: false
+  type: string
+name:
+  description: Name of the device. (*Required if host is specified*)
+  required: false
+  type: string
+max_volume:
+  description: Maximum volume. Defaults to 80.
+  required: false
+  type: number
+sources:
+  description: A list of mappings from source to source name. Valid sources can be found below. A default list will be used if no source mapping is specified.
+  required: false
+  type: list
+zone2:
+  description: Enables control for the receiver's second zone.
+  required: false
+  type: bool
+{% endconfiguration %}
 
 List of source names:
 

source/_components/media_player.samsungtv.markdown

@@ -50,6 +50,7 @@ Currently known supported models:
 - EH5600
 - F6400AF
 - F6400
+- F8000BF
 - D6505
 - D6300SF
 - U6000 (port must be set to 8001)

source/_components/media_player.volumio.markdown

@@ -12,12 +12,11 @@ ha_category: Media Player
 ha_release: 0.41
 ---
 
-The `Volumio` platform allows you to control a [Volumio](http://volumio.org) media player
-from Home Assistant.
+The `Volumio` platform allows you to control a [Volumio](http://volumio.org) media player from Home Assistant.
 
+The preferred way to set up the Volumio platform is by enabling the [discovery component](/components/discovery/).
 
-To add a Volumio player to your installation, add the following to
-your `configuration.yaml` file.
+In case the discovery does not work, or you need specific configuration variables, you can add the following to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry

source/_components/media_player.webostv.markdown

@@ -19,7 +19,7 @@ The `webostv` platform allows you to control a [LG](http://www.lg.com/) webOS Sm
 
 To begin with enable *LG Connect Apps* feature in *Network* settings of the TV [instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others).
 
-Once basic configuration is added to your `configuration.yaml` *Configuration* card should prompt on your HA's States. Follow the instructions and accept pairing request on your TV.
+Once basic configuration is added to your `configuration.yaml` *Configuration* card should prompt on your Home Assistants's states. Follow the instructions and accept pairing request on your TV.
 
 Pairing information will be saved to the `filename:` provided in configuration; this process is IP sensitive, in case the IP address of your TV would change in future.
 
@@ -42,10 +42,12 @@ Configuration variables:
 - **timeout** (*Optional*): The timeout for connections to the TV in seconds.
 - **filename** (*Optional*): The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. It defaults to `webostv.conf`.
 - **customize** array (*Optional*): List of options to customize.
-  - ***sources** array (*Optional*): List of hardware and webOS App inputs.
+  - **sources** array (*Optional*): List of hardware and webOS App inputs.
 
 If you do not specify `host:`, all LG webOS Smart TVs within your network will be auto-discovered.
 
+### {% linkable_title Example %}
+
 A full configuration example will look like the sample below:
 
 ```yaml
@@ -53,7 +55,7 @@ A full configuration example will look like the sample below:
 media_player:
   - platform: webostv
     host: 192.168.0.10
-    name: Living Room TV  
+    name: Living Room TV
     timeout: 5
     filename: webostv.conf
     turn_on_action:
@@ -67,15 +69,15 @@ media_player:
         - makotv
         - netflix
 ```
-** avoid using `[ ]` in the `name:` of your device.
 
+Avoid using `[ ]` in the `name:` of your device.
 
-*Turn On Action*
+### {% linkable_title Turn on action %}
 
 Home Assistant is able to turn on a LG webOS Smart TV if you specify an action, like HDMI-CEC or WakeOnLan.
 
-Common for webOS 3.0 and higher would be to use WakeOnLan feature. 
-To use this feature your TV should be connected to your network via Ethernet rather than Wireless and you should enable *LG Connect Apps* feature in *Network* settings of the TV [instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others) (or *Mobile App* in *General* settings for older models) (*may vary by version).
+Common for webOS 3.0 and higher would be to use WakeOnLan feature.
+To use this feature your TV should be connected to your network via Ethernet rather than Wireless and you should enable *LG Connect Apps* feature in *Network* settings of the TV [instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others) (or *Mobile App* in *General* settings for older models).
 
 ```yaml
 # Example configuration.yaml entry
@@ -90,9 +92,40 @@ media_player:
       data:
         mac: B4:E6:2A:1E:11:0F
 ```
-Any other [actions](/docs/automation/action/) to power on the device can be configured. 
 
+Any other [actions](/docs/automation/action/) to power on the device can be configured.
 
-*Sources*
+### {% linkable_title Sources %}
 
 To obtain complete list of available sources currently configured on the TV, once the webOS TV is configured and linked, while its powered on head to the **Developer Tools** > **States**, find your `media_player.<name>` and use the sources listed in `source_list:` remembering to split them per line into your `sources:` configuration.
+
+### {% linkable_title Change channel through play_media service %}
+
+The `play_media` service can be used in a script to switch to the specified tv channel.
+It selects the best matching cannel according to the `media_content_id` parameter:
+ 1. Channel number *(i.e. '1' or '6')*
+ 2. Exact channel name *(i.e. 'France 2' or 'CNN')*
+ 3. Substring in channel name *(i.e. 'BFM' in 'BFM TV')*
+
+```yaml
+# Example action entry in script to switch to channel number 1
+service: media_player.play_media
+data:
+  entity_id: media_player.lg_webos_smart_tv
+  media_content_id: 1
+  media_content_type: "channel"
+
+# Example action entry in script to switch to channel including 'TF1' in its name
+service: media_player.play_media
+data:
+  entity_id: media_player.lg_webos_smart_tv
+  media_content_id: "TF1"
+  media_content_type: "channel"
+```
+
+### {% linkable_title Next/Previous buttons %}
+
+The behaviour of the next and previsous buttons is different depending on the active source:
+
+ - if the source is 'LiveTV' (television): next/previous buttons act as channel up/down
+ - otherwise: next/previsous buttons act as next/previous track

source/_components/mercedesme.markdown

@@ -23,29 +23,5 @@ This component provides the following platforms:
  - Device tracker: To track location of your car.
 
 <p class='note warning'>
-  The component can integrate cars from European and African markets only.
-</p>
-
-To use Mercedes me in your installation, add the following to your `configuration.yaml` file:
-
-```yaml
-# Example configuration.yaml entry
-mercedesme:
-  username: YOUR_E_MAIL_ADDRESS
-  password: YOUR_PASSWORD
-```
-
-{% configuration %}
-username:
-  description: The email address associated with your Mercedes me account.
-  required: true
-  type: string
-password:
-  description: The password for your given Mercedes me account.
-  required: true
-  type: string
-{% endconfiguration %}
-
-<p class='note'>
-The requirement `lxml` has to be [installed](http://lxml.de/installation.html) manually `pip install lxml` on some devices.
+  The component was removed. The vendor disabled the API endpoint and a new API is not available currently.
 </p>

source/_components/mochad.markdown

@@ -13,6 +13,8 @@ ha_release: 0.32
 
 The `mochad` component is the main component to integrate all X10 platforms being controlled by [mochad](https://sourceforge.net/projects/mochad/). Besides this component you will have to setup your X10 devices separately.
 
+## {% linkable_title Configuration %}
+
 To integrate your Mochad units with Home Assistant, add the following section to your `configuration.yaml` file:
 
 ```yaml
@@ -20,10 +22,20 @@ To integrate your Mochad units with Home Assistant, add the following section to
 mochad:
 ```
 
-Configuration variables:
+{% configuration %}
+host:
+  description: The host that mochad is running on.
+  required: false
+  type: string
+  default: localhost
+port:
+  description: The port that mochad is running on.
+  required: false
+  type: int
+  default: 1099
+{% endconfiguration %}
 
-- **host** (*Optional*): The host that mochad is running on. Defaults to `localhost`.
-- **port** (*Optional*): The port that mochad is running on. Defaults to `1099`.
+## {% linkable_title Example %}
 
 A full configuration sample could look like the one below:
 

source/_components/modbus.markdown

@@ -16,6 +16,8 @@ ha_iot_class: "Local Push"
 
 [Modbus](http://www.modbus.org/) is a serial communication protocol to control PLCs (Programmable logic controller). It currently supports sensors and switches which can be controlled over serial, TCP, and UDP connections.
 
+## {% linkable_title Configuration %}
+
 To add modbus to your installation, add the following to your `configuration.yaml` file:
 
 For a network connection:

source/_components/mqtt.markdown

@@ -33,6 +33,10 @@ mqtt:
   broker: IP_ADDRESS_BROKER
 ```
 
+<p class='note'>
+The minimal setup uses the embedded MQTT broker, however a separate broker is advised for more stability.
+</p>
+
 ## {% linkable_title Additional features %}
 
 - [Certificate](/docs/mqtt/certificate/)

source/_components/notify.clicksend.markdown

@@ -15,9 +15,12 @@ ha_release: 0.48
 
 The `clicksend` platform uses [ClickSend](https://clicksend.com) to deliver notifications from Home Assistant.
 
-### Get your ClickSend API Credentials
+## {% linkable_title Prerequisites %}
+
 Go to your [ClickSend Dashboard](https://dashboard.clicksend.com) section and create your new project. After creating your project, you should now be able to obtain your `username` and `api_key`.
 
+## {% linkable_title Configuration %}
+
 To add ClickSend to your installation, add the following to your Home Assistant `configuration.yaml` file:
 
 ```yaml
@@ -28,6 +31,14 @@ notify:
     username: CLICKSEND_USERNAME
     api_key: CLICKSEND_API_KEY
     recipient: PHONE_NO
+    
+# Multiple recipients
+notify:
+  - platform: clicksend
+    name: ClickSend
+    username: CLICKSEND_USERNAME
+    api_key: CLICKSEND_API_KEY
+    recipient: [PHONE_NO1, PHONE_NO2]
 ```
 
 {% configuration %}
@@ -44,9 +55,9 @@ api_key:
   required: true
   type: string
 recipient:
-  description: "Your phone number. This is where you want to send your notification SMS messages, e.g., `09171234567`."
+  description: "A single or multiple phone numbers. This is where you want to send your SMS notification messages, e.g., `09171234567` or `[09171234567, 09177654321]`."
   required: true
-  type: string
+  type: string or list
 sender:
   description: The name or number of the sender.
   required: false

source/_components/notify.facebook.markdown

@@ -50,7 +50,7 @@ automation:
           - '+919784516314'
 ```
 
-You can also send messages to users that do not have stored their phone number with Facebook, but this requires a bit more work. The Messenger platform uses page specific user IDs instead of a global user ID. You will need to enable a webhook for the "messages" event in Facebook's developer console. Once a user writes a message to a page, that webhook will then receive the user's page specific ID as part of the webhook's payload. Below is a simple PHP script that reacts to the message "get my id" and sends a reply containing the user's ID: 
+You can also send messages to users that do not have stored their phone number on Facebook, but this requires a bit more work. The Messenger platform uses page-specific user IDs instead of a global user ID. You will need to enable a webhook for the "messages" event in Facebook's developer console. Once a user writes a message to a page, that webhook will then receive the user's page specific ID as part of the webhook's payload. Below is a simple PHP script that reacts to the message "get my id" and sends a reply containing the user's ID: 
 
 ```php
 <?php
@@ -96,10 +96,10 @@ if (preg_match('/get my id/', strtolower($message))) {
 ```
 
 ### {% linkable_title Rich messages %}
-You could also send rich messing (cards, buttons, images, videos, etc). [Info](https://developers.facebook.com/docs/messenger-platform/send-api-reference) to which types or messages and how to build them.
+You could also send rich messing (cards, buttons, images, videos, etc). [Info](https://developers.facebook.com/docs/messenger-platform/send-api-reference) to which types of messages and how to build them.
 
 ```yaml
-# Example script with a notification entry with rich message
+# Example script with a notification entry with a rich message
 
 script:
   test_fb_notification:
@@ -117,3 +117,21 @@ script:
                 title: Blue
                 payload: DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLUE
 ```
+
+You can now also use Facebook public beta broadcast API to push messages to ALL users who interacted with your chatbot on your page, without having to collect their number. This will scale to thousands of users. Facebook requires that this only be used for non-commercial purposes and they validate every message you send. Also note, your Facebook bot needs to be authorized for "page_subscritions" if you want to make it to all but can be used right away to a selected group of testers of your choice. 
+
+To enable broadcast just use the keyword "BROADCAST" as your target. Only put ONE target BROADCAST as below:
+
+```yaml
+- alias: Facebook Broadcast
+  trigger:
+    platform: sun
+    event: sunset
+  action:
+    service: notify.facebook
+    data:
+      message: Some text you want to send
+      target:
+        - BROADCAST
+```
+

source/_components/notify.mastodon.markdown

@@ -0,0 +1,52 @@
+---
+layout: page
+title: "Mastodon"
+description: "Instructions on how to add Instapush notifications to Home Assistant."
+date: 2018-03-25 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mastodon.png
+ha_category: Notifications
+ha_release: 0.67
+---
+
+
+The `mastodon` platform uses [MAstodon](https://joinmastodon.org/) to delivery notifications from Home Assistant.
+
+Go to **Preferences** in the Mastodon web interface, then to **Development** and create a new application.
+
+To add Mastodon to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+notify:
+  - name: NOTIFIER_NAME
+    platform: mastodon
+    access_token: !secret mastodon_access_token
+    client_id: !secret mastodon_client_id
+    client_secret: !secret mastodon_client_secret
+```
+
+{% configuration %}
+access_token:
+  description: Your Mastodon access token.
+  required: true
+  type: string
+client_id:
+  description: Your Mastodon client ID
+  required: true
+  type: string
+client_secret:
+  description: Your Mastodon client secret.
+  required: true
+  type: string
+base_url:
+  description: URL of the Mastodon instance to use.
+  required: false
+  type: string
+  default: https://mastodon.social
+{% endconfiguration %}
+
+To use notifications, please see the [getting started with automation page](/getting-started/automation/).

source/_components/notify.matrix.markdown

@@ -17,27 +17,21 @@ The `matrix` platform allows you to deliver notifications from Home Assistant to
 
 ## {% linkable_title Configuration %}
 
-To enable Matrix notifications in your installation, add the following to your `configuration.yaml` file:
+To enable Matrix notifications in your installation, you first need to configure
+the [Matrix component](/components/matrix/). Then, add the following to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry
 notify:
   - name: NOTIFIER_NAME
     platform: matrix
-    homeserver: HOMESERVER
-    username: YOUR_USERNAME
-    password: YOUR_PASSWORD
     default_room: ROOM_ID_OR_ALIAS
 ```
 
 Configuration variables:
 
 - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
-- **homeserver** (*Required*): The base URL of the homeserver, where the notifier account is registered (e.g., `https://matrix.org`).
-- **username** (*Required*): The username of the notifying Matrix account.
-- **password** (*Required*): The password for the given Matrix account.
 - **default_room** (*Required*): The room all messages will be sent to, when no other target is given.
-- **verify_ssl** (*Optional*): Verify the homeservers certificate. Defaults to `true`.
 
 The target room has to be precreated, the room id can be obtained from the rooms settings dialog. Rooms by default have a canonical id of the form `"!<randomid>:homeserver.tld"`, but can also be allocated aliases like `"#roomname:homeserver.tld"`. Make sure to use quotes around the room id or alias to escape special characters (`!`, and `#`) in YAML. The notifying account may need to be invited to the room, depending on the individual rooms policies.
 

source/_components/notify.pushover.markdown

@@ -15,7 +15,9 @@ ha_release: pre 0.7
 
 The [Pushover service](https://pushover.net/) is a platform for the notify component. This allows components to send messages to the user using Pushover.
 
-In order to get an API key you need to go to the [Pushover website](https://pushover.net) and register a new application. From the website you can also retrieve your user key.
+## {% linkable_title Configuration %}
+
+In order to get an API key you need to [register an application](https://pushover.net/apps/clone/home_assistant) on the Pushover website. Your Pushover user key can be found on the [Pushover dashboard](https://pushover.net/dashboard).
 
 To use Pushover notifications, add the following to your `configuration.yaml` file:
 
@@ -35,6 +37,7 @@ Configuration variables:
 - **user_key** (*Required*): Your user key for Pushover.
 
 Example Automation:
+
 ```yaml
 - service: notify.entity_id
       data:
@@ -45,22 +48,16 @@ Example Automation:
           sound: pianobar
           priority: 0
 ```
+
 Component specific values in the nested `data` section are optional.
 
-This is a quote from the Pushover website regarding free/open source apps:
-
-<blockquote>
-  If you are creating a client-side library, application, or open source project that will be redistributed and installed by end-users, you may want to require each of your users to register their own application rather than including your own API token with the software.
-</blockquote>
-
-When setting up the application you can use this [icon](/images/favicon-192x192.png).
-
 To use notifications, please see the [getting started with automation page](/getting-started/automation/).
 
 When sending a notification, optional parameters can also be set as per the pushover [API documentation](https://pushover.net/api).
 
 Example notification triggered from the Alexa component for an intents is shown below which also uses [Automation Templating](/getting-started/automation-templating/) for the message:
 
+{% raw %}
 ```yaml
 # Example configuration.yaml entries
 alexa:
@@ -69,7 +66,7 @@ alexa:
       action:
         service: notify.notify
         data_template:
-          message: "The location of {% raw %}{{ User }}{% endraw %} has been queried via Alexa."
+          message: "The location of {{ User }} has been queried via Alexa."
         data:
           title: "Home Assistant"
           data:
@@ -77,3 +74,4 @@ alexa:
             device: pixel
             url: "https://www.home-assistant.io/"
 ```
+{% endraw %}

source/_components/notify.rest.markdown

@@ -30,6 +30,7 @@ Configuration variables:
 - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
 - **resource** (*Required*): The resource or endpoint that will receive the value.
 - **method** (*Optional*): The method of the request. Default is GET.
+- **headers** (*Optional*): The headers for the request.
 - **message_param_name** (*Optional*): Parameter name for the message. Defaults to `message`.
 - **title_param_name** (*Optional*): Parameter name for the title. Defaults to none.
 - **target_param_name** (*Optional*): Parameter name for the target. Defaults to none.

source/_components/persistent_notification.markdown

@@ -55,6 +55,26 @@ action:
     notification_id: "1234"
 ```
 
+
+### {% linkable_title Markdown support %}
+
+The message attribute supports the [Markdown formatting syntax](https://daringfireball.net/projects/markdown/syntax). Some examples are:
+
+| Type | Message |
+| ---- | ------- |
+| Headline 1 | `# Headline` |
+| Headline 2 | `## Headline` |
+| Newline | `\n` |
+| Bold | `**My bold text**` |
+| Cursive | `*My cursive text*` |
+| Link | `[Link](https://home-assistant.io/)` |
+| Image | `![image](/local/my_image.jpg)` |
+
+<p class="note">
+  `/local/` in this context refers to the `.homeassistant/www/` folder.
+</p>
+
+
 ### {% linkable_title Create a persistent notification %}
 
 Choose <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> **Services** from the **Developer Tools** to call the `persistent_notification` service. Select `persistent_notification/create` from the list of **Available services:** and enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**.

source/_components/pilight.markdown

@@ -19,19 +19,19 @@ This pilight hub connects to the [pilight-daemon](https://manual.pilight.org/pro
 
 The received and supported RF codes are put on the event bus of Home Assistant and are therefore directly usable by other components (e.g., automation). Additionally a send service is provided to send RF codes.
 
+## {% linkable_title Configuration %}
+
 To integrate pilight into Home Assistant, add the following section to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry
 pilight:
-  host: 127.0.0.1
-  port: 5000
 ```
 
 Configuration variables:
 
-- **host** (*Required*): The IP address of the computer running the pilight-daemon, e.g., 192.168.1.32.
-- **port** (*Required*): The network port to connect to. The usual port is [5000](https://manual.pilight.org/development/api.html).
+- **host** (*Optional*): The IP address of the computer running the pilight-daemon, e.g., 192.168.1.32.
+- **port** (*Optional*): The network port to connect to. The usual port is [5001](https://manual.pilight.org/development/api.html).
 - **send_delay** (*Optional*): You can define a send delay as a fraction of seconds if you experience transmission problems when you try to switch multiple switches at once. This can happen when you use a [pilight USB Nano](https://github.com/pilight/pilight-usb-nano) as hardware and switches a whole group of multiple switches on or off. Tested values are between 0.3 and 0.8 seconds depending on the hardware.
 - **whitelist** (*Optional*): You can define a whitelist to prevent that too many unwanted RF codes (e.g., the neighbors weather station) are put on your HA event bus. All defined subsections have to be matched. A subsection is matched if one of the items are true.
 

source/_components/qwikswitch.markdown

@@ -13,12 +13,9 @@ featured: false
 ha_release: "0.20"
 ---
 
+The `qwikswitch` component is the main component to integrate various [QwikSwitch](http://www.qwikswitch.co.za/) devices with Home Assistant. The integration requires the QSUSB Modem device and connects to the QS Mobile application.
 
-The `qwikswitch` component is the main component to integrate various [QwikSwitch](http://www.qwikswitch.co.za/) devices with Home Assistant.
-
-Loading the `qwikswitch` component automatically adds all devices from the QS Mobile application. QS Mobile controls the QSUSB Modem device.
-
-Currently QwikSwitch relays and LED dimmers are supported (tested). QwikSwitch relay devices can be [switches](/components/switch.qwikswitch/) or [lights](/components/light.qwikswitch/) in Home-Assistant. If the device name in the QSUSB app ends with ` Switch` it will be created as a switch, otherwise as a light.
+The `qwikswitch` component discovers all devices from QS Mobile. Currently, Relays and LED dimmers are discovered in Home Assistant. Relay devices are [lights](/components/light.qwikswitch/) by default, and can be configured as [switches](/components/switch.qwikswitch/).
 
 Example configuration:
 
@@ -31,28 +28,67 @@ qwikswitch:
 Configuration variables:
 
 - **url** (*Required*): The URL including the port of your QwikSwitch hub.
-- **dimmer_adjust** (*Optional*): A decimal value to adjust the brightness of the dimmer exponentially. Increasing this value allows dimmers that reaches full brightness with low values in QS Mobile to appear more linear in Home Assistant. Recommended values between 1 and 2 and the default is 1.
-- **button_events** (*Optional*): A comma separated list of button types that will generate events. Details below.
+- **dimmer_adjust** (*Optional*): A decimal value to adjust the brightness of the dimmer exponentially. Increasing this value allows dimmers that reach full brightness with low values in QS Mobile to appear more linear in Home Assistant. Recommended values between 1 and 2 and the default is 1.
+- **button_events** (*Optional*): A comma-separated list of button types that will generate events. See [QwikSwitch Events] for detail.
+- **switches** (*Optional*): A list of device QS_id's that should be switches, and not lights (i.e. `['@0dev01', '@0dev02']`)
+- **sensors** (*Optional*): A dictionary of sensors. In the format of {entity_id: QS_id}. (i.e. `{door_sensor: '@0dev03'}`)
 
-### {% linkable_title QwikSwitch Buttons %}
+### {% linkable_title QwikSwitch Events %}
 
-QwikSwitch devices (i.e. transmitter buttons) will fire events on the Home Assistant bus. These events can then be used as triggers for any `automation` action, as follows:
+QwikSwitch devices (i.e., transmitter buttons) will fire events on the Home Assistant bus. These events can then be used as triggers for any `automation` action, as follows:
 
 ```yaml
 automation:
-  - alias: Action - Respond to button press
+  - alias: Action - Respond to A button press
     trigger:
       platform: event
       event_type: qwikswitch.button.@12df34
 ```
 
-`event_type` names should be in the format **qwikswitch.button.@__ID__**. where **@__ID__** will be captured in the Home Assistant log when pressing the button. Alternatively, you can also get the device ID from the QS Mobile application or using the listen API call by browsing to `http://127.0.0.1:2020/&listen` and then pressing the button.
+`event_type` names should be in the format **qwikswitch.button.@_QS_id_**. where **@_QS_id_** will be captured in the Home Assistant log when pressing the button. Alternatively, you can also get the device ID from the QS Mobile application or by using the listen API call by browsing to `http://127.0.0.1:2020/&listen` and then pressing the button.
+
+The full packet from the QSUSB API will be passed as `data`
 
 By default events will be fired if the value in the command (cmd) field of the listen packet equals:
 - `TOGGLE` - Normal QwikSwitch Transmitter button
 - `SCENE EXE` - QwikSwitch Scene Transmitter buttons
 - `LEVEL` - QwikSwitch OFF Transmitter buttons
 
-The list of recognized commands can be extended for Keyfobs, door sensors, and PIR transmitters with the **button_events** configuration option. **button_events** contain a comma separated list of commands that will fire Home Assistant events. By default it is: TOGGLE,SCENE EXE,LEVEL.
+The list of recognized commands can be extended for Keyfobs, door sensors, and PIR transmitters with the **button_events** configuration option. **button_events** can be a list or comma separated list of additional commands that will fire Home Assistant events. By default, it is: TOGGLE,SCENE EXE,LEVEL.
 
 On some QS Mobile servers button events are only generated for switches added to the QS Mobile application, so it might be best to test button presses through the `/&listen` API
+
+### {% linkable_title Qwikswitch Sensors %}
+
+The sensor configuration is a list of sensors. Depending on the type, it will be a sensor or binary_sensor. Each sensor is configured with the following parameters:
+
+- **name** (*Required*): The sensor name from which the entity_id will be derived.
+- **id** (*Required*): A QS_Id
+- **type** (*Required*): The Qwikswitch sensor type. These could include:
+   - imod (binary_sensor, up to 6 channels)
+   - door (binary_sensor, single channel)
+   - qwikcord (Channel 1 = CTavg, Channel 2 = CTsum)
+- **channel** (*Optional, default=1*): The channel of interest. Refer to type above.
+
+The following parameters are only applicabe to binary_sensors (i.e. door/imod).
+- **invert** (*Optional, default=False): Invert the open/close state. 
+- **class** (*Optional, default=door): The [class](https://www.home-assistant.io/components/binary_sensor) or binary_sensor.
+
+Example sensor configuration:
+
+```yaml
+qwikswitch:
+  ...
+  sensors:
+    - name: door sensor
+      id: "@id03"
+      type: door
+    - name: Imod 1 sensor
+      id: "@id02"
+      channel: 1
+      type: imod
+    - name: Imod 2 sensor
+      id: "@id02"
+      channel: 2
+      type: imod
+```

source/_components/rainmachine.markdown

@@ -0,0 +1,71 @@
+---
+layout: page
+title: "RainMachine"
+description: "Instructions on how to integrate RainMachine units within Home Assistant."
+date: 2018-04-25 20:32
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: rainmachine.png
+ha_category: Hub
+ha_release: 0.69
+ha_iot_class: "Cloud Polling"
+---
+
+The `rainmachine` component is the main component to integrate all platforms
+related to [RainMachine smart Wi-Fi sprinkler controllers](http://www.rainmachine.com/).
+
+## {% linkable_title Base Configuration %}
+
+To connect to your RainMachine device, add the following to your
+`configuration.yaml` file:
+
+```yaml
+rainmachine:
+  ip_address: 192.168.1.100
+  password: YOUR_PASSWORD
+```
+
+To configure switch-related functionality, add configuration options beneath
+a `switches` key within the `rainmachine` sections of `configuration.yaml`
+as below:
+
+```yaml
+rainmachine:
+  ip_address: 192.168.1.100
+  password: YOUR_PASSWORD
+  switches:
+    # switch configuration options...
+```
+
+{% configuration %}
+ip_address:
+  description: the IP address or hostname of your RainMachine unit
+  required: optional
+  type: string
+password:
+  description: your RainMachine password.
+  required: true
+  type: string
+port:
+  description: the TCP port used by your unit for the REST API
+  required: false
+  type: int
+  default: 8080
+ssl:
+  description: whether communication with the local device should occur over HTTPS
+  required: false
+  type: boolean
+  default: true
+switches:
+  description: switch-related configuration options
+  required: false
+  type: map
+  keys:
+    zone_run_time:
+      description: the default number of seconds that a zone should run when turned on
+      required: false
+      type: int
+      default: 600
+{% endconfiguration %}