Add presence detection getting started

home-assistant · Oct 4, 2015 · 67b5d7c · 67b5d7c · SEJeff · Oct 6, 2015
1 parent 6a877e1
commit 67b5d7c
Show file tree

Hide file tree

Showing 11 changed files with 81 additions and 17 deletions.
diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html
@@ -5,6 +5,7 @@
       <li><a href='/getting-started/'>Installing Home Assistant</a></li>
       <li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
       <li><a href='/getting-started/devices.html'>Adding devices</a></li>
+      <li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
       <li><a href='/getting-started/automation.html'>Automation</a></li>
       <li><a href='/components/'>Component overview</a></li>
     </ul>

diff --git a/source/components/alarm.mqtt.markdown b/source/components/alarm.mqtt.markdown
@@ -10,7 +10,7 @@ footer: true
 ---
 
 <img src='/images/supported_brands/mqtt.png' class='brand pull-right' />
-This platform enables the possibility to control a MQTT alarm. The alarm will only change state after receiving the a new state from `state_topic`. If these messages are published with RETAIN flag, the MQTT alarm will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state will
+This platform enables the possibility to control an MQTT alarm. The alarm will only change state after receiving the a new state from `state_topic`. If these messages are published with RETAIN flag, the MQTT alarm will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state will
 be `unknown`.
 
 To enable this alarm, add the following lines to your `configuration.yaml` for a GET request:

diff --git a/source/components/device_tracker.mqtt.markdown b/source/components/device_tracker.mqtt.markdown
@@ -10,7 +10,7 @@ footer: true
 ---
 
 <img src='/images/supported_brands/mqtt.png' class='brand pull-right' />
-This platform allows you to detect presence by monitoring a MQTT topic for new locations. To use this
+This platform allows you to detect presence by monitoring an MQTT topic for new locations. To use this
 platform, you specify a unique topic for each device.
 
 ```yaml

diff --git a/source/components/device_tracker.owntracks.markdown b/source/components/device_tracker.owntracks.markdown
@@ -11,10 +11,11 @@ footer: true
 
 <img src='/images/supported_brands/owntracks.png' class='brand pull-right' />
 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
+users to track their location on Android and iOS phones and publish it to an 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.
+This component requires [the MQTT component](/components/mqtt.html) to be set up and works very well
+together with [the zone component](/components/zone.html).
 
 To integrate Owntracks in Home Assistant, add the following section to your `configuration.yaml` file:
 

diff --git a/source/components/index.markdown b/source/components/index.markdown
@@ -328,12 +328,6 @@ Support for these devices is provided by the Home Assistant community and not
 the manufacturers of these devices.
 </p>
 
-## {% linkable_title Organization %}
-| Type | Description
-| ---- | -----------
-| [Group](/components/group.html) | Allows grouping of entities
-| [Scene](/components/scene.html) | Allow defining preferred state of a set of entities
-
 ## {% linkable_title Hubs %}
 
 Home Assistant integrates with a variety of third party Home Automation hubs and networks. It allows you to control the connected switches, lights and sensors via Home Assistant. Click on the following logos for setup instructions:
@@ -517,6 +511,12 @@ Support for these services is provided by the Home Assistant community and not
 the service providers.
 </p>
 
+## {% linkable_title Organization %}
+| Type | Description
+| ---- | -----------
+| [Group](/components/group.html) | Allows grouping of entities
+| [Scene](/components/scene.html) | Allow defining preferred state of a set of entities
+
 ## {% linkable_title Automation %}
 
 | Type | Description

diff --git a/source/developers/creating_components.markdown b/source/developers/creating_components.markdown
@@ -48,7 +48,7 @@ Home Assistant allows components and platforms to specify their dependencies and
 `DEPENDENCIES` and `REQUIREMENTS`. Both are lists that contain strings.
 
 Dependencies are other Home Assistant components that should be setup before the platform is loaded.
-An example is the MQTT sensor component, which requires an active connection to a MQTT broker. If
+An example is the MQTT sensor component, which requires an active connection to an MQTT broker. If
 Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor
 component.
 

diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown
@@ -169,3 +169,4 @@ go automate!
  - Learn about the available [automation conditions](/components/automation.html#conditions)
  - Learn about [scripts](/components/script.html) to help you trigger multiple actions and delays
  - Learn about [scenes](/components/scene.html) to help you set many entities at once to your liking
+ - Setup the [notification component](/components/#notify-service) to sent yourself messages
diff --git a/source/getting-started/devices.markdown b/source/getting-started/devices.markdown
@@ -19,11 +19,6 @@ and services.  Many components use the `sensor` platform.  Sensors need to be ad
 Most components that support multiple entries within the <code>configuration.yaml</code> follow the <code>component:</code>, <code>component 2:</code> format.
 </p>
 
-To get the most out of automation, it is useful to setup the following things:
-
- * [Presence Detection](/components/#presence)
- * [Notification service](/components/#notify-service)
-
 If you can't find support for your favorite device or service,
 [consider adding support](/developers/add_new_platform.html)
 
@@ -63,4 +58,4 @@ homeassistant:
 ```
 
 
