Merge branch 'current' into next

source/_docs/configuration/basic.markdown

@@ -28,7 +28,7 @@ Configuration variables:
 - **longitude** (*Optional*): Longitude of your location required to calculate the time the sun rises and sets.
 - **elevation** (*Optional*): Altitude above sea level in meters. Impacts weather/sunrise data. 
 - **unit_system** (*Optional*): `metric` for Metric, `imperial` for Imperial.
-- **time_zone** (*Optional*): Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+- **time_zone** (*Optional*): Pick yours from here: [http://en.wikipedia.org/wiki/List_of_tz_database_time_zones](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
 - **name** (*Optional*): Name of the location where Home Assistant is running.
 - **customize** (*Optional*): [Customize](/docs/configuration/customizing-devices/) entities.
 - **customize_domain** (*Optional*): [Customize](/docs/configuration/customizing-devices/) all entities in a domain.

source/_docs/configuration/events.markdown

@@ -18,7 +18,7 @@ Home Assistant contains a few built-in events that are used to coordinate betwee
 Event `homeassistant_start` is fired when all components from the configuration have been intitialized. This is the event that will start the timer firing off `time_changed` events.
 
 <p class='note warning'>
-  Starting 0.42, it is no longer possible to listen for event `homeassistant_start`. Use the 'homeassistant' [platform](docs/automation/trigger) instead.
+  Starting 0.42, it is no longer possible to listen for event `homeassistant_start`. Use the 'homeassistant' [platform](/docs/automation/trigger) instead.
 </p>
 
 ### {% linkable_title Event `homeassistant_stop` %}

source/_docs/ecosystem/appdaemon/tutorial.markdown

@@ -43,22 +43,38 @@ The best way to show what AppDaemon does is through a few simple examples.
 
 ### {% linkable_title Sunrise/Sunset Lighting %}
 
-Lets start with a simple App to turn a light on every night at sunset and off every morning at sunrise. Every App when first started will have its `initialize()` function called which gives it a chance to register a callback for AppDaemons's scheduler for a specific time. In this case we are using `run_at_sunrise()` and `run_at_sunset()` to register 2 separate callbacks. The argument `0` is the number of seconds offset from sunrise or sunset and can be negative or positive. For complex intervals it can be convenient to use Python's `datetime.timedelta` class for calculations. When sunrise or sunset occurs, the appropriate callback function, `sunrise_cb()` or `sunset_cb()`  is called which then makes a call to Home Assistant to turn the porch light on or off by activating a scene. The variables `args["on_scene"]` and `args["off_scene"]` are passed through from the configuration of this particular App, and the same code could be reused to activate completely different scenes in a different version of the App.
+Lets start with a simple App to turn a light on every night fifteen
+minutes (900 seconds) before sunset and off every morning at sunrise.
+Every App when first started will have its ``initialize()`` function
+called which gives it a chance to register a callback for AppDaemons's
+scheduler for a specific time. In this case we are using
+`run_at_sunrise()` and `run_at_sunset()` to register 2 separate
+callbacks. The named argument `offset` is the number of seconds offset
+from sunrise or sunset and can be negative or positive (it defaults to
+zero). For complex intervals it can be convenient to use Python's
+`datetime.timedelta` class for calculations. In the example below,
+when sunrise or just before sunset occurs, the appropriate callback
+function, `sunrise_cb()` or `before_sunset_cb()` is called which
+then makes a call to Home Assistant to turn the porch light on or off by
+activating a scene. The variables `args["on_scene"]` and
+`args["off_scene"]` are passed through from the configuration of this
+particular App, and the same code could be reused to activate completely
+different scenes in a different version of the App.
 
 ```python
-import homeassistant.appapi as appapi
+    import appdaemon.plugins.hass.hassapi as hass
 
-class OutsideLights(appapi.AppDaemon):
+    class OutsideLights(hass.Hass):
 
-  def initialize(self):
-    self.run_at_sunrise(self.sunrise_cb, 0)
-    self.run_at_sunset(self.sunset_cb, 0)
-    
-  def sunrise_cb(self, kwargs):
-    self.turn_on(self.args["off_scene"])
+      def initialize(self):
+        self.run_at_sunrise(self.sunrise_cb)
+        self.run_at_sunset(self.before_sunset_cb, offset=-900)
+        
+      def sunrise_cb(self, kwargs):
+        self.turn_on(self.args["off_scene"])
 
-  def sunset_cb(self, kwargs):
-    self.turn_on(self.args["on_scene"])
+      def before_sunset_cb(self, kwargs):
+        self.turn_on(self.args["on_scene"])
 
 ```
 

source/_docs/ecosystem/nginx.markdown

@@ -14,13 +14,17 @@ Using NGINX as a proxy for Home Assistant allows you to serve Home Assistant sec
 
 ### {% linkable_title 1. Get a domain name forwarded to your IP %}
 
-Chances are, you have a dynamic IP Address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
+Chances are, you have a dynamic IP address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
 
 
 ### {% linkable_title 2 Install nginx on your server %}
 
 This will vary depending on your OS. Check out Google for this. After installing, ensure that NGINX is not running.
 
+<p class='note'>
+You will at least need nginx >= 1.3.13, as WebSocket support is required for the reverse proxy.
+</p>
+
 ### {% linkable_title 3. Obtain an SSL certificate %}
 
 There are two ways of obtaining an SSL certificate.
@@ -28,7 +32,7 @@ There are two ways of obtaining an SSL certificate.
 #### {% linkable_title Using Let's Encrypt %}
 If you purchased your own domain, you can use https://letsencrypt.org/ to obtain a free, publicly trusted SSL certificate. This will allow you to work with services like IFTTT. Download and install per the instructions online and get a certificate using the following command.
 
-```
+```bash
 $ sudo ./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
 ```
 
@@ -75,14 +79,13 @@ $ sudo ln ../sites-available/hass default
 
 Double check this configuration to ensure all settings are correct and start nginx.
 
-
 ### {% linkable_title 8. Port forwarding. %}
 
 Forward ports 443 and 80 to your server on your router. Do not forward port 8123.
 
 ### {% linkable_title NGINX Config %}
 
-```
+```text
 map $http_upgrade $connection_upgrade {
     default upgrade;
     ''      close;

source/_docs/installation/docker.markdown

@@ -20,14 +20,16 @@ $ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/
 
 ### {% linkable_title macOS %}
 
-When using `boot2docker` on macOS you are unable to map the local time to your Docker container. Use `-e "TZ=America/Los_Angeles"` instead of `-v /etc/localtime:/etc/localtime:ro`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+When using `docker-ce` (or `boot2docker`) on macOS, you are unable to map the local timezone to your Docker container (see Docker issue https://github.com/docker/for-mac/issues/44). Instead of `-v /etc/localtime:/etc/localtime:ro`, just pass in the timezone environment variable when you launch the container, ex: `-e "TZ=America/Los_Angeles"`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
-Additionally, if your expectation is that you will be able to browse directly to `http://localhost:8123` on your macOS host, then you will also need to replace the `--net=host` switch with `-p 8123:8123`. This is currently the only way to forward ports on to your actual host (macOS) machine instead of the virtual machine inside `xhyve`. More detail on this can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10).
+If you wish to browse directly to `http://localhost:8123` from your macOS host, meaning forward ports directly to the container, replace the `--net=host` switch with `-p 8123:8123`. More detail can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10).
 
 ```bash
 $ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant
 ```
 
