iCloud3 v2.2.1 Device Tracker-Advanced tracking features, iOS App monitoring

Updated 11/1/2020 - iCloud3 v2.2.1 is now available

The iCloud3 device tracker custom component is a major advancement over the iCloud component that is part of Home Assistant. It monitors the iOS App for location information and zone changes, uses the Waze route tracker for travel times, supports multiple zones, works with the Family Sharing and Find-my-Friends iCloud Location Services tracking methods, solves the false zone exits caused by gps wandering problem and much more.

Review the changes and features below and the extensive documentation to see how iCloud3 can be used to monitor your devices and provide you with presence detection that is accurate, responsive and timely.

Major Enhancements and Changes in v2.2

  • The Find-my-Friends (fmf) and Family Sharing (famshr) tracking methods have been rewritten to support iCloud 2fa accounts.
  • iOS App monitors additional triggers and location changes.
  • Performance enhancements reduce the calls to iCloud Location Services for location data.
  • Reduces ‘old location data’ by requesting iCloud location data before it is needed.
  • The iCloud3 configuration file can be used to specify configuration parameters. Using the iCloud3 Event Log > Actions > Restart iCloud3 command, they will take effect immediately, without restarting HA.
  • Improved error handling and notifications.
  • Additional configuration parameters and sensor attributes.
  • Major enhancements to the iCloud3 Event Log to support themes, tracking monitors, restarting iCloud3, pausing/resuming polling, errors and alerts notifications, event log export, and more.
  • Improvements to Stationary zone locations, detection and notifications…
  • Reorganized the iCloud3 documentation for easier installation, trouble shooting, reference and guidance in using it for device tracking.
  • And some bug fixes.
  • And much more…

Important Links

  • Download iCloud3 using HACS – Open HACS, search for iCloud3, select Install and restart HA. The Quick Start Guide leads you through the steps needed to begin using iCloud3 to track your devices.
  • Extensive documentation with with examples of presence detection, including sample configuration files can be found here
  • The iCloud3 GitHub Repository is here

Description and Features
iCloud3 is a device_tracker custom_component for iPhones, iPads and iWatches. It is tightly integrated with the HA IOS App, uses the Waze Route Tracker for distance and time information, creates Dynamic Stationary Zones when you are stationary, supports device include/exclude filters, minimizes battery usage, and much more.

iCloud3 is a Home Assistant device tracker custom component that greatly expands the capabilities of the HA iCloud integration. It exposes many new attributes, provides many new features, is based on enhanced route tracking methods, is much more accurate, and includes additional service calls.

Some of these features include:

  • A variable polling interval based on the Waze route mapping service (drive time and distance rather than just a calculated straight line distance).
  • Immediate zone changes (enter/exit) and location changes triggered by the iOS App.
  • An Event Log that highlights startup events, tracking events, errors, alerts and statistics and provides an Actions pulldown command window to Restart iCloud3, pause and resume polling, show tracking monitors and more…
  • Sensor templates that are used in automations, in scripts and on Lovelace cards are created and updated automatically.
  • GPS wandering that changes the device’s state from home to not_home randomly is eliminated.
  • Ability to track your location from multiple zones.
  • Short 15-second polling when less than 1 mi/km from home (reliably trigger automations based on an accurate distance).
  • Ability to include or exclude devices or device types (filters for devices you want to track).
  • Stationary Zones that help reduce polling and conserve battery life when you have not moved for a while…
  • Old location data and GPS accuracy are automatically discarded.
  • Additional service call commands (setting intervals, pausing and resuming polling, zone assignment, etc.)
  • No longer need any other program (other than the HA iOS or app) to handle device tracking and presence detection (no more Nmap, OwnTracks or router based tracking components).
  • Many new configuration variables attributes, sensors and Service Calls.
  • And more…

Gary Cobb, aka GeeksterGary

Edited October 10, 2020


I posted this on the 2.1 thread. I’m a release candidate or so behind (but after your changes regarding authentication) and since yesterday I’ve been receiving two factor requests a couple times per day. It looks like the native component is having a similar problem from other posts. It was working perfectly before.

I’m on 0.115.6 so this is unrelated to 0.116.

There haven’t been any changes to the authentication process for a while. I’m running 0.116 and am not seeing any 2fa requests. There was an issue someone opened after switching from the non-2fa account to the 2fa account about getting an authentication request on every update. That turned out to be the verification was never actually completed. Another user has a similar problem and, after deleting the cookie file 4 times and restarting HA, things settled down and are working fine. I deleted my cookie file and restarted iCloud3, went through the verification process and did see that no location information was being returning from iCloud Location Services. After restarting iCloud3, everything was fine.

I would delete the cookie file so a new verification process will start. Go through the select trusted device process, get the 6-digit code via a text message, enter that code and see if it completes. Then restart iCloud3 on the Event Log > Action pull down windows. You may have to do this several times. I did experience a problem a while ago and it seemed like there was a communication error from Apple that solved itself after a few tries.

The complete verification process is described in the iCloud3 docs here.


