iCloud3 for Home Assistant

iCloud3 is a Home Assistant custom component designed to track iPhones, iPads, and Apple Watches. It leverages both Apple's iCloud Location Services and the Home Assistant Mobile App integration to monitor device location, battery levels, distance, travel time, and arrival/departure events.

Key capabilities include:

• Multi-Account Support: Track devices from multiple Apple Accounts (family, friends, etc.).
• Hybrid Tracking: Combines iCloud data with HA Mobile App sensors for improved accuracy and battery efficiency.
• Advanced Zone Logic: Supports stationary zones to save battery, primary home zone overrides, and enter-zone delays to prevent false triggers while driving through zones.
• Waze Integration: Provides travel time and distance estimates via Waze Route Service.
• Data Logging: Maintains a Zone Activity Log in .csv format for travel history and expense reporting.

The Stationary Zone is an automatically managed zone created by iCloud3 when a device remains relatively still for a period of time (e.g., at a mall or restaurant).

Key Behaviors:

• Automatic Management: iCloud3 automatically creates a zone named {devicename}_stationary.
• Location Updates: When a device is stationary, its latitude and longitude are updated with the GPS location, the device state changes to Stationary, and the polling interval is set to the stationary_inzone_interval value (default: 30 mins).
• Exit Behavior: When the device leaves the zone, the iOS App notifies Home Assistant, and standard device tracking resumes.
• Radius Logic: The Stationary Zone radius is 2 times the Home zone radius. When a device exits, the radius resets to 10m and expands again when a new Stationary Zone is entered.
• Entry Requirements: To enter a Stationary Zone, the device must be at least 2.5 times the Home zone radius away, and the user must be still for the duration specified by stationary_still_time (default: 8 minutes).

iCloud3 uses a dual-file configuration system to separate Home Assistant integration settings from iCloud3-specific operational parameters.

1. configuration.yaml (Home Assistant level)

This file is used by Home Assistant to set up the integration. The following parameters must reside here:

• username
• password (required for iCloud Location Services methods)
• create_sensors
• exclude_sensors
• entity_registry_file_name
• config_ic3_file_name

2. config_ic3.yaml (iCloud3 level)

This file contains the bulk of the iCloud3 parameters, such as device lists. Splitting this allows you to change iCloud3 parameters and restart the integration via the Event Log > Actions > Restart iCloud3 command without restarting all of Home Assistant.

File Search Order:

1. If config_ic3_file_name is set, iCloud3 looks at that specific path/file.
2. If config_ic3_file_name is set, it looks in /config/.
3. If config_ic3_file_name is set, it looks in /config/custom_components/icloud3/.
4. Default: /config/config_ic3.yaml.
5. If not in /config/, it looks in /config/custom_components/icloud3/config_ic3.yaml.

Warning: Do not store your primary config_ic3.yaml in the /config/custom_components/icloud3/ directory, as HACS may delete it during updates.

# /config/configuration.yaml
device_tracker:
  - platform: icloud3
    username: gary_icloud_account@email.com
    password: gary_icloud_account_password
    exclude_sensors: batstat,lzonn,lzont,name

# /config/config_ic3.yaml
devices:
  - device_name: gary_iphone
    email: gary_456@email.com
    name: Gary
    picture: gary.png

iCloud3 extends standard device tracking with several advanced data points and services:

• Waze Route Service: Provides travel time and distance to Home or other tracked zones using Waze data. It includes a local database to reuse historical Waze data when a device returns to a previous location.
• Battery Monitoring: Tracks battery level and charging status from both iCloud data and the Mobile App (every 5 seconds).
• Zone Tracking:
  • Reports distance to the center and edge of the Home zone, as well as distance to other zones and devices.
  • Supports a Primary Home Zone setting, allowing tracking results to be reported relative to a specific location (e.g., a vacation home).
  • Includes an Enter Zone delay to prevent false triggers when driving through a zone.
• Zone Activity Log: Maintains a .csv log of zone entries/exits for each device, which can be imported into spreadsheet software.
• Local Time Zone: Allows event times to be displayed in the time zone of the device's current location rather than the HA server's time zone.

iCloud3 is a location tracking system that operates on a 5-second cycle to monitor triggers and notifications from the Home Assistant iOS App (such as Zone Enter/Exit, Background Fetch, and Significant Location Updates).

Core Logic