-###[Next step: Setting up automation &raquo;](/getting-started/automation.html)
+###[Next step: Setting up presence detection &raquo;](/getting-started/presence-detection.html)
diff --git a/source/getting-started/presence-detection.markdown b/source/getting-started/presence-detection.markdown
@@ -0,0 +1,66 @@
+---
+layout: page
+title: "Setting up presence detection"
+description: "Instructions how to setup presence detection within Home Assistant."
+date: 2015-10-4 12:08
+sidebar: false
+comments: false
+sharing: true
+footer: true
+---
+
+<p class='note'>
+We care about privacy. Collected data is <b>only</b> stored in your instance of Home Assistant.
+</p>
+
+Presence detection detects if people are home, an important input for automation. The most important
+piece of information is to know if anyone is home. But knowing who is home or where they are will open
+a whole range of other automation options:
+
+ - Send me a notification when the kid arrives at school
+ - Turn on AC when I leave work
+
+<p class='img'>
+<img src='/images/screenshots/map.png' />
+Screenshot of Home Assistant showing a school, work and home zone and two people.
+</p>
+
+## {% linkable_title Setting it up %}
+
+The device tracker component offers presence detection for Home Assistant. It supports two different
+methods for presence detection: scan for connected devices on the local network and connect to third
+party service.
+
+Scanning for connected devices is easy to setup. See the instructions for our [supported routers][routers]
+or [scan the network using nmap][nmap]. This approach does have its limitations. It will only be able
+to detect if a device is home. It also struggles with iPhones because they disconnect from the WiFi if
+idle, marking them as not home while they are not.
+
+Home Assistant currently supports one third party service for presence detection: [OwnTracks](http://www.owntracks.org).
+OwnTracks is an app that you install on your iPhone or Android phone that allows you to push the location
+of your device to Home Assistant using an MQTT broker. An MQTT broker is an Internet of Things communication
+platform that you can [freely host yourself][mqtt-self] or get [a private instance for free in the cloud](/components/mqtt.html#run-your-own).
+
+<p class='note'>
+OwnTracks communicates directly with your MQTT broker, no data will pass through their servers.
+</p>
+
+#### {% linkable_title Zones %}
+
+<img src='/images/screenshots/badges-zone.png' style='float: right; margin-left: 8px; height: 100px;'>
+Home Assistant will know about the location for your device if you are using OwnTracks. By [setting up
+zones][zone] you will be able to add names to locations of your devices. This way you can easily
+spot on the state page where the people in your house are and use it as [triggers][trigger] and
+[conditions][condition] for automation.
+
+###[Next step: Setting up automation &raquo;](/getting-started/automation.html)
+
+[routers]: /components/#presence
+[nmap]: /components/device_tracker.nmap_scanner.html
+[ha-owntracks]: /components/device_tracker.owntracks.html
+[mqtt-self]: /components/mqtt.html#run-your-own
+[mqtt-cloud]: /components/mqtt.html#cloudmqtt
+[zone]: /components/zone.html
+[trigger]: /components/automation.html#zone-trigger
+[condition]: /components/automation.html#zone-condition
+
diff --git a/source/images/screenshots/badges-zone.png b/source/images/screenshots/badges-zone.png
diff --git a/source/images/screenshots/map.png b/source/images/screenshots/map.png