Getting started with the Home Assistant app for macOS
In this guide, we will install and configure the Home Assistant companion app for macOS.
OwnTracks is a popular app for location tracking in Home Assistant. Allowing to create some cool automation depending on the location of a device. In this article, I’m going to show you how to set up OwnTracks using the HTTP Mode and configure it in Home Assistant with the OwnTracks integration webhook. I’m also going to cover how to use it with the newly released Cloud webhooks which allow sending data back to Home Assistant from anywhere without exposing your instance to the Internet.
To set up OwnTracks in Home Assistant, go to Menu, Configuration, and then Integrations. Search for OwnTracks and then click on Configure. A pop-up comes up containing the unique webhook and also the encryption key.
Make sure that you copy this information because once you close the pop-up, you won’t be able to see it again inside the Home Assistant web interface. However, you can always find it by accessing the core.config_entries file inside the .storage folder which is hidden inside the Home Assistant config folder. (config/.storage/core.config_entries)
For the next step, download the OwnTracks app on your Android or IOS device.
If you are using an Android device, open the OwnTracks app, click on the Menu icon, Preferences, and Connection. Set the Mode to Private HTTP. Then, under Host, enter the OwnTracks webhook URL provided on Home Assistant. Under Identification, set up a Username, Device ID and also a tracker ID for the device you are setting. Now, to add the encryption key, go back to the main Preference window, and then go to Advance.
On an IOS device, click on the “i” at the top left corner of the screen and then, go to Settings. Change the Mode to HTTP, and then set up a Tracker ID. Now, enable Authentication and set up the User ID, the Secret encryption key, and the OwnTracks webhook URL.
If you don’t have Home Assistant set up with remote access, you can still integrate OwnTracks and use the Home Assistant Cloud service which now has webhooks available. Making it possible to send data back to Home Assistant without exposing your instance to the Internet.
To set up the Cloud webhook for OwnTracks, go into configurations and then Home Assistant Cloud. If you haven’t set up an account yet, you can try it out free for 30 days. If you are already signed in, you will notice that the webhooks that you set up in the integration window are available to use with the Cloud service.
Switch on the OwnTracks webhook, and then a pop-up comes up with a new Cloud webhook that you can use for OwnTracks. You can then copy that URL and paste it on the Host field in the OwnTracks app.
By this point, part of the set up is done. You can actually start pushing location data to Home Assistant by tapping on the Publish icon on the top right corner of the OwnTracks map window. Then, if you check the Home Assistant Config folder a new file named known_devices.yaml was automatically created.
There are a few things that you can configure for the devices added. For example, you can add the device’s
MAC address which can be used with a network device tracker like Nmap. You can also add a
picture or an
icon to make it easy to identify a person or device.
antonette_s8: hide_if_away: false name: icon: picture: mac: track: true juan_s9: hide_if_away: false name: icon: picture: mac: track: true
If you want to add an image to a device, you would first need to save that image in the www folder. If you don’t have this folder yet, you would need to create it inside the Home Assistant Config folder. Then, add the path for the image using
/local/ and then the name of the image including the file extension. After the image is added, restart home Assistant to apply the changes.
antonette_s8: hide_if_away: false name: Antonette picture: /local/Antonette.jpg track: true juan_s9: hide_if_away: false name: Juan picture: /local/Juan.jpg track: true
If you are using the classic web UI in Home Assistant, you would automatically see at the top the badges for the devices that you set up. However, if you are using Lovelace and you have it set to yaml mode, then you can either set up the devices in a Glance card or add the badges by adding the following to the top of the main View in the yaml file.
title: Home resources: - url: /local/mini-media-player.js?v=0.9.5 type: module views: - title: Main icon: mdi:home-outline badges: - device_tracker.juan_s9 - device_tracker.antonette_s8 cards:
All right so the next thing that you want to do is set up Zones which can be used in automations that can be triggered when a device is within a specific area. There are 2 ways that you can set up Zones. You can do it directly in Home Assistant or set up regions in the OwnTracks app.
To do it via the OwnTracks app, go to Menu, Regions, and then tap the “ + ” icon at the top to add a new location. In the Description field, enter a name for the new location, then tap on the GPS icon and search for the location that you would like to set up. After you select a new location, specify the radius that you would like to cover for this region. Then click on the checkmark at the top to save the changes.
Now to push this new location to Home Assistant, tap the 3 dots at the top, and then tap on Publish Waypoints. You can then check the map window in Home Assistant to see the new zone. You can also see the zone entity by going to States under Developer tools.
One of the bad things about setting up regions via the OwnTracks app instead of Zones directly in Home Assistant is that any time that you restart your Home Assistant, you would need to manually publish the waypoints so they can appear in Home Assistant.
Now, if you set up the Zones in Home Assistant, you won’t have to worry every time that you have to restart Home Assistant.
To set up specific locations in Home Assistant, create a new file named zones.yaml inside your Home Assistant config folder. Then, set up a name for the location, the latitude, longitude, radius, and an icon that represents the location.
- name: home latitude: !secret H_latitude longitude: !secret H_longitude radius: 80 icon: mdi:home
For assistant finding the Latitude, Longitude and the radius for a location, you can visit the website called Map Developers When finished, save the changes, and then include the Zones in the configuration.yaml file by adding the following:
zone: !include zones.yaml
Restart Home Assistant and then when is back online, you can see the new Zones set up in the Map window, and you can start using them in automations.
OwnTracks is not perfect. Sometimes it can report GPS locations with a low accuracy which can cause false zoning and trigger automations. To help avoid that you can set the
max_gps_accuracy in the configuration.yaml file.
For example, if you set up the
max_gps_accuracy to be within 100 or 200 meters, then only GPS reports within that value would be taking into account.
owntracks: max_gps_accuracy: 100
Other parameters that you can set up here are
waypoint_whitelist. Waypoints allow exporting regions from OwnTracks to Home Assistant. By default, it’s set to true, and any user in your home can export their regions. If you want to limit the users that can do this, then you can use the parameter waypoint_whitelist, which allows adding the usernames for the people that can export their location.
All right so the last thing that you need to set up is the monitoring mode in OwnTracks. If you are going to depend a lot on location tracking for automations then you want to use the Move mode, which continuously tracks and publish a new location to Home Assistant as soon as a device moves. The bad thing about this mode is that it uses a lot of battery, so that’s definitely something to consider. Now, the alternative would be to set up the Significant location change mode which would only publish a new location when a device moves at least 500 meters in 5 minutes. This mode enables the OwnTracks app to run in the background and minimized the battery consumption.
All right guys, that’s all I have for you today. If you have any feedback, suggestions or questions, leave a comment on the above video or send me a message via Twitter. If I have the answer to your questions, I’ll be more than happy to help.
One-time DonationBuy Me a Coffee
SubscriptionBecome a Patreon