This integration does its best to try to determine both how far and with what mode of transit you are traveling throughout the day. It builds off of the device tracker integration and assumes you carry a device with you as you travel.
Because it is based on the frequency with which your device sends GPS information back to Home Assistant, all of the gotchas that apply to location updating from the Companion Apps will affect its ability to provide accurate data.
Said another way: do not expect this integration to provide you with perfection.
There are a few more example graphs below.
Installation through HACS is the preferred installation method.
- Click the button above or go to HACS → Integrations → search for "Movement" → select it.
- Press DOWNLOAD.
- Select the version (it will auto select the latest) → press DOWNLOAD.
- Restart Home Assistant then continue to the setup section.
- Go to the release page and download the
movement.zipattached to the latest release. - Unpack the zip file and move
custom_components/movementto the following directory of your Home Assistant configuration:/config/custom_components/. - Restart Home Assistant then continue to the setup section.
Open your Home Assistant instance and start setting up by following these steps:
- Navigate to "Settings" → "Devices & Services"
- Click "+ Add Integration"
- Search for and select → "Movement"
Or you can use the My Home Assistant Button below.
Follow the instructions to configure the integration.
- Choose a person or a device to track from the main dropdown.
- If desired, configure any of the additional options below.
-
Distance to add to the start of each driving trip
Set in kilometers the distance you want added to the start of each driving trip. This will add an adjustment to your total distance traveled each time the integration determines you're moving fast enough to be considered driving. The reason you may wish to do this is because some devices can take a little longer to "wake up" and start reporting data back to Home Assistant when in the car. This may change based on your phone type, use of GPS or mapping apps, whether or not you have Android Auto or Apple CarPlay that connect automatically, or if you charge your phone in the car. -
Driving multipliers
These settings allow you to scale up or down the distance traveled while driving. Driving is not in a straight line, so depending on the types of roads you frequent, you may find that these settings can help you tweak the integration to get closer to the actual distance you are driving. -
Advanced options
Advanced options will only appear when re-configuring the integration via the CONFIGURE button. These are described in more detail in the dedicated section below.
Each of the sensors that the integration provides are described in detail below. All sensors are reset at the beginning of a new day.
This represents the total distance the person on device tracker has traveled.
Note: if this sensor is disabled, state will not be restored for all sensors in the configuration when Home Assistant is restarted.
adjustmentsThe adjustments that have been added to the distance traveled; mirrors the sensor value*.speedThe speed that the person or device is moving; mirrors the sensor value*.mode_of_transitThe assumed mode of transit the person is using; mirrors the sensor value*.ignore_countThe number of location changes that have been ignored. Changes are ignored when the GPS accuracy is poor and/or when updates arrive clustered together (a workaround for home-assistant/core#126972).update_rate: The rate at which distance changes are being calculated per minute.
* These attributes mirror their respective sensors and are provided as part of the main distance traveled sensor for use by more complex automations. Some automations may require an understanding of the way the state is changing across all of the values simultaneously which cannot be obtained from individual sensors since state change triggers would be delivered to automations for each independently.
The adjustments to the distance traveled that can be attributed to the adjustments in the configuration settings.
The distance that has been determined to be for walking.
Note: The value calculated by this sensor takes into account the possibility that you may be in transition between two modes of transit. It will do its best to assign values to the distance sensor that is the most logical for the given situation. This means the value is not simply the sum of all distance changes from sensor.<name>_distance_traveled while in this mode.
trip_start: The starting time of the current or last walking trip.trip_distance: The distance traveled for the current trip.trip_adjustments: The distance adjustments for the current trip.
The distance that has been determined to be for biking.
See notes in under the walking sensor about how this value is calculated.
trip_start: The starting time of the current or last biking trip.trip_distance: The distance traveled for the current trip.trip_adjustments: The distance adjustments for the current trip.
The distance that has been determined to be for driving.
See notes in under the walking sensor about how this value is calculated.
trip_start: The starting time of the current or last driving trip.trip_distance: The distance traveled for the current trip.trip_adjustments: The distance adjustments for the current trip.
The speed that the person or device is moving based on recent updates.
speed_recent_avg: The average speed at which you've been traveling recently.speed_recent_max: The maximum speed at which you've been traveling recently.
The assumed mode of transit the person is using based on recent updates.
transitioning: Whether it has been determined that the person or device is likely transitioning from one mode of transit to another.
The GPS accuracy person or device from the most recent update.
The number of updates to distance that have been made for the person or device throughout the day.
Add a certain distance manually.
This can be used, for instance if you travel on a certain schedule without a device.
Note: using this action will result in the speed being cleared and may result in the mode of transit needing to be recalculated. It is best to use this action when you know that your device is not moving (much).
config_entry: required Config entry to use. Example:1b4a46c6cba0677bbfb5a8c53e8618b0.distance: The distance to add in kilometers.adjustments: The adjustments to add in kilometers. This will increment both the distance traveled and the distance adjustments. So adding a distance of1.2with adjustments of0.2will result in the distance traveled beingmode_of_transit: The mode of transit that should be switched to.
This event will be fired for custom distance tracking template sensors. See the documentation for more details on how to configure this advanced option.
entity_id: The entity id for which this change applies. This will match the custom distance tracking template sensor. Example:sensor.toyota_prius_distance.config_entry_id: The config entry id for which this change applies. This can be used to get more details in templates, i.e. getting the title viaconfig_entry_attr(config_entry_id, 'title')or even all related entities viaintegration_entities(title).reason: The reason for the change. Eitherupdateorreset.from_state: The prior state of thesensor.<name>_distance_traveled.to_state: The new state of thesensor.<name>_distance_traveled.updates: The new state that should be applied to the template sensor. This can be applied or ignored based on logic that you choose. It includes both the newstateandattributes. See the example for more details.
There are a few things that may help with increasing the frequency with which your device reports its location back to Home Assistant. Be sure to check out the companion app docs as well.
- Get into the habit of plugging in your phone in the car, connecting it to the infotainment system, and ensuring the map app is visible.
- Consider adding zones intersections you walk or drive through frequenly. This can be especially helpful if you are turning or if the road turns at a given location.
- Request location updates via an automation while driving.
Various factors will affect whether or not these will work for you or not. Try out different ideas and see what works best. Different devices manage battery life differently. Most try to strike a good balance, and this is in conflict with constantly obtaining and reporting GPS location.
Your mileage will vary with each of these solutions.
This can be used to build complex scenarios of distance tracking, for instance combining several drivers for a single vehicle:
Using this setting, you can build custom sensors like the walking, biking, or driving sensors. but where you control when the distance changes applies to the sensor.
This can be used to have multiple configurations update the same (template entity) sensor which is what the multiple driver example does. For each driver in this example, you would press the CONFIGURE button, open the Advanced options section, and then select the shared template sensor.
For each trigger template sensor entity that you select, the integration will emit an event that can be consumed by a trigger, and you can change how it gets applied to the sensor as you see fit. See the example YAML configuration linked above for more details.
