Find, ring and watch an accessory over direct BLE

[ubrt]

Implements #17, and carries the rest of the BLE work with it.

Both branches live here at your suggestion, since debugging the Bluetooth side as a user is much easier when the signal strength and the other BLE details are on screen at the same time.

Ringing an accessory

• DeviceInfoActivity: a "Play Sound Nearby" menu entry, one shot.
• MapsActivity: the Ring button on the tag card is a continuous ping toggle. Scan, trigger, pause, repeat until tapped again.

Both show live progress: Scanning, Connecting, Sending, result.

Ringing is a repeating burst rather than a continuous tone. Tapping to sounding takes roughly five seconds, the chirp runs a few seconds, then there is a gap, so while walking you get a burst every several seconds rather than something to home in on. The gap is a single constant, CONTINUOUS_PING_PAUSE_MS, currently 4 s.

Rationale for the FindMy.py / Java split is in my issue comment.

Seeing a tag that is in the room

A passive scan runs while a screen is open. Under its own "Over Bluetooth" heading, the device screen shows when the tag was last heard, its signal strength, and the battery level the accessory broadcasts.

The battery reading is persisted per tag, with the time it was heard. Nothing is copied from Apple's own battery field: that value is stale or unset for exactly the users this is for, and would arrive presented as something the phone had heard.

Where the phone was when it heard a tag is written as a location report of its own, marked local in a provenance column so it can never be confused with a decrypted one. The map draws it like any other position, which is what answers "you left it somewhere in this building".

Listening while the app is closed

An opt-in foreground service, off by default, with a permanent notification. Without it the radio only runs while a screen is open, which keeps the app a display feature. With it the app records, which is why it is opt-in and why the setting says so in its own text.

With the service running, a tag that goes quiet while the phone moves on raises a left-behind alert. A targeted verification scan runs before alerting, so silence only has to be worth checking rather than having to prove anything on its own.

The alert is per tag and off by default, since most tags a person owns are put down on purpose. The wait before it fires and the sound it makes are configurable, and it plays on the alarm stream on repeat until the notification is swiped: a chime at notification volume from a pocket is the thing that gets missed.

Finding the tag: the key derivation

The addresses worth scanning for come from the stored key alignment, extrapolated forward at one index every fifteen minutes.

The candidate margin is 48 hours, derived rather than chosen. One secondary key covers 192 primary indices, so a sighting matched through one places the tag no more precisely than that.

A window too wide to derive is cut to its newest thousand indices. A tag advertising right now has been running, so its index tracks the clock and sits at the top of the window; the bottom belongs to a tag that was switched off for months and has nothing to match anyway.

A primary-key match corrects the alignment in either direction. update_alignment only moves forward, which is right for a fetch and wrong for a BLE match: that comes from a wide, symmetric window and can legitimately land below where alignment believes the tag is, which is proof it has run ahead. Correcting that means writing the serialized state directly, with update_alignment's backward-time guard re-implemented so the bypass does not lose it. This is the piece I would rather push upstream than keep as a bypass.

Only a primary match writes an alignment. A secondary key is reported at the first index the search reaches, so its index is a lower bound rather than a position. A secondary match therefore only raises the floor, upward, which can undershoot the truth but never overshoot it.

Each candidate address is paired with the index it came from, and a sighting hands that back as a hint, so confirming an alignment costs three key derivations at one index rather than the whole window again: 0.02 s against 1.02 s for the same answer.

Derived addresses are kept across launches, in a file per tag. An address is a pure function of the accessory's keys and an index, so a stored one can never be wrong, only incomplete, and a rebuild asks Python only for the part it is missing. The index is kept only for primary keys, which sit at one index forever; a secondary key's index depends on where the deriving range began, so it is stored as unknown rather than as a number that would later be believed.

WideningSearch looks progressively further back for a tag nobody has heard: five hundred indices at a time, at most one tag a minute, never in the first two minutes after a scan starts, and only for tags not heard in the last ten. It stops when the tag turns up or when it reaches a hundred days. See the caveat below.

What it costs