+Alternatively, `docker-compose` works with any recent release of `docker-ce` on macOS. Note that (further down this page) we provide an example `docker-compose.yml` however it differs from the `docker run` example above. To make the .yml directives match, you would need to make _two_ changes: first add the equivalent `ports:` directive, then _remove_ the `network_mode: host` section. This is because `Port mapping is incompatible with network_mode: host:`. More details can be found at [Docker networking docs] (https://docs.docker.com/engine/userguide/networking/#default-networks). Note also the `/dev/tty*` device name used by your Arduino etc. devices will differ from the Linux example, so the compose `mount:` may require updates.
+
 ### {% linkable_title Windows %}
 
 When running Home Assistant in Docker on Windows, you may have some difficulty getting ports to map for routing (since the `--net=host` switch actually applies to the hypervisor's network interface). To get around this, you will need to add port proxy ipv4 rules to your local Windows machine, like so (Replacing '192.168.1.10' with whatever your Windows IP is, and '10.0.50.2' with whatever your Docker container's IP is):
@@ -160,7 +162,8 @@ As the docker command becomes more complex, switching to `docker-compose` can be
 ```yaml
   version: '3'
   services:
-    web:
+    homeassistant:
+      container_name: home-assistant
       image: homeassistant/home-assistant
       volumes:
         - /path/to/your/config:/config
@@ -188,7 +191,8 @@ or in a `docker-compose.yml` file:
 ```yaml
   version: '3'
   services:
-    web:
+    homeassistant:
+      container_name: home-assistant
       image: homeassistant/home-assistant
       volumes:
         - /path/to/your/config:/config

source/_docs/installation/hassbian/common-tasks.markdown

@@ -37,7 +37,7 @@ To get the current state of the `homeassistant.service` replace `stop` with `sta
 ### {% linkable_title Update Home Assistant %}
 
 <p class='note'>
-You can also use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade home-assistant`
+You can also use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade homeassistant`
 </p>
 
 Log in as the `pi` account and execute the following commands:

source/_docs/installation/raspberry-pi.markdown

@@ -12,6 +12,14 @@ redirect_from: /getting-started/installation-raspberry-pi/
 
 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](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite.
 
+<p class='note'>
+Although these installation steps specifically mention a Raspberry Pi, you can go ahead and proceed on any Linux install as well.  This guide is also referred to as the "Advanced Guide" for a virtual environment install.
+</p>
+
+<p class='note warning'>
+Please remember to ensure you're using an [appropriate power supply](https://www.raspberrypi.org/help/faqs/#powerReqs) with your Pi. Mobile chargers may not be suitable, since some are designed to only provide the full power with that manufacturer's handsets. USB ports on your computer also will not supply enough power and must not be used.
+</p>
+
 Connect to the Raspberry Pi over SSH. Default password is `raspberry`.
 You will need to enable SSH access. The Raspberry Pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/).
 
@@ -61,7 +69,13 @@ $ cd /srv/homeassistant
 $ python3 -m venv .
 $ source bin/activate
 ```
-Once you have activated the virtual environment you will notice the prompt change and then you can install Home Assistant.
+Once you have activated the virtual environment (notice the prompt change) you will need to run the following command to install a required python package.
+
+```bash
+(homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ python3 -m pip install wheel
+```
+
+Once you have installed the required python package it is now time to install Home Assistant!
 
 ```bash
 (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ pip3 install homeassistant
@@ -79,3 +93,15 @@ When you run the `hass` command for the first time, it will download, install an
 </p>
 
 If you want setup `hass` as a daemon and autostart it on boot please refer to [Autostart Home Assistant](/docs/autostart/).
+
+### {% linkable_title Updating %}
+
+To update to the latest version of Home Assistant follow these simple steps:
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ source /srv/homeassistant/bin/activate
+$ pip3 install --upgrade homeassistant
+```
+
+Once the last command executes restart the Home Assistant service to apply the latest updates.  Please keep in mind that some updates may take longer to boot up than others.  If Home Assistant fails to start make sure you check the **Breaking Changes** from the [Release Notes](https://github.com/home-assistant/home-assistant/releases).

source/_docs/installation/synology.markdown

@@ -61,7 +61,7 @@ Create homeassistant config directory & switch to it
 
 ```bash
 # mkdir /volume1/homeassistant
-# chown /volume1/homeassistant homeassistant
+# chown homeassistant /volume1/homeassistant 
 # chmod 755 /volume1/homeassistant
 # cd /volume1/homeassistant
 ```

source/_docs/installation/virtualenv.markdown

@@ -16,6 +16,10 @@ It's recommended when installing Python packages that you use a [virtual environ
 
 _(If you're on a Debian based system, you will need to install Python virtual environment support using `apt-get install python3-pip python3-venv`.)_
 
+<p class='Note'>
+It is recommended to use the [advanced guide](/docs/installation/raspberry-pi/) which allows for the installation to run as a `homeassistant` user.  The steps below may be shorter but some users find difficulty when applying updates and may run into issues.
+</p>
+
 ### {% linkable_title Install %}
 
  1. Create a virtual environment in your current directory:

source/_docs/mqtt/discovery.markdown

@@ -44,7 +44,7 @@ The discovery topic need to follow a specific format:
 
 - `<component>`: One of the supported components, eg. `binary_sensor`.
 - `<node_id>`: (*Optional*) id of the node providing the topic.
-- `<object_id>`: The ID of the device. This will become the `entity_id` in Home Assistant.
+- `<object_id>`: "The ID of the device. This is only to allow for separate topics for each device and is not used for the `entity_id`."
 - `<>`: The topic `config` or `state` which defines the current action.
 
 The payload will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. All configuration variables which are *required* must be present in the initial payload send to `/config`.

source/_docs/z-wave/devices.markdown

@@ -39,7 +39,7 @@ The key improvements are:
 
 ### {% linkable_title Z-Wave Security 2 %}
 
-From 2 April 2017 all newly approved Z-Wave devices will have to support the Security 2 (S2) framework. At the time of writing this (September 2017) OpenZWave does not support the S2 framework.
+From 2 April 2017 all newly approved Z-Wave devices will have to support the Security 2 (S2) framework. At the time of writing this (March 2018) OpenZWave does not support the S2 framework.
 
 ## {% linkable_title Device power %}
 

source/_docs/z-wave/installation.markdown

@@ -43,7 +43,7 @@ On Raspberry Pi you will need to enable the serial interface in the `raspi-confi
 ```yaml
 # Example configuration.yaml entry
 zwave:
-  usb_path: /dev/ttyUSB0
+  usb_path: /dev/ttyACM0
 ```
 
 {% configuration zwave %}