home-assistant-findmy

A python script that reads local FindMy cache files to publish device locations and metadata (including those of AirTags, AirPods, Apple Watches, iPhones) to Home Assistant via MQTT.

Migration from < v1.x.x • Support this project

Important

home-assistant-findmy might currently not work on macOS 14.4 (March 2024) and above due to breaking changes introduced by Apple. Please do not upgrade the machine you intend to use it on for now.

Disclaimer

This script is provided as-is, without any warranty. Use at your own risk. This code is not tested and should only be used for experimental purposes. Loading the FindMy cache files is not intended by Apple and might cause problems. The project is not affiliated to Apple Inc., Home Assistant or MQTT.

Description

This python script reads the FindMy cache files and publishes the location data to MQTT to be used in Home Assistant. It uses auto discovery so no further entity configuration is needed in Home Assistant. Consult the documentation on how to set up an MQTT broker for Home Assistant. The script needs to be executed on macOS with a running FindMy installation. It must be executed in a terminal with full disk access to be able to read the cache files.

Supports

Devices (iPhones, iPads, MacBooks, AirPods, Apple Watches, ...)
- including family devices
Objects (AirTags, ...)

How to use

Migration from < v1.x.x

Basic installation

Install using pip: pip3 install home-assistant-findmy
Setup environment variables:
- export MQTT_CLIENT_USERNAME=your_username
- export MQTT_CLIENT_PASSWORD=your_password
- export MQTT_BROKER_IP=your_broker_ip
- export MQTT_BROKER_PORT=your_broker_port (defaults to 1883, if not set)
- export FINDMY_FILE_SCAN_INTERVAL=your_scan_interval (defaults to 5 seconds, if not set)
You can also create a .env file in the directory you run the script from and add the environment variables there, e.g.:
```
MQTT_CLIENT_USERNAME        = mqtt_client
MQTT_CLIENT_PASSWORD        = your_password
MQTT_BROKER_IP              = 192.168.178.5
MQTT_BROKER_PORT            = 1883
FINDMY_FILE_SCAN_INTERVAL   = 5
```
All environment variables can also be set using program arguments, but it is highly recommended to use environment variables for your credentials.

Configure known locations (home/work/gym/...)

Apple's "Safe Locations" are not reliable or versatile enough for your Home Assistant instance. You can configure your own known locations in a JSON file which are then used to determine the state published to Home Assistant. For each location you need to specify a name, latitude, longitude and a tolerance in meters (see example configuration).

Example configuration:

{
    "home": {
        "latitude": 12.3456789,
        "longitude": 12.3456789,
        "tolerance": 70
    },
    "work": {
        "latitude": 12.3456789,
        "longitude": 12.3456789,
        "tolerance": 70
    }
}

If the device location is not inside the tolerance of any specified known location, 'not_home' will be shown. If FindMy does not offer a location, the state is 'unknown'. The first match will be returned if a device is in the range of multiple known locations.

You need to specify the path of your known locations configuration file as a program argument when running the script.

e.g. findmy -l /path/to/known_locations.json

Run the script

Ensure that your terminal has full disk access
Open FindMy in the background and run findmy -l /path/to/known_locations.json

Program Arguments

Argument	Alias	Description
`--locations`	`-l`	Path to the known locations JSON configuration file.
`--privacy`	`-p`	Hides specific device data from the console output.
`--force-sync`	`-f`	Disables the timestamp check and provides an update every `FINDMY_FILE_SCAN_INTERVAL` seconds.
`--ip`		IP of the MQTT broker.
`--port`		Port of the MQTT broker.
`--username`		MQTT client username.
`--password` [Warning]		MQTT client password. Only for rare test cases! Avoid setting the password using this parameter.

Warning: For security reasons, it's advised not to set the password using the --password parameter, except in rare test cases. Always prefer setting it via the environment variable.

Versions

1.1.0

In very rare occasions, or if you have changed the code before, this version might lead to changed device IDs being propagated to your Home Assistant instance.

Fix invalid device IDs by removing special characters
Cleanup of device IDs client side for consistency
Minor improvements

1.0.X - Breaking changes

Configuration is now done solely via environment variables and a JSON file for known locations
Installation using pip is now possible
Device data is only updated if the location timestamp changed in FindMy (skip with -f flag)
Improved terminal output
Minor improvements

0.0.2

Adjusted device names to fit recent MQTT changes (PR)

0.0.1

Initial version

License

See LICENSE.md

Roadmap

Support DeviceGroups
Write comprehensive tests

Could I help you? You can buy me a coffee here if you want 🙏

hkfuertes/home-assistant-findmy