Key derivation, desktop	3.3 s per 1000 indices, linear from 500 to 9600
Key derivation, idle phone	1.8 to 2.9 s per 1000
Key derivation, phone during app startup	15 to 33 s per 1000
Python interpreter warm-up	11 to 12 s, once per process
Addresses produced	about one per index: keys_between de-duplicates, and secondary keys collapse
Stored index, in memory	136 bytes per entry as a HashMap<String, Match>

The warm-up is the reason nothing expensive runs in the first two minutes after a scan starts, and the reason the derived addresses are kept: on a cold start with a populated store, a tag costs one index of derivation rather than several hundred.

Limits worth knowing

WideningSearch is not backed by an observation. It exists on the theory that a tag whose index has drifted far below the extrapolation would otherwise never be found. I have no measurement showing that happens to a tag that stayed powered: the index follows the tag's own clock rather than network contact, and the bounded slice already allows about ten days of slack. It is tested and it costs nothing for a tag that is heard, but I would not defend it as necessary.

This branch therefore also carries the measurement that would settle it. When a fetch moves a tag's alignment, that is a real observation of where the tag was, and extrapolating the previous alignment forward to the same moment gives the drift directly. It is appended to a file in the app's external files directory rather than only logcat, since the reading is worth something as a series over weeks and logcat on a busy phone holds minutes.

Owner-nearby does not work. With the owner present, a 15 second scan sees the owner-present short form (12 02, one observed at −49 dBm) and nothing derived from the key schedule matches it. It fails at detection, not at connect or write, which is consistent with stek29's note that authorised playback is a separate, L2CAP based mechanism. Worth knowing when testing: a tag sitting near an iPhone looks missing, and that has been mistaken for a bug more than once.

Not tested: Google Find My Device accessories, third-party brands beyond the one below, and Android versions other than 17.

Attribution

The protocol constants and fallback order in ble/BleGattSoundTrigger.java derive from AirGuard (Apache-2.0). A NOTICE names what is derived and from where. AirGuard ships no NOTICE of its own and its LICENSE has no copyright line filled in, so the file attributes the project rather than restating a notice its authors never wrote.

Testing

Pixel 10 Pro, Android 17, release build, over several days of ordinary use.

Ringing runs through to DONE (SUCCESS) on real AirTags and on a third-party FineTrack Mini Smart Finder. The passive scan, the alignment correction, the local position write and the background service have each been observed working on a device.

Suites: 348 JVM, 269 Python bridge, 346 strings in each of the ten locale files, flake8 and pyright clean.

The instrumented suite has not been run against this state. It passed at 568 with 5 ignored and 0 failures on aosp-atd, and the two migrations added here are additive, but I have not put a number behind that and will not imply one.

Pin

The FindMy.py pin points at parawanderer/FindMy.py@ddc7f234, so the blocker this PR opened with is resolved.

[ubrt]

Marking this as work in progress — please hold off merging.

