Update documentation for 0.7.4

source/components/automation.markdown

@@ -19,15 +19,21 @@ full configuration but only the relevant part.
 ```yaml
 # Example of entry in configuration.yaml
 automation:
+# Turns on lights 1 hour before sunset if people are home
+# and if people get home between 16:00-23:00
 - alias: 'Rule 1 Light on in the evening'
   trigger:
+    # Prefix the first line of each trigger configuration
+    # with a '-' to enter multiple
     - platform: sun
       event: sunset
-      offset: "-01:00:00"
+      offset: '-01:00:00'
     - platform: state
       entity_id: group.all_devices
       state: home
   condition:
+    # Prefix the first line of each condition configuration
+    # with a '-'' to enter multiple
     - platform: state
       entity_id: group.all_devices
       state: home
@@ -38,19 +44,30 @@ automation:
     service: homeassistant.turn_on
     entity_id: group.living_room
 
+# Turn off lights when everybody leaves the house
 - alias: 'Rule 2 - Away Mode'
-
   trigger:
-   - platform: state
+    platform: state
-     entity_id: group.all_devices
+    entity_id: group.all_devices
-     state: 'not_home'
+    state: 'not_home'
-
-  condition: use_trigger_values
-  condition:
   action:
-     service: light.turn_off
+    service: light.turn_off
-     entity_id: group.all_lights
+    entity_id: group.all_lights
 
+# Notify when Paulus leaves the house in the evening
+- alias: 'Leave Home notification'
+  trigger:
+    platform: zone
+    event: leave
+    zone: zone.home
+    entity_id: device_tracker.paulus
+  condition:
+    platform: time
+    after: '20:00'
+  action:
+    service: notify.notify
+    data:
+      message: 'Paulus left the house'
 ```
 
 <p class='note'>
