Package: home-assistant-findmy
home-assistant-findmyA 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 projectDisclaimerThis 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.DescriptionThis 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.SupportsDevices (iPhones, iPads, MacBooks, AirPods, Apple Watches, ...)including family devicesObjects (AirTags, ...)How to useMigration from < v1.x.xBasic installationInstall using pip:pip3 install home-assistant-findmySetup environment variables:export MQTT_CLIENT_USERNAME=your_usernameexport MQTT_CLIENT_PASSWORD=your_passwordexport MQTT_BROKER_IP=your_broker_ipexport MQTT_BROKER_PORT=your_broker_port(defaults to1883, if not set)export FINDMY_FILE_SCAN_INTERVAL=your_scan_interval(defaults to5seconds, if not set)You can also create a.envfile 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   = 5All environment variables can also be set usingprogram 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.jsonRun the scriptEnsure that your terminal hasfull disk accessOpen FindMy in the background and runfindmy -l /path/to/known_locations.jsonProgram ArgumentsArgumentAliasDescription--locations-lPath to the known locations JSON configuration file.--privacy-pHides specific device data from the console output.--force-sync-fDisables the timestamp check and provides an update everyFINDMY_FILE_SCAN_INTERVALseconds.--ipIP of the MQTT broker.--portPort of the MQTT broker.--usernameMQTT 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--passwordparameter, except in rare test cases. Always prefer setting it via the environment variable.Versions1.1.0In 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 charactersCleanup of device IDs client side for consistencyMinor improvements1.0.X - Breaking changesConfiguration is now done solely via environment variables and a JSON file for known locationsInstallation using pip is now possibleDevice data is only updated if the location timestamp changed in FindMy (skip with-fflag)Improved terminal outputMinor improvements0.0.2Adjusted device names to fitrecent MQTT changes(PR)0.0.1Initial versionLicenseSeeLICENSE.mdRoadmapSupport DeviceGroupsWrite comprehensive testsCould I help you?You can buy me a coffee here if you want 🙏