OwnTracks

OwnTracks 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 Settings > Devices & services.

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’ last known locations. Their location will be displayed within the OwnTracks app.

Configuration

1. To set up OwnTracks in Home Assistant, go to Settings > Devices & services.
2. 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

1. Install the OwnTracks application for Android.

   • If you need a version of OwnTracks without Google Play Services, the “OSS” flavour is available here.

2. In the app, open the sidebar and select Preferences, then Connection.

3. Change the following settings:

   • 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)

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

1. Install the OwnTracks application for iOS.

2. In the OwnTracks app, tap the (i) in the top left and select Settings.

3. Change the following settings:

   • 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

OwnTracks allows the user to set advanced configuration by adding a section to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].

# Example configuration.yaml entry
owntracks:

A full sample configuration for the owntracks platform is shown below:

# Example configuration.yaml entry
owntracks:
  max_gps_accuracy: 200
  waypoints: true
  mqtt_topic: "owntracks/#"
  events_only: true
  waypoint_whitelist:
    - jon
    - ram
  region_mapping:
    cabin: home
    office: work

Using OwnTracks regions

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.

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.

Using OwnTracks regions - forcing OwnTracks to update using iBeaconsOwntracks

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.

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.

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.

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.

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 an iBeacon region that doesn’t match a Zone name (say keys) - it will start tracking it, calling the device device_tracker.beacon_keys).

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.

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.

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:

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.