339 lines
No EOL
19 KiB
HTML
339 lines
No EOL
19 KiB
HTML
<!doctype html>
|
||
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
|
||
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
|
||
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
|
||
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||
<title>Owntracks - Home Assistant</title>
|
||
<meta name="author" content="Home Assistant">
|
||
<meta name="description" content="Instructions how to use Owntracks to track devices in Home Assistant.">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/components/device_tracker.owntracks/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="Owntracks">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/components/device_tracker.owntracks/">
|
||
<meta property="og:type" content="article">
|
||
<meta property="og:description" content="Instructions how to use Owntracks to track devices in Home Assistant.">
|
||
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
|
||
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
<meta name="twitter:site" content="@home_assistant">
|
||
|
||
<meta name="twitter:title" content="Owntracks">
|
||
<meta name="twitter:description" content="Instructions how to use Owntracks to track devices in Home Assistant.">
|
||
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
|
||
|
||
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
|
||
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
|
||
<link rel='shortcut icon' href='/images/favicon.ico' />
|
||
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
|
||
</head>
|
||
|
||
<body >
|
||
|
||
<header>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
|
||
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
|
||
<a href="/" class="site-title">
|
||
<img width='40' src='/demo/favicon-192x192.png'>
|
||
<span>Home Assistant</span>
|
||
</a>
|
||
</div>
|
||
|
||
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
|
||
<nav>
|
||
<input type="checkbox" id="toggle">
|
||
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
|
||
<ul class="menu pull-right">
|
||
|
||
<li><a href="/getting-started/">Getting started</a></li>
|
||
<li><a href="/components/">Components</a></li>
|
||
<li><a href="/ecosystem/">Ecosystem</a></li>
|
||
<li><a href="/cookbook/">Examples</a></li>
|
||
<li><a href="/developers/">Developers</a></li>
|
||
<li><a href="/blog/">Blog</a></li>
|
||
<li><a href="/help/">Need help?</a></li>
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</header>
|
||
|
||
|
||
|
||
<div class="grid-wrapper">
|
||
<div class="grid grid-center">
|
||
|
||
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
|
||
|
||
|
||
<article class="page">
|
||
|
||
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
Owntracks
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<p>This platform allows you to detect presence using <a href="http://owntracks.org/">Owntracks</a>. OwnTracks allows 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.</p>
|
||
|
||
<p>This component requires <a href="/components/mqtt/">the MQTT component</a> to be set up and works very well together with <a href="/components/zone/">the zone component</a>.</p>
|
||
|
||
<p>To integrate Owntracks in Home Assistant, add the following section to your <code class="highlighter-rouge">configuration.yaml</code> file:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
|
||
<span class="s">device_tracker</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">owntracks</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Configuration variables:</p>
|
||
|
||
<ul>
|
||
<li><strong>max_gps_accuracy</strong> (<em>Optional</em>): Sometimes Owntracks can report GPS location with a very low accuracy (few kilometers). That can trigger false zoning in your Home Assistant installation. With the parameter, you can filter these GPS reports. The number has to be in meter. For example, if you put 200 only GPS report with an accuracy under 200 will be take in account.</li>
|
||
<li><strong>waypoints</strong> (<em>Optional</em>): Owntracks users can define <a href="http://owntracks.org/booklet/features/waypoints/">waypoints</a> (a.k.a regions) which are similar in spirit to Home Assistant zones. If this configuration variable is <code class="highlighter-rouge">True</code>, the Owntracks users who are in <code class="highlighter-rouge">waypoint_whitelist</code> can export waypoints from the device and Home Assistant will import them as zone definitions. Defaults to <code class="highlighter-rouge">True</code>.</li>
|
||
<li><strong>waypoint_whitelist</strong> (<em>Optional</em>): A list of user names (as defined for <a href="/components/device_tracker.owntracks/">Owntracks</a>) who can export their waypoints from Owntracks to Home Assistant. Defaults to all users who are connected to Home Assistant via Owntracks.</li>
|
||
</ul>
|
||
|
||
<p>A full sample configuration for the <code class="highlighter-rouge">owntracks</code> platform is shown below:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
|
||
<span class="s">device_tracker</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">owntracks</span>
|
||
<span class="s">max_gps_accuracy</span><span class="pi">:</span> <span class="s">200</span>
|
||
<span class="s">waypoints</span><span class="pi">:</span> <span class="s">True</span>
|
||
<span class="s">waypoint_whitelist</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">jon</span>
|
||
<span class="pi">-</span> <span class="s">ram</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="using-owntracks-with-other-device-trackers" href="#using-owntracks-with-other-device-trackers"></a> Using Owntracks with other device trackers</h3>
|
||
<p>Owntracks can also be used with other device trackers, such as <a href="/components/device_tracker.nmap_tracker/">Nmap</a> or <a href="/components/device_tracker.netgear/">Netgear</a>. To do this, fill in the <code class="highlighter-rouge">mac</code> field to the Owntracks entry in <code class="highlighter-rouge">known_devices.yaml</code> with the MAC address of the device you want to track. This way the state of the device will be determined by the source that reported last. The naming convention for known device list is <code class="highlighter-rouge"><username>_<device-id></code> and could be set in app configuration. More details about this config can found in <a href="/components/device_tracker/">device tracker</a>.</p>
|
||
|
||
<p>An example showing the inclusion of the <code class="highlighter-rouge">mac</code> field for multiple component tracking. The <code class="highlighter-rouge">mac</code> field will need to be added to the <code class="highlighter-rouge">owntracks</code> device and will enable tracking by all components that track via the <code class="highlighter-rouge">mac</code> address.</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">USERNAME_DEVICE_ID</span><span class="pi">:</span>
|
||
<span class="s">name</span><span class="pi">:</span> <span class="s">Friendly Name</span>
|
||
<span class="s">mac</span><span class="pi">:</span> <span class="s">EA:AA:55:E7:C6:94</span>
|
||
<span class="s">picture</span><span class="pi">:</span> <span class="s">https://home-assistant.io/images/favicon-192x192.png</span>
|
||
<span class="s">gravatar</span><span class="pi">:</span> <span class="s">test@example.com</span>
|
||
<span class="s">track</span><span class="pi">:</span> <span class="s">yes</span>
|
||
<span class="s">hide_if_away</span><span class="pi">:</span> <span class="s">no</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="using-owntracks-regions" href="#using-owntracks-regions"></a> Using Owntracks regions</h3>
|
||
<p>Owntracks can track regions, and send region entry and exit information to Home Assistant (HA). You set up a region in the Owntracks app which you should name the same as your HA Zone, and then make sure to turn on the <code class="highlighter-rouge">share</code> option for the region in the owntracks app. Please see the <a href="http://owntracks.org/booklet/guide/waypoints/">owntracks documentation</a>.</p>
|
||
|
||
<p>Home Assistant will use the enter and leave messages to set your zone location. Your location will be set to the center of zone when you enter. Location updates from OwnTracks will be ignored while you are inside a zone.</p>
|
||
|
||
<p>When you exit a zone, Home Assistant will start using location updates to track you again. To make sure that Home Assistant correctly exits a zone (which it calculates based on your GPS coordinates), you may want to set your Zone radius in HA to be slightly smaller that the Owntracks region radius.</p>
|
||
|
||
<h3><a class="title-link" name="using-owntracks-regions---forcing-owntracks-to-update-using" href="#using-owntracks-regions---forcing-owntracks-to-update-using"></a> Using Owntracks regions - forcing Owntracks to update using iBeacons</h3>
|
||
<p>When run in the usual <em>significant changes mode</em> (which is kind to your phone battery), Owntracks sometimes doesn’t update your location as quickly as you’d like when you arrive at a zone. This can be annoying if you want to trigger an automation when you get home. You can improve the situation using iBeacons.</p>
|
||
|
||
<p>iBeacons are simple bluetooth devices that send out an “I’m here” message. They are supported by IOS and some Android devices. Owntracks explain more <a href="http://owntracks.org/booklet/guide/beacons/">here</a>.</p>
|
||
|
||
<p>When you enter an iBeacon region, Owntracks will send a <code class="highlighter-rouge">region enter</code> message to HA as described above. So if you want to have an event triggered when you arrive home, you can put an iBeacon outside your front door. If you set up an OwnTracks iBeacon region called <code class="highlighter-rouge">home</code> then getting close to the beacon will trigger an update to HA that will set your zone to be <code class="highlighter-rouge">home</code>.</p>
|
||
|
||
<p>When you exit an iBeacon region HA will switch back to using GPS to determine your location. Depending on the size of your zone, and the accuracy of your GPS location this may change your HA zone.</p>
|
||
|
||
<p>Sometimes Owntracks will lose connection with an iBeacon for a few seconds. If you name your beacon starting with <code class="highlighter-rouge">-</code> Owntracks will wait longer before deciding it has exited the beacon zone. HA will ignore the <code class="highlighter-rouge">-</code> when it matches the Owntracks region with Zones. So if you call your Owntracks region <code class="highlighter-rouge">-home</code> then HA will recognise it as <code class="highlighter-rouge">home</code>, but you will have a more stable iBeacon connection.</p>
|
||
|
||
<h3><a class="title-link" name="using-owntracks-ibeacons-to-track-devices" href="#using-owntracks-ibeacons-to-track-devices"></a> Using Owntracks iBeacons to track devices</h3>
|
||
<p>iBeacons don’t need to be stationary. You could put one on your key ring, or in your car.</p>
|
||
|
||
<p>When your phone sees a mobile iBeacon that it knows about, it will tell HA the location of that iBeacon. If your phone moves while you are connected to the iBeacon, HA will update the location of the iBeacon. But when your phone loses the connection, HA will stop updating the iBeacon location.</p>
|
||
|
||
<p>To use mobile iBeacons with HA, you just set up a region that doesn’t match your Zone names. If HA sees an entry event for a iBeacon region that doesn’t match a Zone name (say <code class="highlighter-rouge">keys</code>) - it will start tracking it, calling the device <code class="highlighter-rouge">device_tracker.beacon_keys</code>).</p>
|
||
|
||
<p>This allows you to write zone automations for devices that can’t track themselves (for example <em>alert me if I leave the house and my keys are still at home</em>). Another example would be <em>open the gates if my car arrives home</em>.</p>
|
||
|
||
<h3><a class="title-link" name="using-mobile-and-fixed-ibeacons-together" href="#using-mobile-and-fixed-ibeacons-together"></a> Using mobile and fixed iBeacons together</h3>
|
||
<p>You can use iBeacons of both types together, so if you have a Zone <code class="highlighter-rouge">drive</code> with an iBeacon region called <code class="highlighter-rouge">-drive</code> and you arrive home with a mobile iBeacon called <code class="highlighter-rouge">-car</code>, then <code class="highlighter-rouge">device_tracker.beacon_car</code> will be set to a state of <code class="highlighter-rouge">drive</code>.</p>
|
||
|
||
<h3><a class="title-link" name="importing-owntracks-waypoints-as-zones" href="#importing-owntracks-waypoints-as-zones"></a> Importing Owntracks waypoints as zones</h3>
|
||
<p>By default, any Owntracks user connected to Home Assistant can export their waypoint definitions (from the <em>Export - Export to Endpoint</em> menu item) which will then be translated to zone definitions in Home Assistant. The zones will be named <code class="highlighter-rouge"><user>-<device> - <waypoint name></code>. This functionality can be controlled in 2 ways:</p>
|
||
|
||
<ol>
|
||
<li>The configuration variable <code class="highlighter-rouge">waypoints</code> can be set to <code class="highlighter-rouge">False</code> which will disable importing waypoints for all users.</li>
|
||
<li>The configuration variable <code class="highlighter-rouge">waypoint_whitelist</code> can contain a list of users who are allowed to import waypoints.</li>
|
||
</ol>
|
||
|
||
|
||
</article>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
|
||
<div class="grid">
|
||
|
||
|
||
<section class="aside-module grid__item one-whole lap-one-half">
|
||
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/device_tracker.owntracks.markdown'>Edit this page on GitHub</a></div>
|
||
<div class='brand-logo-container section'>
|
||
<img src='/images/supported_brands/owntracks.png' />
|
||
</div>
|
||
<div class='section'>
|
||
Introduced in release: 0.7.4
|
||
</div>
|
||
<div class='section'>
|
||
This is a platform for
|
||
<a href='/components/device_tracker/'>the Device Tracker component</a>.
|
||
</div>
|
||
<div class='section'>
|
||
<h1 class="title delta">Category Presence Detection</h1>
|
||
<ul class='divided'>
|
||
<li>
|
||
<a href='/components/device_tracker.asuswrt/'>ASUSWRT</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.actiontec/'>Actiontec</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.aruba/'>Aruba</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.automatic/'>Automatic</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.bt_home_hub_5/'>BT Home Hub 5</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.bbox/'>Bbox</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.bluetooth_le_tracker/'>Bluetooth LE Tracker</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.bluetooth_tracker/'>Bluetooth Tracker</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.cisco_ios/'>Cisco IOS</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.ddwrt/'>DD-WRT</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.fritz/'>FRITZ!Box</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.gpslogger/'>GPSLogger</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.locative/'>Locative</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.mqtt/'>MQTT Device Tracker</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/sensor.mqtt_room/'>MQTT Room Presence</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.netgear/'>Netgear</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.nmap_tracker/'>Nmap</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.luci/'>OpenWRT (luci)</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.ubus/'>OpenWRT (ubus)</a>
|
||
</li>
|
||
<li>
|
||
Owntracks
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.ping/'>Ping (ICMP)</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.snmp/'>SNMP</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.swisscom/'>Swisscom Internet-Box</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.tplink/'>TP-Link</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.thomson/'>Thomson</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.tomato/'>Tomato</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.trackr/'>TrackR</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.upc_connect/'>UPC ConnectBox</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.unifi/'>Ubiquiti Unifi WAP</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.volvooncall/'>Volvo On Call</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.xiaomi/'>Xiaomi Router</a>
|
||
</li>
|
||
<li>
|
||
<a href='/components/device_tracker.icloud/'>iCloud</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</section>
|
||
|
||
</div>
|
||
</aside>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<footer>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
<div class="grid__item">
|
||
<div class="copyright">
|
||
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
|
||
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
|
||
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
|
||
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
|
||
|
||
<div class="credit">
|
||
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
|
||
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
|
||
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
<script>
|
||
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
|
||
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
|
||
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
|
||
s.parentNode.insertBefore(g,s)}(document,'script'));
|
||
</script>
|
||
</body>
|
||
</html> |