Apple Device Tracker integration for Gladys Assistant
Track your Apple devices with Find My and use them as presence sensors in Gladys.
Published by prohand
- Devices
- Version 1.0.4
- Requires Gladys >=4.86.0
- ★ 0
This integration signs in to your iCloud account, reads the position of the devices visible in Find My and exposes them in Gladys as presence sensors. You can then trigger scenes on "my iPhone arrives home" or "nobody is here any more".
What you get
One Gladys device per device visible in Find My on iCloud.com (iPhone, iPad, Mac, Apple Watch, and the AirPods Apple lists there), with these measurements:
| Measurement | Type | What it is for |
|---|---|---|
| Presence | Binary | The scene trigger (1 = at home) |
| Distance from home | Decimal (km) | Follow how far away you are, pre-heat the house |
| Position accuracy | Integer (m) | Tell a GPS fix from a Wi-Fi guess |
| Position | Text | "latitude,longitude", handy when debugging |
| Position age | Integer (min) | Spot a device that stopped reporting |
| Battery | Integer (%) | Alert on a low battery |
| Charging | Binary | Know whether the device is plugged in |
| Ring | Button | Plays the Find My sound on that device |
Battery and charging only show up on devices that report them: an accessory has neither.
Ringing a device from the dashboard
Every measurement above is read-only, but Ring is a button: put the device on a dashboard and its "Push" button plays the Find My sound on that iPhone, iPad, Mac or Apple Watch — the same thing the Find My app does. It is a push button, not a switch: nothing to turn back off, one press is one ring. A scene can press it too ("when the doorbell rings at night, ring my iPhone").
The Make a device ring action of the Configuration tab does exactly the same and is still there: it is the way to ring a device you have not added to Gladys yet.
Already have your devices in Gladys? Gladys never changes the features of a device you created on its own: open the Discovery tab of the integration and click Update on each device for the button to appear.
AirTags are not reported. Apple does not serve them through the Find My web API: their position is end-to-end encrypted and only ever decrypted by the Find My app on an Apple device. iCloud.com itself only shows the "Devices" tab, never the "Items" one — so no integration signing in to an iCloud account can see them. The integration still reads the accessory lists in case Apple starts serving them: they would then be discovered without a new release.
Configuration
- Open the Configuration tab of the integration.
- Fill in your Apple ID (the email of the iCloud account) and your password. Gladys stores them encrypted and only sends them to Apple.
- The latitude and longitude of your home are pre-filled with the
position of your Gladys house: leave them alone unless you want another
reference point. If they stay empty — a house created without an address —
click Get the coordinates of my Gladys house (the action tells you what
is blocking), or type them in decimal degrees (
48.8566,2.3522, copied from any map service). Set the radius inside which a device counts as present (150 m by default — raise it if you have a large property, or if your devices are often located through Wi-Fi). - Save.
Two-factor authentication
If your account uses two-factor authentication — Apple's default — a 6-digit code appears on your Apple devices right after you save. The integration explicitly asks Apple to send it: an account with no trusted device (only a phone number) receives it by SMS.
- Note the code. The message shown in the Configuration tab says where it was sent (trusted devices, or phone number).
- In the Configuration tab, click Send the two-factor code, type it in and validate.
- The integration then asks Apple to trust this session, so the code is not requested again on the next restarts (Apple keeps that trust for roughly 30 days, sometimes less).
If nothing arrives, click Send me a new two-factor code: Apple sends another one (push first, SMS as a fallback) without starting over. And when the notification still does not show up on your devices, Send me the code by SMS forces it to a trusted phone number.
Advanced settings
- Refresh interval (
poll_frequency, 300 s by default): how often the integration asks Apple for a new position. This is the first knob to turn — shorter means a more reactive presence, but more calls to Apple and more battery used on your devices. The minimum is 60 s. Gladys itself cannot poll slower than once a minute: between two real refreshes the integration simply answers with the last known position. Whatever the setting, it never calls Apple more than once every 30 seconds, and a single call covers all your devices. - Maximum accuracy (500 m by default): a position reported with a wider uncertainty radius is ignored. Without that guard, a position derived from a carrier Wi-Fi network would make your presence jump by kilometers.
- Include family devices: also expose the devices shared through Family Sharing.
Presence hysteresis
A device becomes present as soon as it enters the radius, but only becomes absent past 125% of the radius. With a 150 m radius, it has to go beyond 187 m to count as gone. That is what keeps a phone sitting at the edge of the zone from firing your scenes over and over because of GPS noise.
Actions
- Send the two-factor code — validates the 6-digit code and gets the session trusted by Apple.
- Send me a new two-factor code — asks Apple for another code: a push to the trusted devices, or an SMS when the account has none.
- Send me the code by SMS — forces the code to a trusted phone number, even when the account has trusted devices.
- Get the coordinates of my Gladys house — fills the latitude and longitude from your Gladys house, and shows the exact error when Gladys does not serve them. Reload the page to see the filled fields.
- Test the iCloud connection — signs in again and shows how many devices were found, with their names.
- Forget the saved session — deletes the stored tokens. Use it when the connection is stuck in an odd state: the next sign-in starts from scratch (and will ask for a new two-factor code).
- Make a device ring — pick one of your devices and it plays the Find My sound. Handy to find a phone in the sofa, and the way to ring a device you have not added to Gladys yet. Devices you did add carry the same button on their dashboard card (see above).
Troubleshooting
"iCloud connection failed: ...": the message repeats Apple's own answer. The usual causes are a changed password, an account temporarily locked after too many attempts, or a session that needs approving again.
No two-factor code arrives: use Send me a new two-factor code, then Send me the code by SMS. The message shown in the Configuration tab repeats the reason Apple gave when it refused to send anything. Then check on appleid.apple.com that the account really has a trusted device or a trusted phone number — without one of the two, Apple has nowhere to send it.
The coordinates stay empty: the integration reads the position of your
house through the Gladys API, which needs the location permission (declared
in its manifest) and a house with an address (Settings → House). The Get the
coordinates of my Gladys house action shows the exact reason it was refused.
My AirTag does not show up: expected, and nothing the integration can fix (see the note above). Apple only gives the position of Find My items to the Find My app on an Apple device. To trigger a scene on an object, track a device that does report its position (iPhone, Apple Watch), or use a tracker from another brand with its own integration.
No device shows up: check that Find My iPhone is enabled on those devices (Settings → your name → Find My). A device that has been off or offline for a long time may report no position at all; it appears in Gladys but without presence until Apple has something recent.
The device I just added stays empty: its values are published as soon as it is created, then on every refresh. If it stays empty, check the Configuration tab (the integration must be connected to iCloud) and the Accuracy reading: a device Apple has no position for gets neither presence nor distance.
"No recent value" on the dashboard: Gladys considers a value outdated when nothing has been published for it for a while (48 hours by default). The integration re-publishes every value at least every 30 minutes, so this should only show up when the integration is stopped, cannot sign in to iCloud any more (check the Configuration tab) or when the device reports no position at all.
The "Ring" button is missing: the device was created before the feature existed. Open the Discovery tab of the integration and click Update on that device.
The device does not ring: the sound is played by Apple, not by Gladys. A
device that is off, offline or long asleep only rings the next time it comes
back online. The error message repeats Apple's own answer; LOG_LEVEL=debug
gives the full detail in the logs.
Presence never moves: look at the Position accuracy measurement. If it is close to or above your "Maximum accuracy" setting, positions are being ignored — raise the threshold, or the home radius.
The two-factor code is asked for often: Apple decides how long a session stays trusted. Avoid changing the password or revoking sessions from appleid.apple.com.
The integration logs everything it does: read its logs from the Gladys
interface (or docker logs on the host), with LOG_LEVEL=debug for the full
detail.
Good to know
Apple publishes no official API for Find My. This integration uses the same interface as the icloud.com website, with the same secure sign-in mechanism (SRP: your password never leaves your machine, only a cryptographic proof is sent). Apple can change that interface without notice: if the integration stops working overnight, that is the most likely cause.
Your credentials stay with you, in your Gladys instance, and never go through any third-party service.
Configuration settings
These are the settings Apple Device Tracker asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your iCloud account | section | No | This integration signs in to iCloud with your Apple ID and reads the position of the devices visible in Find My. Your credentials stay in Gladys, on your machine. Two-factor authentication is supported: after saving, use the action below to enter the 6-digit code Apple sends you, and the "Send me a new two-factor code" action if nothing arrives. |
| Apple ID | string | Yes | The email address of the iCloud account that owns the devices. |
| Apple ID password | secret | Yes | Stored encrypted by Gladys and only sent to Apple. Changing it forces a new sign-in. |
| Your home | section | No | A device is considered present when it is inside the radius below. The coordinates are pre-filled with the position of your Gladys house: correct them only if you want another reference point. |
| Home latitude | string | No | Decimal degrees between -90 and 90 (example: 48.8566). Pre-filled from your Gladys house when left empty. A text field, so the decimals are never rounded. |
| Home longitude | string | No | Decimal degrees between -180 and 180 (example: 2.3522). Pre-filled from your Gladys house when left empty. A text field, so the decimals are never rounded. |
| Home radius (m) | number | No | Radius around your home marking a device as present. A device leaves only once it is 25% beyond it, to avoid flapping. |
| Advanced | section | No | Apple rate-limits Find My: keep the refresh interval reasonable. Positions less accurate than the threshold below are ignored instead of moving your presence around. |
| Refresh interval (s) | number | No | How often the integration asks Apple for a new position, in seconds. Gladys itself ticks every minute (its own limit) and the integration answers from its cache until this interval has passed. |
| Maximum accuracy (m) | number | No | Positions reported with a worse accuracy radius than this are ignored. |
| Include family devices | boolean | No | Also expose the devices shared with you through Family Sharing. |
How to install Apple Device Tracker in Gladys
- In Gladys, open Integrations: Apple Device Tracker appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-appledevicetracker:1.0.4), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-appledevicetracker.
Apple Device Tracker requires Gladys >=4.86.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Apple Device Tracker is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation