Skip to content

Linux + iPhone Continuity / iMessage / SMS

fix: update airpods handoff for ios27 changes

Zack Bartela47b0f3d7cd5
diff --git a/docs/BLUETOOTH.md b/docs/BLUETOOTH.md
index 700d322..f1929ad 100644
--- a/docs/BLUETOOTH.md
+++ b/docs/BLUETOOTH.md
@@ -547,6 +547,14 @@ that has finished its call is exactly what a reclaim takes the buds from, and an
`0x17` stays there until another host claims. The iPhone keeps the owner bit until another host
claims, so ownership alone never means "still using them" either; that needs the audio source.
+**The owner bit is corroboration, not the decision.** It is dependable on some setups and not on
+others, and the difference is not visible from here. Measured 2026-09-15: on one machine the phone
+moves `0x05` idle to `0x07` owning on every handoff, exactly as the table says; in the log attached
+to #193 the same iOS version reports `0x05` while the audio-source notification names that phone as
+the host the buds are carrying media for -- either it never took ownership, or its host list was
+never refreshed, and the two are indistinguishable in a log that only records changes. What the buds
+carry, and for whom, is the audio-source notification, and that is what `peer_busy()` reads.
+
The AC reference reads the low values as validation state instead (`0x00` validated,
`0x01` pending, `0x02` unvalidated, `0x03` both, `0x05` a stuck session) and says ownership is not
in this field. That does not match this hardware: our own entry alternates `0x00` and `0x02` in
@@ -701,10 +709,20 @@ the stem sets is the volume of whoever owns them.
**It runs on what the other hosts report through the buds**, the smart-routing media reports
above. No timer decides anything, and it does not need call control.
-- **A call on the phone gives the buds up** the moment the phone reports category `501`, before it
- takes them. **Media on the phone gives them up** once the phone both reports it playing and owns
- the buds (`AirPodsState::peer_busy()`): an iPhone playing on its own speaker does not take them
- from a Mac, and does not take them from here.
+- **The phone gives the buds up once it is actually using them**, call or media alike: it reports
+ itself playing *and* the buds report their audio going to it (`AirPodsState::peer_busy()`,
+ `peer_holds_the_audio()`). Neither half decides alone -- an iPhone playing on its own speaker
+ reports the same media, and the owner bit answers nothing, having been seen idle on a phone the
+ buds were carrying media for.
+- **A call report is not a yield.** Announcing a call is not taking the buds. Tether held a version
+ that released on category `501` before the phone claimed; measured 2026-09-15 over four calls on
+ one iPhone, the two where Tether released first were the two where the buds never carried the
+ call -- no audio-source notification for the phone at all -- while the two where the phone claimed
+ first (`audioRoutingSetOwnershipToFalse`, owner bit to `0x07`) routed within a second. Releasing
+ early hands the phone a device whose owner has just vanished and whose transport is down. The
+ call report still holds *this* machine's claims back (`takes_over_for_play()`), and losing the
+ owner bit still pauses local playback on the spot, so nothing reaches the speakers while the
+ phone takes over.
- **The phone reporting `NO` takes them back**, and resumes what the release paused.
- **A player starting here takes them**, wherever they are, unless the phone is on a call. MPRIS
`PropertiesChanged` drives it (`MediaControl::watch()`). With the card down the player is paused
diff --git a/src/core/include/tether/bluetooth/airpods.hpp b/src/core/include/tether/bluetooth/airpods.hpp
index f535fc7..40d9f9f 100644
--- a/src/core/include/tether/bluetooth/airpods.hpp
+++ b/src/core/include/tether/bluetooth/airpods.hpp
@@ -128,6 +128,7 @@ namespace tether::bluetooth {
// Another host reports a call or media playing, from its own smart-routing reports.
bool peer_audio = false;
bool peer_call = false;
+ bool peer_holds_audio = false;
bool local_audio = false;
std::optional<bool> owns;
AirPodsBattery battery;
@@ -138,10 +139,8 @@ namespace tether::bluetooth {
// Written for display, shown verbatim.
std::string reason;
- // What handoff yields to: a peer on a call, which always takes the buds, or a peer that owns
- // them and is playing through them. Ownership alone is not enough, because the phone keeps
- // it until another host claims.
- bool peer_busy() const { return peer_call || (peer_active && peer_audio); }
+ // What handoff yields to. A peer that is playing, call or media, and has the buds' audio.
+ bool peer_busy() const { return peer_holds_audio && peer_audio; }
bool operator==(const AirPodsState&) const = default;
};
@@ -171,6 +170,11 @@ namespace tether::bluetooth {
// Whether a session that has claimed the buds to validate itself should hand ownership straight back.
bool releases_when_idle(bool local_audio, bool peer_present, bool yielded);
+ // Whether the buds are carrying audio for a host other than `local`, folded from one audio-source
+ // notification into the previous answer. A source of `None`, and the all-zero address the buds send
+ // with it, leave it alone: iOS sends `NONE` every twenty seconds or so during a live call.
+ bool peer_holds_the_audio(bool current, const AudioSourceEvent& event, const std::string& local);
+
// `otherDeviceAudioCategory` in a host's media report, as an iPhone sends them.
inline constexpr int AUDIO_CATEGORY_NONE = 100;
inline constexpr int AUDIO_CATEGORY_MEDIA = 301;
diff --git a/src/core/src/bluetooth/airpods.cpp b/src/core/src/bluetooth/airpods.cpp
index df9873a..5c3331d 100644
--- a/src/core/src/bluetooth/airpods.cpp
+++ b/src/core/src/bluetooth/airpods.cpp
@@ -251,6 +251,7 @@ namespace tether::bluetooth {
{"peer_active", s.peer_active},
{"peer_audio", s.peer_audio},
{"peer_call", s.peer_call},
+ {"peer_holds_audio", s.peer_holds_audio},
{"status", to_string(s.status)},
{"reason", s.reason},
};
@@ -462,6 +463,14 @@ namespace tether::bluetooth {
return peer_present && !local_audio && !yielded;
}
+ bool peer_holds_the_audio(bool current, const AudioSourceEvent& event, const std::string& local) {
+ // The address the buds send with a source of `None`.
+ constexpr const char* NO_HOST = "00:00:00:00:00:00";
+ if (event.source == AudioSource::None || event.address.empty() || event.address == NO_HOST)
+ return current;
+ return event.address != local;
+ }
+
namespace {
// Apple's OPACK, the subset smart routing uses: one dictionary of strings, integers and booleans.
@@ -1052,6 +1061,8 @@ namespace tether::bluetooth {
// Another host is attached to the buds, this machine is playing through them.
bool peer_present = false;
bool local_audio = false;
+ // The buds' audio is going to another host.
+ bool peer_holds_audio = false;
// The buds' host list, and each host's latest media report.
std::vector<AapPeer> hosts;
std::map<std::string, SmartRoutingMessage> reports;
@@ -1126,6 +1137,10 @@ namespace tether::bluetooth {
if (!send_ownership(fd, false))
break;
owns = false;
+ {
+ std::lock_guard<std::mutex> lock(mutex);
+ state.owns = false;
+ }
}
continue;
}
@@ -1168,6 +1183,11 @@ namespace tether::bluetooth {
delivered = true;
owns = buffer[sizeof(OWNS_CONNECTION_PREFIX)] == 0x01;
debug::log(DEBUG, "airpods: ownership verdict {:#04x}", buffer[sizeof(OWNS_CONNECTION_PREFIX)]);
+ {
+ std::lock_guard<std::mutex> lock(mutex);
+ state.owns = owns;
+ }
+ publish(AirPodsStatus::Live, "");
continue;
}
@@ -1201,12 +1221,20 @@ namespace tether::bluetooth {
std::lock_guard<std::mutex> lock(mutex);
local = local_address;
}
+
+ const bool held = peer_holds_the_audio(peer_holds_audio, *source, local);
+ bool changed = held != peer_holds_audio;
+ peer_holds_audio = held;
if (!local.empty() && source->address == local &&
local_audio != (source->source != AudioSource::None)) {
local_audio = source->source != AudioSource::None;
+ changed = true;
+ }
+ if (changed) {
{
std::lock_guard<std::mutex> lock(mutex);
state.local_audio = local_audio;
+ state.peer_holds_audio = peer_holds_audio;
}
publish(delivered ? AirPodsStatus::Live : AirPodsStatus::Connecting, "");
}
@@ -1324,6 +1352,7 @@ namespace tether::bluetooth {
pending_take_over = false;
state.peer_audio = false;
state.peer_call = false;
+ state.peer_holds_audio = false;
}
::close(fd);
}
@@ -1355,6 +1384,7 @@ namespace tether::bluetooth {
state.peer_active = false;
state.peer_audio = false;
state.peer_call = false;
+ state.peer_holds_audio = false;
state.local_audio = false;
state.owns.reset();
}
@@ -1377,6 +1407,7 @@ namespace tether::bluetooth {
state.peer_active = false;
state.peer_audio = false;
state.peer_call = false;
+ state.peer_holds_audio = false;
state.local_audio = false;
state.owns.reset();
}
diff --git a/test/test_airpods.cpp b/test/test_airpods.cpp
index 6ee228f..68fecfc 100644
--- a/test/test_airpods.cpp
+++ b/test/test_airpods.cpp
@@ -419,21 +419,44 @@ TEST(AirPods, BuildsTheTakeOverMessages) {
EXPECT_TRUE(decoded->set_ownership_to_false);
}
-// Handoff yields to a phone that owns the buds and is playing through them, or to a call, which
-// always takes them. Ownership alone is a phone that finished and kept the bit; media alone is a
-// phone playing on its own speaker.
-TEST(AirPods, YieldsToAnOwnerWithAudioOrACall) {
+// Handoff yields to a phone that is playing and has the buds' audio. The audio alone is a phone
+// that stopped; the report alone is a phone playing on its own speaker. Neither the owner bit nor
+// an announced call decides it: a phone that says it has a call has not taken the buds yet.
+TEST(AirPods, YieldsToAPhoneHoldingTheAudioAndPlaying) {
AirPodsState state;
- state.peer_active = true;
+ state.peer_holds_audio = true;
EXPECT_FALSE(state.peer_busy());
state.peer_audio = true;
EXPECT_TRUE(state.peer_busy());
- state.peer_active = false;
+ state.peer_holds_audio = false;
+ EXPECT_FALSE(state.peer_busy());
+ // An owner that is not carrying the audio is still not using them.
+ state.peer_active = true;
EXPECT_FALSE(state.peer_busy());
+ // Nor is a call the phone has only announced: releasing ahead of its claim is what broke it.
state.peer_call = true;
+ EXPECT_FALSE(state.peer_busy());
+ // The call once the buds are actually carrying it.
+ state.peer_holds_audio = true;
EXPECT_TRUE(state.peer_busy());
}
+// Who the buds are carrying audio for, folded one notification at a time.
+TEST(AirPods, TracksWhichHostHasTheBudsAudio) {
+ const std::string local = "02:00:00:00:00:02";
+ const AudioSourceEvent phone{"02:00:00:00:00:04", AudioSource::Media};
+ const AudioSourceEvent here{local, AudioSource::Media};
+ const AudioSourceEvent nobody{"00:00:00:00:00:00", AudioSource::None};
+
+ EXPECT_TRUE(peer_holds_the_audio(false, phone, local));
+ EXPECT_TRUE(peer_holds_the_audio(false, {"02:00:00:00:00:04", AudioSource::Call}, local));
+ EXPECT_FALSE(peer_holds_the_audio(true, here, local));
+ // iOS sends NONE every twenty seconds or so during a live call: it settles nothing.
+ EXPECT_TRUE(peer_holds_the_audio(true, nobody, local));
+ EXPECT_FALSE(peer_holds_the_audio(false, nobody, local));
+ EXPECT_TRUE(peer_holds_the_audio(true, {local, AudioSource::None}, local));
+}
+
// This machine's own entry rises with its own ownership and is never a peer.
TEST(AirPods, SummarisesPeersWithoutCountingItself) {
const std::vector<AapPeer> peers = {{"02:00:00:00:00:02", 0x01, 0x17}, {"02:00:00:00:00:04", 0x02, 0x10}};