@@ -166,6 +183,22 @@ Valid values for `weekday` are (`sun`, `mon`, `tue`, `wed`, `thu`, `fri` & `sat`
 
 The above example will trigger on Saturday and Sunday every hour on the 5 (2:05, 3:05, 4:05, etc).
 
+
+#### {% linkable_title Zone trigger %}
+Zone triggers can trigger when an entity is entering or leaving the zone. For zone automation to work,
+you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently
+this is limited to the [OwnTracks platform](/components/device_tracker.owntracks.html).
+
+```yaml
+automation:
+  trigger:
+    platform: zone
+    entity_id: device_tracker.paulus
+    zone: zone.home
+    # Event is either enter or leave
+    event: enter
+```
+
 ## {% linkable_title Conditions %}
 
 Conditions are an optional part of an automation rule and be used to prevent an action from happening
@@ -234,6 +267,19 @@ automation:
 
 Valid values for `weekday` are (sun, mon, tue, wed, thu, fri & sat)
 
+#### {% linkable_title Zone condition %}
+Zone conditions test if an entity is in a certain zone. For zone automation to work,
+you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently
+this is limited to the [OwnTracks platform](/components/device_tracker.owntracks.html).
+
+```yaml
+automation:
+  condition:
+    platform: zone
+    entity_id: device_tracker.paulus
+    zone: zone.home
+```
+
 ## {% linkable_title Actions %}
 
 When an automation rule fires, it calls a service. For this service you can specify an entity id it

source/components/device_tracker.owntracks.markdown

@@ -10,7 +10,11 @@ footer: true
 ---
 
 <img src='/images/supported_brands/owntracks.png' class='brand pull-right' />
-This platform allows you to detect presence by monitoring MQTT topics uses by [Owntracks](http://owntracks.org/) for new locations. 
+This platform allows you to detect presence using [Owntracks](http://owntracks.org/). OwnTracks allows
+users to track their location on Android and iOS phones and publish it to a MQTT broker. This platform
+will connect to the broker and monitor for new locations.
+
+This component requires [the MQTT component](/components/mqtt.html) to be set up.
 
 To integrate Owntracks in Home Assistant, add the following section to your `configuration.yaml` file:
 

source/components/mqtt.markdown

@@ -9,9 +9,8 @@ sharing: true
 footer: true
 ---
 <img src='/images/supported_brands/mqtt.png' class='brand pull-right' />
-MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.
+MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol
-
+on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.
-The MQTT component needs an MQTT broker like [Mosquitto](http://mosquitto.org/) or [Mosca](http://www.mosca.io/). The Eclipse Foundation is running a public MQTT broker at [iot.eclipse.org](http://iot.eclipse.org/getting-started) or the Mosquitto Project under [test.mosquitto.org](http://test.mosquitto.org). If you prefer to use a public, keep in mind to adjust the topic and that your messages may be publicly accessible.
 
 To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file:
 
@@ -24,6 +23,7 @@ mqtt:
   keepalive: 60
   username: USERNAME
   password: PASSWORD
+  certificate: /home/paulus/dev/addtrustexternalcaroot.crt
 ```
 
 Configuration variables:
@@ -34,20 +34,90 @@ Configuration variables:
 - **keepalive** (*Optional*): The keep alive in seconds for this client. Default is 60.
 - **username** (*Optional*): The username to use with your MQTT broker.
 - **password** (*Optional*): The corresponding password for the username to use with your MQTT broker.
+- **certificate** (*Optional*): Certificate to use to encrypt communication with the broker.
+
+## {% linkable_title Picking a broker %}
+
+The MQTT component needs you to run an MQTT broker for Home Assistant to connect to.
+
+There are three options, each with various degrees of ease of setup and privacy.
+
+#### {% linkable_title Run your own %}
+
+Most private option but requires a bit more work. There are two free and open-source brokers to pick
+from: [Mosquitto](http://mosquitto.org/) and [Mosca](http://www.mosca.io/).
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  broker: 192.168.1.100
+  port: 1883
+  client_id: home-assistant-1
+  keepalive: 60
+  username: USERNAME
+  password: PASSWORD
+```
+
+#### {% linkable_title Public MQTT %}
+
+The Mosquitto project runs a [public broker](http://test.mosquitto.org). Easiest to setup but there
+is 0 privacy as all messages are public. Use this only for testing purposes and not for real tracking
+of your devices.
+
+```yaml
+mqtt:
+  broker: test.mosquitto.org
+  port: 1883
+
+  # Optional, if you want encryption
+  # (doesn't really matter because broker is public)
+  port: 8883
+  # Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt
+  certificate: /home/paulus/downloads/mosquitto.org.crt
+```
+
+#### {% linkable_title CloudMQTT %}
+
+[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free up to 10
+connected devices. This is enough to get started with for example
+[OwnTracks](/components/device_tracker.owntracks.html) and give you a taste of what is possible.
 
 <p class='note'>
-The MQTT component has no TLS support at the moment. This means that only plain-text communication is possible.
+Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks.
 </p>
 
-## Building on top of MQTT
+ 1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed)
+ 2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create)
+    (Cute Cat is the free plan)
+ 3. From the control panel, click on the _Details_ button.
+ 4. Create unique users for Home Assistant and each phone to connect<br>(CloudMQTT does not allow two
+    connections from the same user)
+      a. Under manage users, fill in username, password and click add
+      b. Under ACLs, select user, topic `#`, check 'read access' and 'write access'
+ 5. Copy the instance info to your configuration.yaml:
+```yaml
+    mqtt:
+      broker: <Server>
+      port: <SSL Port>
+      username: <User>
+      password: <Password>
+```
+
+<p class='note'>
+Home Assistant will automatically load the correct certificate if you connect to an encrypted channel
+of CloudMQTT (port range 20 000 - 30 000).
+</p>
+
+## {% linkable_title Building on top of MQTT %}
 
  - [MQTT Sensor](/components/sensor.mqtt.html)
  - [MQTT Switch](/components/switch.mqtt.html)
  - [MQTT Device Tracker](/components/device_tracker.mqtt.html)
+ - [OwnTracks Device Tracker](/components/device_tracker.owntracks.html)
  - [MQTT-automation rule](/components/automation.html#mqtt-based-automation)
  - Integrating it into a component. See the [MQTT example component](https://github.com/balloob/home-assistant/blob/dev/config/custom_components/mqtt_example.py) how to do this.
 
-## Testing
+## {% linkable_title Testing your setup %}
 
 For debugging purposes `mosquitto` is shipping commandline tools to send and recieve MQTT messages. For sending test messages to a broker running on localhost:
 

source/components/sensor.rpi_gpio.markdown

@@ -29,6 +29,6 @@ sensor:
 For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#GPIO_connector) about the Raspberry Pi.
 
 <p class='note warning'>
-As this requires access to the GPIO, you will need to run Home Assistant as root.
+If you are not running Raspbian Jessie, you will need to run Home Assistant as root.
 </p>
 

source/components/switch.rpi_gpio.markdown

@@ -26,6 +26,5 @@ switch:
 For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#GPIO_connector) about the Raspberry Pi.
 
 <p class='note warning'>
-As this requires access to the GPIO, you will need to run Home Assistant as root.
+If you are not running Raspbian Jessie, you will need to run Home Assistant as root.
 </p>
-

source/getting-started/index.markdown

@@ -18,9 +18,6 @@ footer: true
 <label class='menu-selector docker' for='docker-install'>Install using Docker</label>
 
 
-<h3>Installation</h3>
-
-
 <div class='install-instructions normal'>
 Installing and running Home Assistant on your local machine is easy. Make sure you have <a href='https://www.python.org/downloads/' target="_blank">Python 3.4</a> installed and execute the following code in a console:
 
@@ -33,44 +30,50 @@ hass \-\-open-ui
 <p>Running these commands will:</p>
 <ol>
 <li>Install Home Assistant</li>
-<li>Launch Home Assistant and serve web interface on <a href='http://localhost:8123' target="_blank">http://localhost:8123</a></li>
+<li>Launch Home Assistant and serve web interface on
+<a href='http://localhost:8123' target="_blank">http://localhost:8123</a></li>
 </ol>
 </div> <!-- INSTALL-INSTRUCTIONS NORMAL -->
 
 
 <div class='install-instructions docker'>
-<p>Installation with Docker is straightforward. Adjust the following command so that <code>/path/to/your/config/</code> points at the folder where you want to store your config and run it:</p>
+
+Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/`
+points at the folder where you want to store your config and run it:
 
 ```bash
 docker run -d \-\-name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro \-\-net=host balloob/home-assistant
 ```
 
-<p>This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.</p>
+This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.
 
 <p class='note'>
-When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace <code>-v /etc/localtime:/etc/localtime:ro</code> with <code>-e "TZ=America/Los_Angeles"</code> (replacing America/Los_Angeles with <a href='http://en.wikipedia.org/wiki/List_of_tz_database_time_zones' target="_blank">your timezone</a>)
+When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace
+<code>-v /etc/localtime:/etc/localtime:ro</code> with <code>-e "TZ=America/Los_Angeles"</code>
+(replacing America/Los_Angeles with <a href='http://en.wikipedia.org/wiki/List_of_tz_database_time_zones' target="_blank">your timezone</a>)
 </p>
+
 </div> <!-- INSTALL-INSTRUCTIONS DOCKER -->
 
 
 <div class='install-instructions raspberry'>
-<p>Home Assistant uses Python 3.4 which is not shipped with the current Raspbian distibution for the Raspberry Pi. Before installing Home Assistant, you will have to <a href="https://www.raspberrypi.org/forums/viewtopic.php?f=32&t=113961#p779265" target="_blank">install Python 3.4</a>.
 
-Once that is complete, installing and running Home Assistant on your local machine is easy. Make sure you have <a href='https://www.python.org/downloads/' target="_blank">Python 3.4</a> installed and execute the following code in a console:
+Home Assistant requires the Raspberry Pi to run <a href='https://www.raspberrypi.org/downloads/raspbian/'>Raspbian Jessie</a>.
+This version has been released on September 24, 2015 and comes by default with Python 3.4 which is required for Home Assistant.
+
+Execute the following code in a console:
 
-<p>
 ```bash
 pip3 install homeassistant
 hass \-\-open-ui
 ```
-</p>
-<p>Running these commands will:</p>
-<ol>
-<li>Install Home Assistant</li>
-<li>Launch Home Assistant and serve web interface on <a href='http://localhost:8123' target="_blank">http://localhost:8123</a></li>
-</ol>
-</div> <!-- INSTALL-INSTRUCTIONS RASPBERRY -->
 
+Running these commands will:
+
+ - Install Home Assistant
+ - Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123)
+
+</div> <!-- INSTALL-INSTRUCTIONS RASPBERRY -->
 
 ### {% linkable_title Troubleshooting %}
 

source/getting-started/troubleshooting-configuration.markdown

@@ -18,13 +18,54 @@ Home Assistant will print out the configuration directory it is using when start
 Whenever a component or configuration option results in a warning, it will be stored in
 `home-assistant.log`. This file is reset on start of Home Assistant.
 
+### {% linkable_title YAML %}
+
+Home Assistant uses the YAML syntax for configuration. YAML can be confusing at start but it is really
+powerful in allowing you to express complex configurations.
+
+The basics of YAML are lists and lookup tables containing key-value pairs. Lists will have each item
+start with a `-` while lookup tables will have the format `key: value`. The last value for a key is
+used in case you specify a duplicate key.
+
+```yaml
+# A list
+- hello
+- how
+- are
+- you
+
+# Lookup table
+beer: ice cold  # <-- will be ignored because key specified twice
+beer: warm
+wine: room temperature
+water: cold
+
+# Nesting tables
+device_tracker:
+  platform: mqtt
+
+# Nesting a list of tables in a table
+sensor:
+  - platform: mqtt
+    state_topic: sensor/topic
+  - platform: mqtt
+    state_topic: sensor2/topic
+```
+
+Indentation is used to specify which objects are nested under one anohter. Getting the right indentation
+can be tricky if you're not using an editor with a fixed width font. You can test your
+configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/).
+
+To learn more about the quirks of YAML, read
+[YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html)
+by SaltStack.
+
 ### {% linkable_title My component does not show up %}
 When a component does not show up, many different things can be the case. Before you try any of
 these steps, make sure to look at the `home-assistant.log` file and see if there are any errors
 related to your component you are trying to set up.
 
 **Problems with the configuration<br>**
-
 `configuration.yaml` does not allow multiple sections to have the same name. If you want a
  specific component to be loaded twice, append a number to the name.
 
@@ -42,9 +83,8 @@ Another common problem is that a required configuration setting is missing. If t
 case, the component will report this to `home-assistant.log`. You can have a look at
 [the component page](/components/) for instructions how to setup the components.
 
-Incorrect indentation within the `configuration.yaml` can also create issues.  [Online YAML parsers](http://yaml-online-parser.appspot.com/) are available to verify your text is properly formatted.  If there are errors, you will also see the tracebacks in the `home-assistant.log` referencing the line number from `configuration.yaml`.  This information along with the YAML parsers can be a fast way to resolve small validation issues.
+If you find any errors or want to expand the documentation, please
-
+[let us know](https://github.com/balloob/home-assistant.io/issues).
-If you find any errors or want to expand the documentation, please [let us know](https://github.com/balloob/home-assistant.io/issues).
 
 **Problems with dependencies<br>**
 Almost all components have external dependencies to communicate with your devices and services.