iphonedetect finds sleeping iPhones with an mDNS probe and the ARP cache

An mDNS probe, then read the ARP cache

The mechanism is two steps and both are unusual for a presence detector. The integration sends an mDNS message to the hosts you define. The device responds if it is connected to the network, even when it is in deep sleep. That response causes an entry to be made in the ARP cache, and the integration reads that entry. The interesting part is the ordering. A conventional tracker waits for a device to announce itself, which a sleeping iPhone will not do. Probing first and then inspecting the neighbour table converts a silent device into a visible one, and that is the whole reason this component exists. The cost of that trick is that the integration has to know the address it is probing, and every operational headache in this project follows from that single design decision.

It is a device_tracker for the person integration

The intended use is described plainly in the project documentation: the integration is useful as a device_tracker for your person integration, so you can see if users are at home. That means the component does not try to be a presence system in itself. It produces entities that other parts of Home Assistant consume. Setup creates an entity named device_tracker.<name>, where the name is the one you give it, and the same steps are repeated for additional entities. The entity name you choose during setup is therefore part of your automation vocabulary, and changing it later is not something the documentation covers. Because the output is an ordinary device_tracker entity, the presence logic, the history and the dashboards are all handled by Home Assistant, which is the main argument for using a custom component here rather than writing your own polling loop.

Installing it through HACS or by copying a directory

There are two documented installation paths and neither is a command line. If you do not have HACS installed, the author recommends it, and the repository is available in the Home Assistant Community Store under the name iPhone Device Tracker, so it can be added from a repository badge or by searching for that name in the store. The manual path is to download the iphonedetect directory and place it in your <config>/custom_component location. Either way there is a step that people miss: after installation you need to restart Home Assistant before using the integration. Setup is then done through the user interface. If you do not have My Home Assistant redirects set up, you go to Settings, then Devices & Services, click Add integration and search for iPhone Device Tracker. You give the entity a unique name and enter its IP address. Since version 2.4.0 the integration can be set up from the UI, which removed the older yaml configuration route.

Static addresses and a single SSID are prerequisites, not tips

The network section of the documentation is a list of requirements rather than suggestions. You should assign a static IP address to the device you want to track, probably in your router. The alternative is to set a manual IP in the device WiFi configuration. You should avoid automatically connecting to different SSIDs, specifically the 2.4 and 5 GHz bands. Each tracked device also has a consider home timeout that you can change in the UI, with the default given as 24 seconds. A release note in the project history says the range limit for consider home was removed in version 2.4.1, so the timeout is not clamped to a narrow range. Taken together, the requirements describe a specific kind of network: one phone, one address, one band, one router. If your household has phones roaming between two access points on different bands, this integration is going to need attention rather than configuration.

Private Wi-Fi addresses are the main reason detection stops working

The troubleshooting section leads with private Wi-Fi address, and the explanation is specific. The private MAC address of a device remains the same for each network, as long as the network is not recreated or rotating MAC is used, which the documentation ties to iOS 18 and later. In other words, if a tracked device can no longer be found, the user has probably recreated the connection to the Wi-Fi, forcing a new random MAC address. The same section notes that if the Wi-Fi has different SSIDs for the 2.4 and 5 GHz bands and the phone has private network enabled, two different MAC addresses are presented to DHCP, which will most likely require tracking two IP addresses per user. The documentation's advice is blunt about the fix: for the best result, have and connect to only one SSID, turn off private network, and assign a static IP. That is a real constraint on the phone configuration, not a tuning knob.

Multiple access points produce false not_home states

The second troubleshooting entry covers flakiness. Especially when the network has multiple access points, tracked devices are sometimes marked as not_home when they are actually connected to the network. The suggested remedy is to increase the consider home timeout, though the documentation says the most likely cause is a network issue and recommends trying to place the access points at different locations. Another documented cause is timing: devices might auto-update during the night, and they will of course be not_home for a while. Both cases point at the same conclusion. The integration reports what the network neighbourhood looks like, so a network that is slow to age out ARP entries or a client that disappears for a moment will produce presence changes that have nothing to do with the person actually being at home.

What the project promises, and what it does not

The disclaimer section is unusually direct for a community integration. The author states they are in no way affiliated with Apple Inc, that they do not guarantee the functionality of the integration and are not responsible for any damage, and that product names and trademarks in the repository remain the property of their respective owners. The original idea is credited to a Home Assistant community member named return01. The licence is MIT with a LICENSE file at the repository root, and the project is published as a Home Assistant custom component with a hacs.json file and a custom_components directory. Release history shows version 2.4.0 on 2025-01-16 introducing UI setup, version 2.4.1 on 2025-02-01 removing the consider home range limit, and version 2.5.0 on 2026-07-03, with the last push on that same date. The alternative to this component is the standard device_tracker integration, which relies on the network's own view of connected clients rather than actively waking a sleeping phone with an mDNS probe, and the difference in reliability follows directly from that mechanism.

Editorial conclusion

Adopt iphonedetect if you want presence detection for iPhones in a Home Assistant setup and you can give each phone a static IP, keep it on a single SSID and turn off private network addressing. Do not adopt it as a general presence solution for mixed device fleets, because its mechanism is an active mDNS probe aimed at one IP at a time and it cannot survive a rotating MAC address. Before you install it, decide whether the consider home timeout of 24 seconds suits your network, watch the first week of not_home flapping on a multi access point setup, and note that the author states plainly that no functionality is guaranteed and that there is no affiliation with Apple.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mudape/iphonedetect on GitHub
4. README
5. Releases