Merge branch 'current' into next

source/_components/binary_sensor.mqtt.markdown

@@ -46,7 +46,7 @@ An extended configuration for the same sensor could look like this if you want/n
 ```yaml
 # Example configuration.yml entry
 binary_sensor:
-  platform: mqtt
+  - platform: mqtt
     state_topic: "home-assistant/window/contact"
     name: "Windows contact"
     qos: 0

source/_components/mysensors.markdown

@@ -176,6 +176,6 @@ void receive(const MyMessage &message) {
 Sending a heartbeat from the MySensors device to Home Assistant activates the SmartSleep functionality in Home Assistant. This means that messages are buffered and only sent to the device upon receiving a heartbeat from the device. State changes are stored so that only the last requested state change is sent to the device. Other types of messages are queued in a FIFO queue. SmartSleep is useful for battery powered actuators that are waiting for commands.  See the MySensors library API for information on how to send heartbeats and sleep device.  
 
 
-Visit the [library api] of MySensors for more information.
+Visit the [library api][MySensors library api] of MySensors for more information.
 
 [MySensors library api]: http://www.mysensors.org/download

source/_components/notify.html5.markdown

@@ -37,7 +37,7 @@ Configuration variables:
 - Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain.
 - After that, go to [https://console.firebase.google.com](https://console.firebase.google.com) and select import Google project, select the project you created.
 - Then, click the cogwheel on top left and select "Project settings".
-- Select Cloud messaging tab if under server key is button Regenerate key, click that.
+- Select 'Cloud Messaging' tab, listed beneath Project Credentials will be your 152 character 'Server Key' and 12 digit ID 'Sender ID'.
 
 
 ### {% linkable_title Requirements %}

source/_components/notify.pushbullet.markdown

@@ -26,7 +26,7 @@ notify:
 
 Configuration variables:
 
-- **api_key** (*Required*): Enter the API key for Pushbullet. Go to https://www.pushbullet.com/ to retrieve your API key.
+- **api_key** (*Required*): Enter the API key for Pushbullet. Go to [https://www.pushbullet.com/#settings/account](https://www.pushbullet.com/#settings/account) to retrieve your API key/access token.
 - **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`.
 
 ### {% linkable_title Usage %}

source/_components/recorder.markdown

