mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-09 18:36:51 +00:00
OwnTracks integration: update docs (#27762)
This commit is contained in:
c0ffeeca7
GitHub
parent
b43299effe
commit
63b79c11be
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: OwnTracks
|
||||
description: Instructions on how to use Owntracks to track devices in Home Assistant.
|
||||
description: Instructions on how to use OwnTracks to track devices in Home Assistant.
|
||||
ha_category:
|
||||
- Presence Detection
|
||||
ha_iot_class: Local Push
|
||||
@ -12,42 +12,47 @@ ha_platforms:
|
||||
ha_integration_type: integration
|
||||
---
|
||||
|
||||
[OwnTracks](https://owntracks.org/) 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.
|
||||
[OwnTracks](https://owntracks.org/) is a free and open source application for iOS and Android that allows you to track your location and send it directly to Home Assistant. OwnTracks can be set up via **{% my integrations title="Settings > Devices & Services" %}**.
|
||||
|
||||
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. When a location is submitted via HTTP, Home Assistant will return all [Persons](/integrations/person/)' last known locations and they will be displayed within the OwnTracks app.
|
||||
By default, the integration listens for incoming messages from OwnTracks via HTTP. If Home Assistant is configured to use MQTT instead, it listens for MQTT messages. When a location is submitted via HTTP, Home Assistant returns all [Persons](/integrations/person/)' last known locations. Their location will be displayed within the OwnTracks app.
|
||||
|
||||
<lite-youtube videoid="UieAQ8sC6GY" videotitle="Location Tracking with OwnTracks HTTP Mode and Home Assistant" posterquality="maxresdefault"></lite-youtube>
|
||||
|
||||
## Configuration
|
||||
|
||||
To configure OwnTracks, you must set it up via the integrations panel in the configuration screen. This will give you the webhook URL to use during mobile device configuration (below).
|
||||
1. To set up OwnTracks in Home Assistant, go to **{% my integrations title="Settings > Devices & Services" %}**.
|
||||
1. Add the **OwnTracks** integration.
|
||||
* This will give you the **Webhook** URL as well as the **Encryption key** to use during mobile device configuration (below).
|
||||
|
||||
### Configuring the app - Android
|
||||
|
||||
Install [OwnTracks](https://play.google.com/store/apps/details?id=org.owntracks.android) application for Android. If you need a version of OwnTracks without Google Play Services, the "OSS" flavour is available [here](https://github.com/owntracks/android/releases).
|
||||
1. Install the [OwnTracks](https://play.google.com/store/apps/details?id=org.owntracks.android) application for Android.
|
||||
* If you need a version of OwnTracks without Google Play Services, the "OSS" flavour is available [here](https://github.com/owntracks/android/releases).
|
||||
|
||||
In the app, open the sidebar and click on preferences, then on the connection. Change the following settings:
|
||||
1. In the app, open the sidebar and select **Preferences**, then **Connection**.
|
||||
1. Change the following settings:
|
||||
|
||||
- Mode: Private HTTP
|
||||
- Host: `<URL given to you when setting up the integration>`
|
||||
- Identification:
|
||||
- Username: `<Username>`
|
||||
- Password: Can be left blank.
|
||||
- Device ID: `<Device name>`
|
||||
- Tracker ID: `<xx>` Two character tracker ID. (can be left blank)
|
||||
- **Mode**: HTTP
|
||||
- **Host**: `<URL given to you when setting up the integration>`
|
||||
- **Identification**:
|
||||
- **Username**: `<Username>`: You can make one up for OwnTracks.
|
||||
- **Password**: Can be left blank.
|
||||
- **Device ID**: `<Device name>`: Something that helps you remember which of your devices is used for OwnTracks.
|
||||
- **Tracker ID**: `<xx>` Two character tracker ID. (can be left blank)
|
||||
|
||||
Your tracker device will be known in Home Assistant as `<Username>_<Device name>`. If you entered a Tracker ID the tid attribute will be set to that ID.
|
||||
4. Your tracker device will be known in Home Assistant as `<Username>_<Device name>`. If you entered a Tracker ID, the `tid` attribute will be set to that ID.
|
||||
|
||||
### Configuring the app - iOS
|
||||
|
||||
[Install the OwnTracks application for iOS.](https://itunes.apple.com/us/app/owntracks/id692424691?mt=8)
|
||||
1. [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:
|
||||
1. In the OwnTracks app, tap the (i) in the top left and select **Settings**.
|
||||
1. Change the following settings:
|
||||
|
||||
- Mode: HTTP
|
||||
- URL: `<URL given to you when setting up the integration>`
|
||||
- Turn on authentication
|
||||
- User ID: `<Your name>`
|
||||
- **Mode**: HTTP
|
||||
- **URL**: `<URL given to you when setting up the integration>`
|
||||
- Turn on authentication
|
||||
- **User ID**: `<Your name>`. You can make one up for OwnTracks.
|
||||
|
||||
## Advanced configuration
|
||||
|
||||
@ -60,25 +65,25 @@ owntracks:
|
||||
|
||||
{% configuration %}
|
||||
max_gps_accuracy:
|
||||
description: 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.
|
||||
description: 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 meters. For example, if you put 200, only GPS reports with an accuracy of 200 meters will be takes in account.
|
||||
required: false
|
||||
type: integer
|
||||
waypoints:
|
||||
description: "Owntracks users can define [waypoints](https://owntracks.org/booklet/features/waypoints/) (a.k.a regions) which are similar in spirit to Home Assistant zones. If this configuration variable is `true`, the Owntracks users who are in `waypoint_whitelist` can export waypoints from the device and Home Assistant will import them as zone definitions."
|
||||
description: "OwnTracks users can define [waypoints](https://owntracks.org/booklet/features/waypoints/) (a.k.a regions) which are similar in spirit to Home Assistant zones. If this configuration variable is `true`, the OwnTracks users who are listed in the `waypoint_whitelist` can export waypoints from the device. Home Assistant will import these waypoints as zone definitions."
|
||||
required: false
|
||||
default: true
|
||||
type: boolean
|
||||
waypoint_whitelist:
|
||||
description: "A list of user names (as defined for [Owntracks](/integrations/owntracks)) who can export their waypoints from Owntracks to Home Assistant. This would be the `username` portion of the Base Topic Name, (e.g., owntracks/**username**/iPhone)"
|
||||
description: "A list of user names (as defined for [OwnTracks](/integrations/owntracks)) who can export their waypoints from OwnTracks to Home Assistant. This would be the `username` portion of the Base Topic Name, (e.g., owntracks/username/iPhone)."
|
||||
required: false
|
||||
default: All users who are connected to Home Assistant via Owntracks.
|
||||
default: All users who are connected to Home Assistant via OwnTracks.
|
||||
type: list
|
||||
secret:
|
||||
description: "[Payload encryption key](https://owntracks.org/booklet/features/encrypt/). This is usable when communicating with a third-party untrusted server or a public server (where anybody can subscribe to any topic). By default the payload is assumed to be unencrypted (although the communication between Home Assistant and the server might still be encrypted). This feature requires the `libsodium` library to be present."
|
||||
description: "[Payload encryption key](https://owntracks.org/booklet/features/encrypt/). This is usable when communicating with a third-party untrusted server or a public server (where anybody can subscribe to any topic). By default, the payload is assumed to be unencrypted (although the communication between Home Assistant and the server might still be encrypted). This feature requires the `libsodium` library to be present."
|
||||
required: false
|
||||
type: string
|
||||
mqtt_topic:
|
||||
description: The topic to subscribe for Owntracks updates on your MQTT instance.
|
||||
description: The topic to subscribe for OwnTracks updates on your MQTT instance.
|
||||
required: false
|
||||
default: owntracks/#
|
||||
type: string
|
||||
@ -88,7 +93,7 @@ events_only:
|
||||
type: boolean
|
||||
default: false
|
||||
region_mapping:
|
||||
description: "Dictionary to remap names of regions as configured in the Owntracks app to Home Assistant zones. Use this if you have multiple homes or Home Assistant instances and want to map a different label to 'home'. `key: value` maps Owntracks region `key` to Home Assistant zone `value`."
|
||||
description: "Dictionary to remap names of regions as configured in the OwnTracks app to Home Assistant zones. Use this if you have multiple homes or Home Assistant instances and want to map a different label to 'home'. `key: value` maps OwnTracks region `key` to Home Assistant zone `value`."
|
||||
required: false
|
||||
type: list
|
||||
{% endconfiguration %}
|
||||
@ -110,31 +115,31 @@ owntracks:
|
||||
office: work
|
||||
```
|
||||
|
||||
## Using Owntracks regions
|
||||
## Using OwnTracks regions
|
||||
|
||||
Owntracks can track regions, and send region entry and exit information to Home Assistant. You set up a region in the Owntracks app which you should name the same as your Home Assistant Zone. Please see the [owntracks documentation](https://owntracks.org/booklet/guide/waypoints/).
|
||||
OwnTracks can track regions, and send region entry and exit information to Home Assistant. To do this, set up a region in the OwnTracks app. Make sure to use the same name for the region in your Home Assistant Zone. When adding the coordinates for your region, note that the unit used for **Radius** in OwnTracks is *meter*. For more information, refer to the [OwnTracks documentation](https://owntracks.org/booklet/guide/waypoints/).
|
||||
|
||||
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.
|
||||
Home Assistant uses 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.
|
||||
|
||||
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.
|
||||
|
||||
## Using Owntracks regions - forcing Owntracks to update using iBeacons
|
||||
## Using OwnTracks regions - forcing OwnTracks to update using iBeaconsOwntracks
|
||||
|
||||
<div class='note'>
|
||||
Owntracks v2.0.0 removes support for iBeacons on Android.
|
||||
OwnTracks v2.0.0 removes support for iBeacons on Android.
|
||||
</div>
|
||||
|
||||
When run in the usual *significant changes mode* (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.
|
||||
When run in the usual *significant changes mode* (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.
|
||||
|
||||
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 [here](https://owntracks.org/booklet/guide/beacons/).
|
||||
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 [here](https://owntracks.org/booklet/guide/beacons/).
|
||||
|
||||
When you enter an iBeacon region, Owntracks will send a `region enter` 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 `home` then getting close to the beacon will trigger an update to HA that will set your zone to be `home`.
|
||||
When you enter an iBeacon region, OwnTracks will send a `region enter` 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 `home` then getting close to the beacon will trigger an update to HA that will set your zone to be `home`.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Using Owntracks iBeacons to track devices
|
||||
## 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.
|
||||
|
||||
@ -148,9 +153,9 @@ This allows you to write zone automations for devices that can't track themselve
|
||||
|
||||
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`.
|
||||
|
||||
## Importing Owntracks waypoints as zones
|
||||
## 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> - <region name>:<region uuid>`. 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> - <region name>:<region uuid>`. 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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user