• Data Validation: Transactions older than 2 minutes are discarded. To prevent GPS wandering, transactions within 1km of a zone are discarded when the device is already in a zone.
• Polling Mechanism: Every 15 seconds, iCloud3 evaluates if a device needs a location update from iCloud Location Services. If required, it issues the request, validates the result, and calculates the distance to tracked zones.
• Tracking Methods: It utilizes devices within your iCloud Family Sharing list or those being followed via the FindMy App.

Dynamic Polling Intervals

Instead of a fixed interval, iCloud3 calculates a dynamic polling schedule based on several factors to balance accuracy and battery/resource usage:

• Zone Status: Whether the device is in a configured zone or the special Stationary Zone (used to minimize polling when location hasn't changed).
• Proximity: A 'line-of-sight' distance from Home or other zones.
• Travel Time: Driving time and distance calculated via the Waze Route Calculator service.
• Direction: Whether the device is moving towards, away from, or is stationary relative to a zone.
• Device State: Battery level and the accuracy/freshness of the current GPS location.

This dynamic approach allows for high-resolution tracking (down to 1/10 of a mile/km) which enables automations based on distance rather than just simple zone entry/exit.

iCloud3 supports three primary tracking modes. It automatically selects the most efficient method based on your configuration and available data.

1. iCloud Location Services (Default)

Uses Apple's cloud services to locate devices. It uses two sub-methods:

• Find-My-Friends (fmf): Uses the email address provided in your config to track people on your FindMy App > People > Share My Location list. More efficient for specific individuals.
• Family Sharing (famshr): Tracks all members in your iCloud Family Sharing list. Easier to set up but less efficient if the list is large.

2. iOS App (iosapp)

Requires the Home Assistant Companion iOS App installed on the device. It uses push notifications to trigger zone entries/exits and location updates.

3. Hybrid/Specific Configurations

• No iOS App: If you don't want to use the iOS App for a specific device, set noiosapp: true in the device configuration.
• iOS App Only: To use the iOS App for location updates but not use iCloud Location Services, set tracking_method: iosapp in the platform configuration.

Use Template Sensors to create user-friendly 'badges' for dashboards (like Lovelace). These sensors can map raw iCloud3 data to friendly names and dynamic images.

• Location Badge: Maps sensor.gary_iphone_badge to a friendly name and a static image.
• Device Status Badge: Uses a template to change the entity_picture based on the state of a device (e.g., showing garage-door-open.png vs garage-door-closed.png).
• Presence Summary: A complex template sensor that calculates if the house is AllHome, FarAway, AllAway, or Someone based on multiple user zone names and distance flags.

# Garage Door Open/Closed Badge
- platform: template
  sensors:
    garage_door_badge:
      value_template: >-
        {{states("sensor.garage_door_state") | title}}
      entity_picture_template: >-
        {% if is_state("sensor.garage_door_state", "open") %}
          /local/garage-door-open.png
        {% else %}
          /local/garage-door-closed.png 
        {% endif %}

iCloud3 provides advanced tracking for iDevices (iPhone, iPad, Apple Watch) using data from iCloud Accounts and the HA Mobile App.

Tracking Modes

• Active Tracking: The device actively requests its location at regular intervals based on its distance from Home or other defined zones.
• Passive Monitoring: The device does not request its own location; instead, it is updated whenever another tracked device in the system requests its location.

Key Features

• Multiple Accounts: Supports tracking devices from multiple Apple Accounts (family, friends, etc.).
• Mobile App Integration: Monitors Mobile App activity for location and trigger changes every 5 seconds.
• GPS Accuracy: Includes logic to eliminate GPS wandering errors that cause incorrect zone exits.
• Stationary Zone: Automatically creates a dynamic Stationary Zone when a device remains unmoved for a period, helping to conserve battery life.

iCloud3 uses an algorithm to determine the time interval between iCloud Find my Friends location update requests. This balances the need for accurate data against Apple's request limits and device battery life.

The algorithm runs a sequence of tests. The first test that returns true determines the interval, and no further tests are performed. The interval is influenced by:

• Zone/State Changes: Transitions between zones (e.g., entering/exiting a Home zone).
• Proximity: Distance from defined zones.
• Travel Data: Waze travel time and direction of travel.
• GPS Accuracy: Poor accuracy may trigger a specific interval.
• Manual Overrides: User-specified intervals.

Interval Adjustments: After the base interval is determined, it may be modified by these multipliers:

1. Stationary Count: If stationary, the interval is multiplied by 2 if the stationary count (reported in the info attribute) is an even number, and by 3 if it is divisible by 3.
2. Direction of Travel: If the direction is Away, the interval is multiplied by 2.
3. Exceptions: If the battery is low, GPS accuracy is poor, or location data is old, no multipliers are applied.