@@ -16,7 +16,7 @@ The `recorder` component is storing details in a database which then are handled
 
 Home Assistant uses [SQLAlchemy](http://www.sqlalchemy.org/) as Object Relational Mapper (ORM). This means that you can now use **any** SQL backend for the recorder that is supported by SQLAlchemy, like [MySQL](https://www.mysql.com/), [MariaDB](https://mariadb.org/), or [PostgreSQL](https://www.postgresql.org/).
 
-The default database engine is [SQLite](https://www.sqlite.org/) which doesn't require any configuration. The database is stored in your Home Assistant configuration directory (`.homeassistant`) and called `home-assistant.db`.
+The default database engine is [SQLite](https://www.sqlite.org/) which doesn't require any configuration. The database is stored in your Home Assistant configuration directory (`.homeassistant`) and called `home-assistant_v2.db`.
 
 To setup the `recorder` component in your installation, add the following to your `configuration.yaml` file:
 

source/_components/script.markdown

@@ -25,9 +25,15 @@ script:
       # This is Home Assistant Script Syntax
       - service: notify.notify
         data_template:
-          message: Current temperature is {% raw %}{{ states.sensor.temperature.state }}{% endraw %}
+          message: Current temperature is {% raw %}{{ states.sensor.temperature.state }}{% endraw %}
+```
+<p class='note'>
+Script names (e.g. `message_temperature` in the example above) are not allowed to contain dash (minus) characters, i.e. `-`.
+The preferred way to separate words for better readability is to use underscore (`_`) characters. 
+</p>
 
-  # Turns on the bedroom lights and then the living room lights 1 minute later
+```yaml
+  # Turns on the bedroom lights and then the living room lights 1 minute later
   wakeup:
     alias: Wake Up
     sequence:

source/_components/sensor.sma.markdown

@@ -14,7 +14,7 @@ ha_release: 0.36
 ---
 
 
-The `sma` sensor will poll a [SMA][http://www.sma-america.com/] solar inverter and present the values as sensors (or attributes of sensors) in Home Assistant.
+The `sma` sensor will poll a [SMA](http://www.sma-solar.com/) [(US)](http://www.sma-america.com/) solar inverter and present the values as sensors (or attributes of sensors) in Home Assistant.
 
 To enable this sensor, add the following lines to your `configuration.yaml` file:
 
@@ -60,7 +60,8 @@ Example:
    custom:
       yesterday_consumption: 
          key: 6400_00543A01
-         unit: W
+         unit: kWh
+         factor: 1000
 ```
 
 Over time more sensors will be added as standard sensors to the [pysma library](https://github.com/kellerza/pysma/blob/master/pysma/__init__.py#L18). Feel free to submit additional sensors on that repository.

source/_components/switch.tplink.markdown

@@ -33,7 +33,7 @@ switch:
 
 Configuration variables:
 
-- **host** (*Required*): The IP address of your myStrom switch, eg. `http://192.168.1.32`.
+- **host** (*Required*): The IP address of your TP-Link switch, eg. `http://192.168.1.32`.
 - **name** (*Optional*): The name to use when displaying this switch.
 
 

source/_components/switch.wake_on_lan.markdown

@@ -51,6 +51,7 @@ from Home Assistant running on another Linux computer (the **server**).
 6. On the **target**, we need to let the hass user execute the program needed to suspend/shut down the target computer. I'm using `pm-suspend`, use `poweroff` to turn off the computer. First, get the full path: `which pm-suspend`. On my system, this is `/usr/sbin/pm-suspend`.
 7. On the **target**, using an account with sudo access (typically your main account), `sudo visudo`. Add this line last in the file: `hass ALL=NOPASSWD:/usr/sbin/pm-suspend`, where you replace `hass` with the name of your user on the target, if different, and `/usr/sbin/pm-suspend` with the command of your choice, if different.
 8. On the **server**, add the following to your configuration, replacing TARGET with the target's name:
+
 ```yaml
 switch:
   - platform: wake_on_lan

source/_cookbook/dim_lights_when_playing_media.markdown

@@ -56,6 +56,7 @@ automation:
       - platform: state
         entity_id: media_player.htpc
         from: 'playing'
+        to: 'idle'
     condition:
       - condition: state
         entity_id: sun.sun
@@ -69,6 +70,7 @@ automation:
       - platform: state
         entity_id: media_player.htpc
         to: 'playing'
+        from: 'idle'
     condition:
       - condition: state
         entity_id: sun.sun

source/_cookbook/sonos_say.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
 title: "Sonos say script to speak with text-to-speech"
-description: "Sonos say script to speak with text-to-speech."
+description: "Sonos say script to use text-to-speech with Sonos"
 date: 2017-01-18 00:00
 sidebar: true
 comments: false
@@ -12,7 +12,7 @@ ha_category: Automation Examples
 
 #### {% linkable_title Sonos say script to speak with text-to-speech %}
 
-This script allow you to use TTS on sonos in a easy way with all features.
+This script allows you to use [TTS](https://home-assistant.io/components/#text-to-speech) on Sonos.
 
 ```yaml
 script:
@@ -21,30 +21,36 @@ script:
     sequence:
      - service: media_player.sonos_snapshot
        data_template:
-         entity_id: {% raw %}{{ sonos_entity }}{% endraw %}
+         entity_id: {% raw %}"{{ sonos_entity }}"{% endraw %}
      - service: media_player.sonos_unjoin
        data_template:
-        entity_id: {% raw %}{{ sonos_entity }}{% endraw %}
+         entity_id: {% raw %}"{{ sonos_entity }}"{% endraw %}
      - service: media_player.volume_set
        data_template:
-       entity_id: {% raw %}{{ sonos_entity }}{% endraw %}
+         entity_id: {% raw %}"{{ sonos_entity }}"{% endraw %}
-       volume_level: {% raw %}{{ volume }}{% endraw %}
+         volume_level: {% raw %}"{{ volume }}"{% endraw %}
      - service: tts.voicerss_say
        data_template:
-       entity_id: {% raw %}{{ sonos_entity }}{% endraw %}
+         entity_id: {% raw %}"{{ sonos_entity }}"{% endraw %}
-       message: {% raw %}{{ message }}{% endraw %}
+         message: {% raw %}"{{ message }}"{% endraw %}
-   - delay: {% raw %}{{ delay }}{% endraw %}
+     - delay: {% raw %}"{{ delay }}"{% endraw %}
      - service: media_player.sonos_restore
        data_template:
-       entity_id: {% raw %}{{ sonos_entity }}{% endraw %}
+         entity_id: {% raw %}"{{ sonos_entity }}"{% endraw %}
 ```
 
 We call this now with:
 ```yaml
-service: script.sonos_say
+automation:
+  - alias: 'test'
+    trigger:
+      - platform: state
+        entity_id: input_boolean.mytest
+    action:   
+      - service: script.sonos_say
         data:
-  sonos_entity: media_player.kitchen
+          sonos_entity: media_player.office
-  volume: 0.3
+          volume: 0.5
           message: 'Your husband comming home!'
           delay: '00:00:05'
 ```

source/_topics/templating.markdown

@@ -22,12 +22,14 @@ Templating is a powerful feature in Home Assistant that allows the user control
 
 - Formatting outgoing messages in, for example, the [notify] and [alexa] components.
 - Process incoming data from sources that provide raw data, like [MQTT], [REST sensor], or the [command line sensor].
+- [Advanced Automation templating]auto-template]
 
 [notify]: /components/notify/
 [alexa]: /components/alexa/
 [MQTT]: /components/mqtt/
 [REST sensor]: /components/sensor.rest/
 [command line sensor]: /components/sensor.command_line/
+[auto-template]: /getting-started/automation-templating/
 
 ## {% linkable_title Building templates %}
 

source/developers/cla.markdown

@@ -41,7 +41,7 @@ and not mention sign-off.
 
 ## Signing
 
-To sign this CLA you must first submit a pull request to a repository under the Home Assistant organization.
+If you have not signed the CLA and you submit a pull request to a repository under the Home Assistant organization, a link will be automatically generated. Just follow the link and the instructions in the link.
 
 ## Adoption
 

source/developers/component_generic_discovery.markdown

@@ -10,13 +10,13 @@ footer: true
 ---
 
 New controller or hub components often need to add platforms in sub-components (i.e. Lights & Switches) without additional configuration.
-This can be achieved using the `homeassistant.components.discovery.load_platform` method:
+This can be achieved using the `load_platform` or `async_load_platform` methods from `homeassistant.helpers.discovery`:
 
 ```python
-def load_platform(hass, component, platform, info=None, hass_config=None)
+def load_platform(hass, component, platform, discovered=None, hass_config=None)
 ```
 
-From more info on how this works, refer to the [load_platform](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L78) method.
+From more info on how this works, refer to the [load_platform](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/discovery.py#L136) method.
 
 ### {% linkable_title Example %}
 
@@ -40,7 +40,7 @@ The source for your component can be located in your configuration directory for
 In the hub component `myflashyhub.py` you can call your light and switch components. To pass any non-serializable information to the platforms in the sub-component, you can use a global variable.
 
 ```python
-from homeassistant.components.discovery import load_platform
+from homeassistant.helpers.discovery import load_platform
 DOMAIN = 'myflashyhub'
 
 MFH_GLOBAL = None
@@ -77,7 +77,3 @@ The `load_platform` method allows the platforms to be loaded with the need for a
 #switch:
 #  platform: myflashyhub
 ```
-
-<p class='note '>
-In the past, this was achieved by adding your component to the `DISCOVERY_PLATFORMS` in the target sub-component. Generic discovery through  `load_platform()` allows you to load any sub-component, including custom components, without changing the sub-component.
-</p>

source/developers/platform_example_light.markdown

@@ -76,11 +76,14 @@ class AwesomeLight(Light):
     def __init__(self, light):
         """Initialize an AwesomeLight."""
         self._light = light
+        self._name = light.name
+        self._state = None
+        self._brightness = None
 
     @property
     def name(self):
         """Return the display name of this light."""
-        return self._light.name
+        return self._name
 
     @property
     def brightness(self):
@@ -89,12 +92,12 @@ class AwesomeLight(Light):
         This method is optional. Removing it indicates to Home Assistant
         that brightness is not supported for this light.
         """
-        return self._light.brightness
+        return self._brightness
 
     @property
     def is_on(self):
         """Return true if light is on."""
-        return self._light.is_on()
+        return self._state
 
     def turn_on(self, **kwargs):
         """Instruct the light to turn on.
@@ -115,4 +118,6 @@ class AwesomeLight(Light):
         This is the only method that should fetch new data for Home Assistant.
         """
         self._light.update()
+        self._state = self._light.is_on()
+        self._brightness = self._light.brightness
 ```

source/developers/platform_example_sensor.markdown

@@ -38,6 +38,10 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 class ExampleSensor(Entity):
     """Representation of a Sensor."""
 
+    def __init__(self):
+        """Initialize the sensor."""
+        self._state = None
+
     @property
     def name(self):
         """Return the name of the sensor."""
@@ -46,10 +50,17 @@ class ExampleSensor(Entity):
     @property
     def state(self):
         """Return the state of the sensor."""
-        return 23
+        return self._state
 
     @property
     def unit_of_measurement(self):
         """Return the unit of measurement."""
         return TEMP_CELSIUS
+
+    def update(self):
+        """Fetch new state data for the sensor.
+
+        This is the only method that should fetch new data for Home Assistant.
+        """
+        self._state = 23
 ```

source/developers/rest_api.markdown

@@ -418,7 +418,7 @@ Sample `curl` command:
 ```bash
 $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
        -H "Content-Type: application/json" \
-       -d '{"entity_id": "switch.christmas_lights", "state": "on"}' \
+       -d '{"entity_id": "switch.christmas_lights"}' \
        http://localhost:8123/api/services/switch/turn_on
 ```
 

source/developers/websocket_api.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
-title: "Websocket API"
+title: "WebSocket API"
-description: "Home Assistant Websocket API documentation"
+description: "Home Assistant WebSocket API documentation"
 date: 2016-11-26 13:27
 sidebar: true
 comments: false
@@ -9,9 +9,11 @@ sharing: true
 footer: true
 ---
 
-Home Assistant contains a websocket API. This API can be used to stream information from a Home Assistant instance to any client that implements websockets. Implementations in different languages:
+Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages:
 
  - [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
+ - [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/)
+ - [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser 
 
 Connect your websocket implementation to `ws://localhost:8123/api/websocket`.
 

source/getting-started/hassbian-installation.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-raspberry-pi-image/
 ---
 
 The easiest way to install Home Assistant on your Raspberry Pi is by using HASSbian: a Raspberry Pi image with Home Assistant built-in. The image will install the latest version of Home Assistant on initial boot (~10 minutes).

source/getting-started/hassbian.markdown

@@ -16,7 +16,7 @@ Hassbian is our customized operating system for the Raspberry Pi 3. It is the ea
  - [Pi specific integrations][integrations]
  - [Learn how to perform common tasks][common]
 
-[install]: /getting-started/hassbian-installatino/
+[install]: /getting-started/hassbian-installation/
 [customize]: /getting-started/hassbian-customization/
 [common]: /getting-started/hassbian-common-tasks/
 [integrations]: /getting-started/hassbian-integrations/

source/getting-started/index.markdown

@@ -31,7 +31,7 @@ You will need to install Home Assistant before we can get started. You can insta
 For advanced users we have several alternative guides for installing Home Assistant.
 
 - [Docker](/getting-started/installation-docker/)
-- [Manual Raspberry Pi installtion](/getting-started/installation-raspberry-pi/) (requires existing Raspbian installation)
+- [Manual Raspberry Pi installation](/getting-started/installation-raspberry-pi/) (requires existing Raspbian installation)
 - [Raspberry Pi All-In-One Installer Script](/getting-started/installation-raspberry-pi-all-in-one/) (requires existing Raspbian installation)
 - [Vagrant](/getting-started/installation-vagrant/)
 - [Synology NAS](/getting-started/installation-synology/)

source/getting-started/installation-raspberry-pi.markdown

@@ -9,20 +9,6 @@ sharing: true
 footer: true
 ---
 
-### {% linkable_title Installation %}
-
-There's currently three documented ways to install Home Assistant on a Raspberry Pi.  
- - [Manual installation](/getting-started/installation-raspberry-pi/#manual-installation). Following this guide doing each step manually. This is highly recommended as a first installation since you get a good overview of the installation.
- - [Hassbian image](/getting-started/installation-raspberry-pi-image). Basic installation with the same settings as following the manual installation guide. Some additional software is preinstalled to make installation quicker and easier. Installation uses `homeassistant` user.
- - [All-in-One Installer](/getting-started/installation-raspberry-pi-all-in-one/). Fabric based installation script that installs and compiles many of the things an advanced Home Assistant install is likely to need. Installation uses `homeassistant` user.
- 
- <p class='note note'>
-  Since each installation type uses a different user for Home Assistant, be sure to note and use the correct username for the `adduser` commands listed below for camera and GPIO extensions.
-</p>
-
-
-### {% linkable_title Manual Installation %}
-
 This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/).
 The installation will be installed in a [Virtual Environment](/getting-started/installation-virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite.
 

source/getting-started/z-wave-controllers.markdown

@@ -20,7 +20,7 @@ Upon first run, the `zwave` component will take time to initialize entities and
 | Device                  | Works on Linux | Works on Windows | Works on OSX |
 |-------------------------|----------------|------------------|--------------|
 | Aeotec Z-Stick Series 2 |   ✓     |                  |              |
-| Aeotec Z-Stick Series 5 |   ✓     |                  |              |
+| Aeotec Z-Stick Series 5 |   ✓     |                  |   ✓   |
 | Pine64 Z-Wave Module    |   ✓     |                  |              |
 | Razberry GPIO Module    |   ✓     |                  |              |
 | ZWave.me UZB1           |   ✓     |                  |              |

source/getting-started/z-wave.markdown

@@ -236,7 +236,7 @@ The `zwave` component exposes multiple services to help maintain the network.
 | print_config_parameter | Prints Z-wave node's config parameter value to the log.
 | remove_node | Put the Z-Wave controller in exclusion mode. Allows one to remove a device from the Z-Wave network.|
 | rename_node | Sets a node's name. Requires an `entity_id` and `name` field. |
-| set_config_parameter | Let's the user set a config parameter to a node.
+| set_config_parameter | Let's the user set a config parameter to a node.|
 | soft_reset | Tells the controller to do a "soft reset". This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.|
 | start_network | Starts the Z-Wave network.|
 | stop_network | Stops the Z-Wave network.|