mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-09 10:26:52 +00:00
Fix OwnTracks docs
This commit is contained in:
Paulus Schoutsen
parent
244995ae14
commit
54ec2e9ca7
@ -1,82 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "OwnTracks (via HTTP)"
|
||||
description: "Instructions on how to use Owntracks via HTTP to track devices in Home Assistant."
|
||||
date: 2017-09-28 07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
logo: owntracks.png
|
||||
ha_category: Presence Detection
|
||||
featured: true
|
||||
ha_release: 0.55
|
||||
---
|
||||
|
||||
OwnTracks is a free and open source application that allows you to track your location in Home Assistant. This is a platform that supports OwnTracks via their HTTP publishing method.
|
||||
|
||||
To integrate Owntracks tracking via HTTP in Home Assistant, add the following section to your `configuration.yaml` file:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
device_tracker:
|
||||
- platform: owntracks_http
|
||||
webhook_id: long-random-webhook-url
|
||||
```
|
||||
|
||||
The value for `webhook_id` should be sufficiently long and random, as it is the only form of "authentication" that is used. For this reason, it is highly advisable to be randomly generated.
|
||||
|
||||
To generate a `webhook_id` you can use the following command on your Raspberry Pi:
|
||||
|
||||
```bash
|
||||
python3 -c "import binascii;import os;print(binascii.hexlify(os.urandom(32)).decode('ascii'))"
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
webhook_id:
|
||||
description: Set the URL suffix used in the webhook component
|
||||
required: true
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
For further configuration options and usage instructions, read the documentation for the [OwnTracks platform](/components/device_tracker.owntracks/).
|
||||
|
||||
## {% linkable_title Configuring OwnTracks to submit data via HTTP %}
|
||||
|
||||
Open OwnTracks and go to Connection preferences:
|
||||
|
||||
- Mode: Select **Private HTTP**
|
||||
- Host: [Home Assistant URL]:[port]/api/webhook/[your-random-webhook-url]?u=[your name]&d=[device name]
|
||||
|
||||
Host example: If I host my Home Assistant at `https://example.duckdns.org`, my name is Paulus, my phone is a Pixel and I configured the value for `webhook_id` to be `long-random-webhook-url` I would set the host to be `https://example.duckdns.org/api/webhook/long-random-webhook-url?u=paulus&d=pixel`. This will result in an entity with an ID of `device_tracker.paulus_pixel`. You can pick any name for the user and the device.
|
||||
|
||||
Since the battery data is available as an attribute of the device tracker entity, it can be tracked with a [`template` sensor](/components/sensor.template/).
|
||||
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
pixel_battery:
|
||||
friendly_name: Pixel of Paulus
|
||||
unit_of_measurement: "%"
|
||||
value_template: '{{ states.device_tracker.paulus_pixel.attributes.battery|int }}'
|
||||
device_class: battery
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
## {% linkable_title Setting up on Android %}
|
||||
|
||||
The Android OwnTracks app sends more data than its iOS counterpart and it is possible to configure it using the `Identification` tab in `Preferences`, setting **Username** to your name, and **Device ID** to your device's name. Password field may be left blank.
|
||||
|
||||
Elaborating on the general example above:
|
||||
|
||||
1. Identification: Turn **Authentication** on,
|
||||
2. Set **Username** to `paulus` and leave the password blank or put any string in it.
|
||||
3. Set Device ID to `pixel`
|
||||
4. In the Host tab enter simply `https://example.duckdns.org/api/webhook/long-random-webhook-url`
|
||||
|
||||
|
||||
@ -11,18 +11,45 @@ logo: owntracks.png
|
||||
ha_category: Presence Detection
|
||||
featured: false
|
||||
ha_release: 0.7.4
|
||||
redirect_from:
|
||||
- components/device_tracker.owntracks
|
||||
- components/device_tracker.owntracks_http
|
||||
---
|
||||
|
||||
This platform allows you to detect presence using [Owntracks](http://owntracks.org/). OwnTracks allows users to track their location on iOS and Android phones and publish it to an MQTT broker. This platform will connect to the broker and monitor for new locations.
|
||||
OwnTracks is a free and open source application for iOS and Android that allow you to track your location and send it directly to Home Assistant. It can be set up via the integrations panel in the configuration screen.
|
||||
|
||||
This component requires [the MQTT component](/components/mqtt/) to be set up and works very well together with [the zone component](/components/zone/).
|
||||
By default the integration will listen for incoming messages from OwnTracks via HTTP. It will also listen for MQTT messages if Home Assistant is configured to use MQTT.
|
||||
|
||||
To integrate Owntracks in Home Assistant, add the following section to your `configuration.yaml` file:
|
||||
### {% linkable_title Configuring the app - Android %}
|
||||
|
||||
[Install the OwnTracks application for Android.](https://play.google.com/store/apps/details?id=org.owntracks.android)
|
||||
|
||||
In the OwnTracks app, open sidebar and click on preferences, then on connection. Change the following settings:
|
||||
|
||||
- Mode: Private HTTP
|
||||
- Host: `<url given to you when setting up the integration>`
|
||||
- Identification:
|
||||
- Username: `<Your name>`
|
||||
- Device ID: `<Your device name>`
|
||||
|
||||
### {% linkable_title Configuring the app - iOS %}
|
||||
|
||||
[Install the OwnTracks application for iOS.](https://itunes.apple.com/us/app/owntracks/id692424691?mt=8)
|
||||
|
||||
In the OwnTracks app, tap the (i) in the top left and click on settings. Change the following settings:
|
||||
|
||||
- Mode: HTTP
|
||||
- URL: `<url given to you when setting up the integration>`
|
||||
- Turn on authentication
|
||||
- User ID: `<Your name>`
|
||||
|
||||
## {% linkable_title Advanced configuration %}
|
||||
|
||||
OwnTracks allows the user to set advanced configuration by adding a section to your `configuration.yaml`.
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
device_tracker:
|
||||
- platform: owntracks
|
||||
owntracks:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
@ -63,37 +90,20 @@ A full sample configuration for the `owntracks` platform is shown below:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
device_tracker:
|
||||
- platform: owntracks
|
||||
max_gps_accuracy: 200
|
||||
waypoints: true
|
||||
mqtt_topic: "owntracks/#"
|
||||
events_only: true
|
||||
waypoint_whitelist:
|
||||
- jon
|
||||
- ram
|
||||
region_mapping:
|
||||
cabin: home
|
||||
office: work
|
||||
owntracks:
|
||||
max_gps_accuracy: 200
|
||||
waypoints: true
|
||||
mqtt_topic: "owntracks/#"
|
||||
events_only: true
|
||||
waypoint_whitelist:
|
||||
- jon
|
||||
- ram
|
||||
region_mapping:
|
||||
cabin: home
|
||||
office: work
|
||||
```
|
||||
|
||||
### {% linkable_title Using Owntracks with other device trackers %}
|
||||
|
||||
Owntracks can also be used with other device trackers, such as [Nmap](/components/device_tracker.nmap_tracker/) or [Netgear](/components/device_tracker.netgear/). To do this, fill in the `mac` field to the Owntracks entry in `known_devices.yaml` 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 `<username>_<device-id>` and could be set in app configuration. More details about this config can found in [device tracker](/components/device_tracker/).
|
||||
|
||||
An example showing the inclusion of the `mac` field for multiple component tracking. The `mac` field will need to be added to the `owntracks` device and will enable tracking by all components that track via the `mac` address.
|
||||
|
||||
```yaml
|
||||
USERNAME_DEVICE_ID:
|
||||
name: Friendly Name
|
||||
mac: EA:AA:55:E7:C6:94
|
||||
picture: https://www.home-assistant.io/images/favicon-192x192.png
|
||||
gravatar: test@example.com
|
||||
track: yes
|
||||
hide_if_away: no
|
||||
```
|
||||
|
||||
### {% linkable_title Using Owntracks regions %}
|
||||
## {% linkable_title Using Owntracks regions %}
|
||||
|
||||
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 `share` option for the region in the owntracks app. Please see the [owntracks documentation](http://owntracks.org/booklet/guide/waypoints/).
|
||||
|
||||
@ -101,7 +111,7 @@ Home Assistant will use the enter and leave messages to set your zone location.
|
||||
|
||||
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.
|
||||
|
||||
### {% linkable_title Using Owntracks regions - forcing Owntracks to update using iBeacons %}
|
||||
## {% linkable_title Using Owntracks regions - forcing Owntracks to update using iBeacons %}
|
||||
|
||||
<p class='note'>
|
||||
Owntracks v2.0.0 removes support for iBeacons on Android.
|
||||
@ -117,7 +127,7 @@ When you exit an iBeacon region HA will switch back to using GPS to determine yo
|
||||
|
||||
Sometimes Owntracks will lose connection with an iBeacon for a few seconds. If you name your beacon starting with `-` Owntracks will wait longer before deciding it has exited the beacon zone. HA will ignore the `-` when it matches the Owntracks region with Zones. So if you call your Owntracks region `-home` then HA will recognize it as `home`, but you will have a more stable iBeacon connection.
|
||||
|
||||
### {% linkable_title Using Owntracks iBeacons to track devices %}
|
||||
## {% linkable_title Using Owntracks iBeacons to track devices %}
|
||||
|
||||
iBeacons don't need to be stationary. You could put one on your key ring, or in your car.
|
||||
|
||||
@ -127,13 +137,29 @@ To use mobile iBeacons with HA, you just set up a region that doesn't match your
|
||||
|
||||
This allows you to write zone automations for devices that can't track themselves (for example *alert me if I leave the house and my keys are still at home*). Another example would be *open the gates if my car arrives home*.
|
||||
|
||||
### {% linkable_title Using mobile and fixed iBeacons together %}
|
||||
## {% linkable_title Using mobile and fixed iBeacons together %}
|
||||
|
||||
You can use iBeacons of both types together, so if you have a Zone `drive` with an iBeacon region called `-drive` and you arrive home with a mobile iBeacon called `-car`, then `device_tracker.beacon_car` will be set to a state of `drive`.
|
||||
|
||||
### {% linkable_title Importing Owntracks waypoints as zones %}
|
||||
## {% linkable_title Importing Owntracks waypoints as zones %}
|
||||
|
||||
By default, any Owntracks user connected to Home Assistant can export their waypoint definitions (from the *Export - Export to Endpoint* menu item) which will then be translated to zone definitions in Home Assistant. The zones will be named `<user>-<device> - <waypoint name>`. This functionality can be controlled in 2 ways:
|
||||
|
||||
1. The configuration variable `waypoints` can be set to `false` which will disable importing waypoints for all users.
|
||||
2. The configuration variable `waypoint_whitelist` can contain a list of users who are allowed to import waypoints.
|
||||
|
||||
## {% linkable_title Using Owntracks with other device trackers %}
|
||||
|
||||
Owntracks can also be used with other device trackers, such as [Nmap](/components/device_tracker.nmap_tracker/) or [Netgear](/components/device_tracker.netgear/). To do this, fill in the `mac` field to the Owntracks entry in `known_devices.yaml` 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 `<username>_<device-id>` and could be set in app configuration. More details about this config can found in [device tracker](/components/device_tracker/).
|
||||
|
||||
An example showing the inclusion of the `mac` field for multiple component tracking. The `mac` field will need to be added to the `owntracks` device and will enable tracking by all components that track via the `mac` address.
|
||||
|
||||
```yaml
|
||||
USERNAME_DEVICE_ID:
|
||||
name: Friendly Name
|
||||
mac: EA:AA:55:E7:C6:94
|
||||
picture: https://www.home-assistant.io/images/favicon-192x192.png
|
||||
gravatar: test@example.com
|
||||
track: yes
|
||||
hide_if_away: no
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user