Home Assistant Home Assistant

Proximity

The proximity integration allows you to monitor the proximity of devices or persons to a particular zone and the direction of travel. The result is an entity created in Home Assistant which maintains the proximity data.

This integration is useful to reduce the number of automation rules required when wanting to perform automations based on locations outside a particular zone. The zone and state based triggers allow similar control but the number of rules grows exponentially when factors such as direction of travel need to be taken into account.

Some examples of its use include:

  • Increase thermostat temperature as you near home
  • Decrease temperature the further away from home you travel

The Proximity entity which is created has the following values:

  • state: Distance from the monitored zone (in unit_of_measurement)
  • dir_of_travel: Direction of the closest device or person to the monitored zone. Values are:
    • not set
    • arrived
    • towards
    • away_from
    • unknown
    • stationary
  • unit_of_measurement: Measurement of distance. Values are:
    • km
    • m
    • mi
    • yd
    • ft
  • nearest: The device or person which is nearest to the zone

To enable this integration in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
proximity:
  home: 
    ignored_zones:
      - work
    devices:
      - device_tracker.car1
    tolerance: 50
    unit_of_measurement: mi

Video Tutorial

This video tutorial explains how to set up geofencing in Home Assistant using the proximity integration.

Configuration Variables

Looking for your configuration file?
zone map (Optional)

The zone to which this integration is measuring the distance to. Default is the home zone.

ignored_zones list (Optional)

Where proximity is not calculated for a device or person (either the device being monitored or ones being compared (e.g., work or school).

devices list (Optional)

A list of devices and/or persons to compare location against to check closeness to the configured zone.

tolerance integer (Optional)

The tolerance used to calculate the direction of travel in meters (m) to filter out small GPS coordinate changes.

unit_of_measurement string (Optional, default: km)

The unit of measurement for distance. Valid values are (km, m, mi, yd, ft) [kilometers, meters, miles, yards and feet respectively].

To add multiple proximity components, add a mapping to your configuration.yaml file:

# Example configuration.yaml entry
proximity:
  home:
    ignored_zones:
      - work
      - school
    devices:
      - device_tracker.car1
      - device_tracker.iphone1
      - device_tracker.iphone2
    tolerance: 50
    unit_of_measurement: mi
  home3:
    zone: home3
    devices:
      - device_tracker.iphone1
    tolerance: 50
  work:
    zone: work
    devices:
      - person.paulus
    tolerance: 10