jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-09 10:26:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix OwnTracks docs

Browse Source
This commit is contained in:
Paulus Schoutsen 2018-11-29 10:28:12 +01:00
parent 244995ae14
commit 54ec2e9ca7
2 changed files with 64 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
source/_components/device_tracker.owntracks_http.markdown
View File

@ -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`

102
source/_components/device_tracker.owntracks.markdown → source/_components/owntracks.markdown
View File

@ -11,18 +11,45 @@ logo: owntracks.png
ha_category: Presence Detection ha_category: Presence Detection
featured: false featured: false
ha_release: 0.7.4 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
device_tracker: owntracks:
- platform: owntracks
``` ```
{% configuration %} {% configuration %}
@ -63,37 +90,20 @@ A full sample configuration for the `owntracks` platform is shown below:
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
device_tracker: owntracks:
- platform: owntracks max_gps_accuracy: 200
max_gps_accuracy: 200 waypoints: true
waypoints: true mqtt_topic: "owntracks/#"
mqtt_topic: "owntracks/#" events_only: true
events_only: true waypoint_whitelist:
waypoint_whitelist: - jon
- jon - ram
- ram region_mapping:
region_mapping: cabin: home
cabin: home office: work
office: work
``` ```
### {% linkable_title Using Owntracks with other device trackers %} ## {% linkable_title Using Owntracks regions %}
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 %}
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/). 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. 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'> <p class='note'>
Owntracks v2.0.0 removes support for iBeacons on Android. 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. 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. 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*. 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`. 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: 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. 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. 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
```