Testing with two real third-party Find My accessories surfaced a reliability gap: an accessory's stored key alignment can drift ahead of its true index, and once that happens the 12h search margin alone doesn't recover it (one of the two needed a multi-day margin to be found at all, which isn't a fix, just a wider blind spot).

Root cause: update_alignment only refuses to move backwards, so anything that feeds it a matched key's index — a network fetch, or the sighting-feedback this branch just added in recordAccessorySeen — can push alignment past the true index and never come back, if that index came from a secondary key match. A secondary key covers ~96 primary indices, so its first-match index in a search window is only a lower bound, not the true one. Only a primary-key match identifies the index uniquely enough to trust.

Working on a fix that restricts alignment corrections (both the BLE feedback path here and the existing network-fetch path) to primary-key matches only, and allows correcting downward when one disagrees with the stored value. Will follow up once it's tested end to end — a real AirTag test is planned for next week, which should also cover ground this branch hasn't (only third-party accessories tested so far).

[parawanderer]

Agreed, holding. Confirming the network half from the pinned source so you don't have to re-derive it — findmy/reports/reports.py:456:

for i in sorted(key_to_ind[key], reverse=True):
    accessory.update_alignment(report.timestamp, i)

key_to_ind is populated from both cur_keys_primary and cur_keys_secondary, so a report that decrypts against a secondary key feeds its lower-bound index straight in. Same mechanism, already shipping — this branch adds a second door to a room the app is in already. Which also means a drifted tag gets harder to find over the network, not just over BLE, and presents as "stopped updating" with nothing in the logs.

Note I pushed to your branch while you were writing this (rebase onto main, pin moved to the merged 254a7624, plus a 12h margin and the sighting feedback). The feedback half is exactly what you're describing as unsafe — I took the docstring's "safe to hand over regardless" at face value and you've disproved it on hardware. Happy to drop it and leave the field unused until your fix lands, or leave it in place for you to build on; your call, since you're the one testing it.

@parawanderer has an AirTag and an owner iPad that can be powered off for the separated case, so the AirTag gap is coverable here too if that's useful alongside your test next week.

---

(Reply drafted via Claude Code, reviewed by me.)

[ubrt]

Pushed the primary-key-only alignment fix mentioned above.

Also been running a passive companion build locally on top of this branch's BLE work: live battery and signal strength for owned tags on the map and device info screen while in range. Mainly useful as a simple way to tell whether you're actually receiving anything from the tag at all - watching the reading update live, per advertisement, is what made it obvious something was wrong when a tag stopped being found despite sitting right next to the phone. Never pinned down what originally caused that drift, but the fix closes a real gap in how a match got trusted, and the tag has stayed found since. Not part of this PR, still iterating; may open it separately later.

If you want, it would really help if you tested with your own AirTag too :)

[parawanderer]

Quick note I wanted to drop here before I go all in on my own review as I am finishing up the other open items I still had for 1.1.0: so the app now optionally connects to iCloud. When it does fetch your tags from iCloud, if you enable the debug option in Settings, you'll see that on the "My Devices" device page of every AirTag it has the battery status as reported by iCloud on it. Now I think currently I only get the list from iCloud every 6 hours (I will probably tweak it because iPads update more frequently), but I'm curious if that matches the status you're seeing the tags report by bluetooth? 🤔

[ubrt]

Good question. Two things worth knowing about what the Bluetooth side reports before comparing:

The advertisement only carries a 2-bit battery field, so it is one of four coarse levels (full / medium / low / critically low), not a percentage. It's the same encoding FindMy.py's BATTERY_LEVEL map reads. So the comparison can only ever be "same bucket or not".

On my two third-party tags there is nothing to compare against, which is itself the interesting result: both were imported via the iCloud account connection (not the zip import), and the iCloud record still reports battery level 0 ("not yet reported") for both. So for these tags the BLE reading is the only battery signal that exists at all. Presumably only Apple's own devices ever write that field for third-party accessories, or these vendors never report it. Your AirTags may well behave differently there, so your comparison would cover the case mine can't.

More generally: for anyone without an Apple device around (this app's core audience, arguably), BLE is the only battery source there is, whatever iCloud's refresh interval. The design question that actually falls out of this is persistence: right now my build only shows the BLE value while it's live and lets it age out. Should a sighting's battery level be persisted and shown as "last known (from BLE, at time X)" until a fresher value arrives from whichever source? Curious what you think.

The passive-watch build lives on my fork if you want to poke at it: https://github.com/ubrt/OpenTagViewer/tree/feature/nearby-tag-status (built on top of this PR's branch; not proposing it here, still iterating).

[parawanderer]

Coming off my sprint to implement the whole iCloud stuff here just to answer your question @ubrt (I will check your work tomorrow or as soon as I am able to with my devices). But basically I would say that: yes you should save that battery status information and probably the time it was recorded too. It's useful for the owner of the tag to have, imo. I would combine that storage with the persistence of the BLE scans as an alternative source of location history - on top of the apple FindMy network reports (to the extent that you fill the fields of the LocationReports with BLE info).

Anyways, I highly recommend you rebase on main right now to pull all the iCloud changes since I think those are more or less complete now and have a bunch of account state management bug fixes.

[parawanderer]

@ubrt so far, so good.

I'm thinking it might be nice to reuse some free-to-use battery icon for the battery state in the main UI in place of the current "Battery" text to make the main map page easier to parse. I'm sure there should be something like this available already for free reuse, with 4 battery states. WDYT?

Also, I guess that if we merge your work into the app, the limitation will remain that when the tags are in their owner-connected state they will not be able to be locatable, right? Maybe it's worth typing up an issue summarising the state of that limitation in this repository, so somebody who is interested in investigating that further has a nice basis to start from. I suspect you might have a bit more context on this than me, so maybe you could have e.g. Claude Code summarise your knowledge on that in a new issue post here (and I can add anything I ran into over the last year with this topic below it - but really I haven't touched the Bluetooth all that much at all).

