Location

Overview

Location updates are sent from your device to Home Assistant in a number of situations:

  • When you enter or exit a zone defined in Home Assistant. For Android ensure the zone based tracking toggle is enabled in App Configuration.
  • When an iBeacon is detected or lost (see below). iOS
  • When the app is opened and it was not already open in the background.
  • Via an automated background fetch.
  • When an update is requested via special notification
  • When a URL Handler link is opened. iOS
  • When the app is called via a X-Callback-URL. iOS
  • When your devices detects a significant location change.
  • Manually when the app is refreshed (swipe down when at the top of a page) or from the shortcut menu opened from 3D touching the app icon. iOS
  • When an update is requested by sending an intent. Android

You can check the cause of the most recent location update by checking the value of sensor.last_update_trigger iOS

Depending on your set up, location data is sent directly from your phone to your Home Assistant instances or via the Home Assistant Cloud Service. This will depend on the URLs specified in the Connection section of the App Configuration menu. Location data is not sent via any other servers or organisations. Of course, if you decide not grant the Home Assistant Companion App location permission or if you subsequently remove the location permissions (iOS Settings>Privacy>Location Services or android Settings>Privacy>Permissions), no location data will be sent from your device to Home Assistant. It is important to note that none of the sensors will work if location is disabled. An alternative is to disable the device_tracker.<device_name> entity from the entity registry.

Getting started

Once you have installed and opened the Home Assistant Companion App for the first time, a new device_tracker. entity will be created. By default the entity will have a name of the form device_tracker.<device_ID> where <device_ID> is the device name you have set (iOS Settings>General>About or android Settings>About Phone). You can check the entity name within Home Assistant by visiting the Integration section of the Configuration page from the sidebar (swipe right if you're using the iOS Companion App) then clicking or tapping on the Mobile App integration for your device and scrolling through the list of entities. You can edit the entity's name attribute as you desire if needed.

The following is a basic example to switch a light on when you enter your home zone after dark.

automation:
- alias: 'Turn door light on when getting home'
trigger:
platform: state
entity_id: device_tracker.<device_ID>
to: 'home'
condition:
condition: sun
after: sunset
action:
- service: light.turn_on
data:
entity_id: light.frontdoor

Entity attributes

The newly created device_tracker entity may provide some of the following attributes depending on your operating system.

NameUnit
sourceNone
battery_levelpercentage
latitudedegrees
longitudedegrees
gps_accuracymeters
altitudemeters
coursedegrees
speedmeters per second
vertical_accuracymeters
floorfloors iOS

If you want to know more about the specifics of these attributes, please refer to the relevant documentation of your operating system:

Android or iOS

Location tracking when outside a Home Assistant zone

iOS

The Home Assistant Companion App receives significant location changes from iOS. Whenever an update is received, it is sent to Home Assistant. Roughly, an update is received every time that your device transfers to a new cellular tower, a significant amount of time has passed (usually a couple hours) or a connection state changes and the system notices your location recently changed.

Apple defines significant significant-change location updates as:

The significant-change location service delivers updates only when there has been a significant change in the device’s location, such as 500 meters or more.

They also say in the Energy Efficiency Guide:

Significant-change location updates wake the system and your app once every 15 minutes, at minimum, even if no location changes have occurred.

Finally, I think this answer from Stack Overflow says it best:

The significant location change is the least accurate of all the location monitoring types. It only gets its updates when there is a cell tower transition or change. This can mean a varying level of accuracy and updates based on where the user is. City area, more updates with more towers. Out of town, interstate, fewer towers and changes.

What's the real story on significant-change location updates? Who knows, because Apple keeps it private.

Location tracking in Home Assistant zones

At launch, Home Assistant for iOS sets up geofences for all zones in your Home Assistant configuration. Enter and exit notifications are sent to Home Assistant. For Android you will need to ensure that Zone Based Tracking is enabled in the App Configuration page.

Configuration

Add track_ios: false to your zone configurations to disable zone location tracking for all connected iOS apps. iOS

iBeacons

iOS

The app has basic support for using iBeacons to trigger enter/exit updates. To configure them, add your iBeacon details to your zone like this:

zone.home:
beacon:
uuid: B9407F30-F5F8-466E-AFF9-25556B57FE6D
major: 60042
minor: 43814

Restart Home Assistant and then the iOS app. It will then begin using iBeacons instead of your location for enter (but not exit) triggers around your zones. To add an iBeacon to zone.home add the above under your customize.

Sending an intent

Android Sending an intent is an advanced feature intended for users who are familiar with Android automation apps. Users can request a location update by sending an intent using an app such as Tasker or any other automation app that allows the user to send an intent. You will need to make sure that the app is running in the background for the updates to trigger properly.

The following steps are an example of how to send an intent using Tasker:

  1. Create a new task
  2. Add a step to the task
  3. Select "Send Intent"
  4. Under Action enter io.homeassistant.companion.android.background.REQUEST_ACCURATE_UPDATE
  5. Save the task
  6. Use the task with any Tasker profile to request a location update