Installed everything. Login with icloud is ok. Had my 2way auth done… Have my entities and sensors.
Restart HA and now i dont see the correct information in the entities. When update HA iOS the iOS entities are updates. the icloud still show me i’m at home. (im at my work now 1km away)

It sounds like iCloud3 is not monitoring the iOS app device tracker or last update trigger entity so it is not picking up zone enter/exit triggers. Review the startup information in the Event Log to see what entities are monitored and for any error messages. Select Event Log > Actions > Show Tracking Monitors to display the iOS app data as seen by iCloud3.

The iCloud3 docs discuss the iOS App here.
The iCloud3 docs discuss the Event Log during startup here.

I’ll try that but it’s odd that suddenly it’s a problem after a month of no issues. I upgraded to the new release last night and restarted and reauthenticated (At 8:33 PM) and it was fine until 10:18 this morning. Here is what I’m seeing in the log.

in find my friends I add my friend. So we share both our location.

I add this in device_tracker:

- platform: icloud3
  username: !secret icloud_username
  password: !secret icloud_password
  tracking_method: fmf
  unit_of_measurement: km
  gps_accuracy_threshold: 20
  waze_realtime: true
  waze_region: EU
    - peter_iphone > !secret icloud_username
    - cenkay_xr > !secret icloud_kay_username

But I get this error now:

Schermafbeelding 2020-10-11 om 17.35.14

If I add hard a email address than just the info of cenkay_xr is showing.
Mine is not show even the info is coming from my email account …
It say my email is not valid and its not in the FMF contact list

Hi Gary, I read every word of your documentation and my startup event logs match yours exactly. I am having issues where locations are not being updated or when they do, it is 30-40 minutes late. What should I check next ??


  1. Make sure you can see everyone sharing their location in the FindMy app on all the devices. If you can not see it in the FindMy App, it will not be returned to iCloud3 when it is starting up. As I remember, the FindMy app might send an invitation to the person at the email address you entered to be shared. That person must approve the sharing invitation or they will not be seen.
  2. Apple Link - https://support.apple.com/en-us/HT210400

Go to Event Log > Actions > Export Event Log. It will create icloud3-event-log.log in the HA /config directory. Send it to [email protected] and I’ll take a look at it to see if I notice anything.

More info about exporting the Event Log is in the iCloud3 docs here

I already now add my friend in family sharing. Now both accounts are show correct in HA :smiley:
And we did add him first as friend and he accepted the invite. Hit info was in HA, mine was not. (I add my username/password credentials)

But its solved now

iCloud3 is working perfectly for me, but my wife’s phone isn’t working properly. It’s constantly and consistently showing her in a named Zone just up the road (the local shops).
Today we’ve gone for a walk around the neighbourhood and MY iCloud3 shows my phone merrily making its way around the neighbourhood while my wife’s remains static.
It’s really odd. It says in her log:
“Updating device>GPS 53.799690247,-1.549103022/65m Located 8 seconds ago”
(location details obfuscated) but the location stays set at the wrong zone which is about 120m away.
Confused. Why does it work so well for me but not at all for my wife?

A thought: wonder if devicename is case sensitive…

EDIT: I altered the case of devicename and it’s correctly identified my wife as ‘home’ for the first time. However, when I look at my ‘log’ in the state column it shows ‘home’, same for the zone column but in my wife’s state is blank. Only the zone shows her at home.

icloud3 setup error >> the ios app device_tracker entity was not found in the entity register. CRLFDevice_tracker entities suffixes found -

Also I have no ‘actions’ button only refresh, debug and restart.

Hi Gary,

What is the use of *zone_name, *zone_name2, *zone_name3 ?

In your track_devices parameter line, you are using the !secret XXX to identify the person you want to track. The track_devices parameter does not support using the HA !secret method. You need to use the actual email address of the person you want to track. iCloud3 use’s the’@‘ on the parameter line to determine the field is an email address that then ties it to the person.

See the display_as configuration parameter in the iCloud3 docs. Using it, you can change the text displayed in the Event Log from one value to another and hide the email address in the HA logs.

sent, thanks for the help

You are running an old version of the Event Log and need to clear your browser cache to load the new version. Then see what it looks like.

On your phone or iPad running the iOS App, select HA sidebar > App Configuration > Reset front end cache at the bottom of the screen. Exit back to HA and pull down from there too to refresh the page. That should reload the Event Log on the phone or iPad. Do this on every device running HA.

My compliments on developing this brilliant add-on! Works a charm!
Quick Q: Can KM be used instead of miles? My default units in HA are set to metric.

configuration parameter unit_of_measurement: km
See iCloud3 docs for more info on available parameters here

There are just another way to format the zone name. I actually exclude on my set up.

1 Like

The error message “The iOS App device_tracker entity was not found in the entity registry” indicates you have not installed the iOS App on the phone. Without the iOS App, you will not receive Zone enter/exit triggers and iCloud3 will not react to zone htt

See iCloud3 docs for more info on the iOS App here