I think that after merging your changes here, that would leave the app's limitations at:

• Spike: can an AirTag be registered without an iPhone or iPad? (BLE reverse engineering) #166 registering tags to Apple via the app (currently outright requires actual iOS or iPadOS to register them; minor annoyance I guess)
• Spike: contribute location reports back to the Find My network, instead of only consuming it #167 pushing anonymous location updates for tags near you to apple FindMy from the app (honestly not really needed in practice, but it's not covered by anything I've ever found)
• Locate the owner's own Apple devices properly, via the Find My iPhone service #131 grab the non-FindMy network location updates for devices that actually do show up on the official website (I consider this redundant work since there's an existing solution for it, but it might be nice to add the compatibility - this requires digging through the existing iCloud endpoints that were already added in my FindMy fork basically).
• And then detecting a tag you have all the keys for already while it is in the Owner-connected state. I made Claude code write a summary document on anything I was aware of regarding this state here but there is no issue in this repo for that topic yet.

[parawanderer]

Heads up on an overlap with #173, which is likely to merge first.

LocationReport.provenance says its reason for existing is the export:

The column exists because the history is exported. Without it the CSV hands somebody a file
where their own phone's positions sit unlabelled among Apple's, and nothing in the file says
which is which.

This PR does not touch HistoryCsvWriter or HistoryZipWriter, so that is currently unwired.

Meanwhile #173 rewrites the history CSV (adds beacon_id, a requiredHeaders() contract shared
between writer and reader) and adds an importer that restores rows from it. When both are in:

• the CSV still will not carry provenance, so the column's own justification goes unmet
• and importing a history exported after this PR would restore every row with provenance
  defaulting to apple, silently relabelling the user's own local sightings as network reports.
  Those are different claims: Bluetooth range against a hundred metres or worse.

Nothing to change here yet. Just flagging that once #173 lands, this PR owns adding provenance to
requiredHeaders(), the writer and the importer, since neither PR can see the problem on its own.

---

This comment was written by Claude Code.

[ubrt]

I did two tests this week while keeping the AirTag offline, and both were successful. The signal was detected and the sound was triggered.

In my case, there was a slight delay of around 30 seconds after I unwrapped the AirTag. It could be that the device uses a longer interval between pings when it has been disconnected from its host for an extended period of time.

I’ll finish up the remaining work next weekend. There is currently a bug with the notifications when a tag hasn’t been seen for some time, the alert never stops in some cases.

If there are no showstoppers on your side, we could merge this next week?

[parawanderer]

Hi @ubrt, nice! For me I've been testing it around town when I remember and it's been looking good so far. I haven't found any bugs with your mechanism though I did not test the alert. Totally cool to merge this after you fix the bug you found and then release this as part of the 1.1.0 version of this app!

[ubrt]

"Also, I guess that if we merge your work into the app, the limitation will remain that when the tags are in their owner-connected state they will not be able to be locatable, right? Maybe it's worth typing up an issue summarising the state of that limitation in this repository, so somebody who is interested in investigating that further has a nice basis to start from."

From my knowledge, this is a hard limitation with no chance to work around. If the host device is in range the tag and host are connected with a real end to end bluetooth connection. So the tag stops sending beacons and disables the public service for ringing.

[parawanderer]

@ubrt right okay, fair enough, I will write up my own knowledge on the topic separately then.

Let me know when you feel comfortable to merge this and create a release including this then!

[ubrt]

Just pushed the remaining fixes for the lost device notifications. From my side this is now ready to merge. Please feel free to give everything a final test :).