Skip to content

Linux + iPhone Continuity / iMessage / SMS

fix: better reconnect handling after out/in range

Zack Bartel3f3cfd01bbb6
diff --git a/docs/BLUETOOTH.md b/docs/BLUETOOTH.md
index e24f035..6e38233 100644
--- a/docs/BLUETOOTH.md
+++ b/docs/BLUETOOTH.md
@@ -126,6 +126,8 @@ checks the daemon does not make.
| LE never connects and the log repeats `le-connection-abort-by-local` | Something on this side is cancelling the connection. Tether's own cause was a `PreferredBearer` write racing the async connect, fixed; anything else writing that property during a connect will do the same | Check no other Bluetooth tool is driving the same device. The phone is not the cause: `abort-by-local` means the local host cancelled |
| Notifications stopped and never came back, while messages and contacts kept working | Fixed. The bearer supervisor used to stop retrying LE after six attempts, and only a Classic drop or a daemon restart re-armed it | Nothing. The solicitation is kept on air whenever LE is down, which is what the iPhone answers -- see 2026-08-22 |
| `tether --bt-status` reports `Bond: BR/EDR only` | The bond was made without cross-transport key derivation, so it has no LE half and can never carry ANCS | Forget this computer on the iPhone and pair again. Check `secure-connections` in the same output first: re-pairing cannot help while it is off |
+| Walked back into range and nothing reconnected for minutes | Fixed. The ANCS advert was gated on the Classic link, and the Classic backoff had no event that ended the absence | Nothing. The advert stays on air whenever LE is down, and an LE link coming up clears the Classic backoff -- see 2026-08-22 |
+| Startup logs `StartNotify not ready yet (InProgress)` for up to a minute | GATT discovery is still running on the new LE link | Nothing. It subscribes on its own. Only treat it as the 2026-08-19 hang if the LE link never comes up |
| The status says the iPhone is not answering on LE, and its permission is on | The phone's Bluetooth stack is wedged, which the granted permission does not prevent | Turn Bluetooth off and back on **on the iPhone**. Re-pairing and re-toggling the permission do not clear this |
| Everything connects but `ancs_ready` stays false | Compatibility mode, or iOS has not authorized notification content yet | Check `Mode:` in `tether --bt-status`. In full mode the daemon retries, the first request returns `NotPermitted` until the prompt on the phone is approved |
| A group conversation cannot be replied to | Working as designed until the route is unambiguous | The thread's `reply_reason` says which condition failed |
@@ -757,3 +759,145 @@ phonebook is personal data, and the cache and journal are both written mode 0600
Tether's Bluetooth support is an independent implementation written against those published
findings, Apple's ANCS specification, the Bluetooth SIG MAP and PBAP specifications, and
the BlueZ D-Bus API.
+
+### 2026-08-22 - Coming back in range waited on a backoff nothing could clear
+
+Left the laptop, came back, and the log had been idle for minutes:
+
+```
+[WARN] bluetooth: BR/EDR connect failed (br-connection-unknown), retrying in 5s
+[WARN] bluetooth: BR/EDR connect failed (br-connection-unknown), retrying in 10s
+... 20s, 40s, 80s, 160s ...
+[WARN] bluetooth: BR/EDR connect failed (br-connection-unknown), retrying in 300s
+```
+
+Two halves each waiting on the other:
+
+**The advert was gated on the Classic link.** `supervise_ancs_solicitation` required
+`bearer.classic_connected`, so with BR/EDR down nothing was on air. The advert is the
+only part of this daemon that reacts to the phone returning -- the iPhone opens the LE
+link 1.3s after seeing it (2026-08-22 above) -- and it was switched off in exactly the
+state where it is the sole means of recovery. The gate no longer mentions BR/EDR.
+
+**The Classic backoff had no way to learn the phone was back.** `br-connection-unknown`
+is BlueZ's catch-all for a failed Classic connect: it covers a phone that walked out of
+range and a phone that refused, so it cannot be added to `is_transient` -- doing that
+would page a wedged phone every 5s forever. The backoff to 300s is right while the phone
+is genuinely gone. What was missing was the event that ends the absence. An LE link
+opening is that event: it is proof the phone is in range and answering. `tick()` now
+clears `classic_backoff`, `next_classic_attempt_` and `classic_failures_` on the
+false-to-true edge of `le_connected`, so BR/EDR is dialled on the same tick.
+
+Clearing `classic_failures_` matters on its own: six failures out of range had the status
+telling the user the iPhone "keeps refusing the Bluetooth connection", advice for a wedged
+phone, about a phone that had only been in another room.
+
+Together: return to range, LE comes up within seconds off the advert, Classic follows
+immediately. Neither half waits on the other any more.
+
+### 2026-08-22 - A live LE link is proof, not an event
+
+The first cut of the fix above cleared the BR/EDR backoff on the false-to-true edge of
+`le_connected`. Walking back in showed why that is not enough:
+
+```
+BR/EDR connect failed (br-connection-unknown), retrying in 5s
+... 10s, 20s, 40s, 80s ...
+```
+
+all of it with LE connected and notifications mirroring. The edge fired once, and the
+backoff then climbed unopposed against a phone that was demonstrably in range and
+answering. iOS declines the BR/EDR page for its own reasons while holding the LE link up;
+that is a "not now", not an absence, and it clears on its own within seconds.
+
+The backoff ceiling is now conditional: `LE_UP_CLASSIC_BACKOFF_MAX_SECONDS` (30s) while LE
+is connected, the full 300s only when it is not. The edge clear stays -- it still collapses
+a ceiling grown during a real absence the moment the phone answers.
+
+The same state produced worse advice. With six failures logged, `--bt-status` said the
+iPhone "keeps refusing the Bluetooth connection. Turn Bluetooth off and back on" -- about a
+phone that was delivering notifications over LE at that moment, and where following the
+advice would have broken the one bearer that was working. That string is now suppressed
+while `le_connected`, replaced with one that says what is actually true: notifications are
+connected, messages and contacts are still being reached for.
+
+**A dead OBEX session was read as a phone capability.** The same outage produced:
+
+```
+the sent folder is unavailable (Transport got disconnected); showing received messages only
+listing 'inbox' failed (UnknownObject: Method "ListMessages" ... doesn't exist); falling back to the inbox alone
+```
+
+Both are capability fallbacks -- `map_lists_sent` and `map_lists_subfolders` are latched
+off for the life of the session -- and both fired on an OBEX session that had simply gone
+away with the link. A dropped link left the daemon convinced the iPhone serves no sent
+folder and no subfolders. `map_session_dead()` now separates the two: `UnknownObject` and a
+disconnected transport skip the fallbacks entirely and reopen the session on the spot,
+rather than counting to `MAP_FAILURES_BEFORE_REOPEN` first.
+
+### 2026-08-22 - The advert was not the problem; the per-bearer Connect was
+
+A daemon start with the phone on the desk logged `br-connection-unknown` on repeat while
+ANCS was already talking GATT over LE. The obvious suspect was the advert change above --
+connectable LE advertising now runs during the window BR/EDR is being paged, which it never
+did before. Measured instead of assumed, with `tetherd` stopped so nothing else drove the
+radio:
+
+| Condition | Cold `Device1.Connect` |
+|---|---|
+| No advertising | 1s, 2s, 1s -- 3/3 |
+| ANCS solicitation on air | 1s, 1s, 1s -- 3/3 |
+
+The advert costs nothing. Paging works fine underneath it, and the gate change stands.
+
+What differs is which method is called. `connect_classic()` picks the per-bearer
+`Bearer.BREDR1.Connect` whenever `Device1.Connected` is already true, and treats a refusal
+from it as final. Before the advert change that branch was nearly unreachable at startup:
+with no advert, LE never came up first, so `Device1.Connected` stayed false and the untyped
+`Device1.Connect` -- the one that connects in a second -- did the work. Now LE comes up
+within seconds of the advert going on air, `Device1.Connected` flips to true, and every
+subsequent Classic attempt takes the per-bearer path, which answers `br-connection-unknown`
+under a live LE link.
+
+So the advert did not break paging; it changed which door the daemon knocks on. A refusal
+from the per-bearer Connect now falls through to `Device1.Connect` instead of ending the
+attempt. Only `InProgress` and `AlreadyConnected` still return early -- both mean a connect
+is already running, and racing a second one against it is the failure mode that produced
+the `InProgress` storms.
+
+`set_preferred_bearer("bredr")` sits on that fallback path, and reaching it under a live LE
+link would reintroduce the 2026-08-20 bug exactly. It is now skipped whenever LE is up. The
+property only steers the untyped Connect, and with LE up the phone is reachable without it.
+
+### 2026-08-22 - Confirmed: a clean start, and where the remaining minute goes
+
+First daemon start after the fallback above, phone on the desk:
+
+```
+[INFO] bluetooth: soliciting ANCS for 180s
+[INFO] bluetooth: pulled 7 contacts
+[INFO] ancs: the notification subscription is no longer live (BlueZ cleared Notifying), rebuilding it
+[INFO] ancs: StartNotify not ready yet (org.bluez.Error.InProgress: In Progress)
+[INFO] ancs: Subscribing to the iPhone's notifications...
+```
+
+Not one `br-connection-unknown` in the whole run, and PBAP pulled before any warning was
+logged at all -- BR/EDR was up almost immediately. The backoff climb that opened this
+investigation is gone.
+
+What is left takes about a minute, and it is entirely the LE half: `StartNotify` answering
+`InProgress` while BlueZ finishes GATT discovery on the freshly opened link. The daemon
+retries and it clears on its own.
+
+**This is not the hang recorded on 2026-08-19.** That one also answers `InProgress` on
+`StartNotify`, and the difference matters because the remedy there is a `bluetoothd`
+restart, which is worth nothing here:
+
+| | Transient (normal startup) | Hung (2026-08-19) |
+|---|---|---|
+| Duration | Seconds to about a minute, then subscribes | Indefinite |
+| LE link | Up -- the characteristics are there to discover | Never appears; every `Bearer.LE1.Connect` is accepted and nothing connects |
+| Remedy | None. Wait | `sudo systemctl restart bluetooth` |
+
+The link being up is the discriminator: `InProgress` under a live LE link is discovery
+still running, not a poisoned path.
diff --git a/src/core/include/tether/bluetooth/bearer_supervisor.hpp b/src/core/include/tether/bluetooth/bearer_supervisor.hpp
index d0f300f..fbc908e 100644
--- a/src/core/include/tether/bluetooth/bearer_supervisor.hpp
+++ b/src/core/include/tether/bluetooth/bearer_supervisor.hpp
@@ -9,6 +9,10 @@ namespace tether::bluetooth {
inline constexpr int BEARER_SETTLE_SECONDS = 3;
inline constexpr int BEARER_BACKOFF_MIN_SECONDS = 5;
inline constexpr int BEARER_BACKOFF_MAX_SECONDS = 300;
+
+ // Ceiling for the BR/EDR backoff while LE is connected.
+ inline constexpr int LE_UP_CLASSIC_BACKOFF_MAX_SECONDS = 30;
+
// How many refused attempts before the status stops saying "connecting"
inline constexpr int CLASSIC_FAILURES_BEFORE_ADVICE = 6;
diff --git a/src/core/src/bluetooth/bearer_supervisor.cpp b/src/core/src/bluetooth/bearer_supervisor.cpp
index 5b7bad8..8b8697d 100644
--- a/src/core/src/bluetooth/bearer_supervisor.cpp
+++ b/src/core/src/bluetooth/bearer_supervisor.cpp
@@ -100,6 +100,13 @@ namespace tether::bluetooth {
if (status_.le_connected)
status_.le_dialling = false;
+ // The phone opening the LE link proves it is in range and answering
+ if (status_.le_connected && !previous.le_connected) {
+ status_.classic_backoff = 0;
+ next_classic_attempt_ = 0;
+ classic_failures_ = 0;
+ }
+
if (status_.classic_connected) {
if (classic_connected_since_ < 0)
classic_connected_since_ = now;
@@ -113,6 +120,8 @@ namespace tether::bluetooth {
// mirroring off for a phone that is still delivering notifications.
classic_connected_since_ = -1;
+ const int ceiling = status_.le_connected ? LE_UP_CLASSIC_BACKOFF_MAX_SECONDS : BEARER_BACKOFF_MAX_SECONDS;
+
if (now >= next_classic_attempt_) {
std::string err;
switch (classify(ops_.connect_classic(err), err)) {
@@ -124,12 +133,12 @@ namespace tether::bluetooth {
case ConnectResult::Busy:
// Not a refusal and not an attempt. Standing back is the
// whole remedy.
- status_.classic_backoff = grow_backoff(status_.classic_backoff);
+ status_.classic_backoff = grow_backoff(status_.classic_backoff, ceiling);
next_classic_attempt_ = now + status_.classic_backoff;
break;
case ConnectResult::Failed:
++classic_failures_;
- status_.classic_backoff = next_backoff(status_.classic_backoff, err);
+ status_.classic_backoff = next_backoff(status_.classic_backoff, err, ceiling);
next_classic_attempt_ = now + status_.classic_backoff;
debug::log(
WARN, "bluetooth: BR/EDR connect failed ({}), retrying in {}s", err, status_.classic_backoff);
@@ -140,10 +149,12 @@ namespace tether::bluetooth {
// An iPhone that keeps refusing while unlocked, with its Bluetooth
// permissions already on, is wedged on its own side: nothing here
// clears it, and saying "connecting" forever hides that.
- status_.reason = classic_failures_ >= CLASSIC_FAILURES_BEFORE_ADVICE
+ status_.reason = classic_failures_ >= CLASSIC_FAILURES_BEFORE_ADVICE && !status_.le_connected
? "The iPhone keeps refusing the Bluetooth connection. Turn Bluetooth off and "
"back on on the iPhone — that clears it even when the permissions are already "
"on. Re-pairing is not the fix."
+ : status_.le_connected
+ ? "Notifications are connected. Still reaching the iPhone for messages and contacts..."
: "Connecting to the iPhone over Bluetooth...";
return !(status_ == previous);
}
diff --git a/src/core/src/bluetooth/connection.cpp b/src/core/src/bluetooth/connection.cpp
index a3374d5..9035cc2 100644
--- a/src/core/src/bluetooth/connection.cpp
+++ b/src/core/src/bluetooth/connection.cpp
@@ -228,6 +228,13 @@ namespace tether::bluetooth {
// profile supervisor short-circuits once map_open is set, so nothing else
// notices. Consecutive listing failures are the cheapest liveness signal.
constexpr int MAP_FAILURES_BEFORE_REOPEN = 3;
+
+ // The OBEX session object is gone, or its transport died under it.
+ auto map_session_dead = [](const std::string& err) {
+ return err.find("UnknownObject") != std::string::npos ||
+ err.find("Transport got disconnected") != std::string::npos ||
+ err.find("Transport is not connected") != std::string::npos;
+ };
constexpr int MESSAGE_LIST_MAX = 200;
// Bodies are fetched one OBEX Get at a time on the connection thread,
// which also has ANCS and the bearer supervisor. Needs cap to keep the
@@ -305,19 +312,25 @@ namespace tether::bluetooth {
return ConnectResult::Failed;
}
// bluez only exposes the per-bearer Connect while the device is connected on some bearer
+ std::string bearer_err;
if (device->has_classic_bearer && device->connected) {
- std::string bearer_err;
if (call(device->path, IFACE_BEARER_BREDR, "Connect", bearer_err))
return ConnectResult::Requested;
- // some versions publish the interface without the method
- if (bearer_err.find("UnknownMethod") == std::string::npos) {
+ if (bearer_err.find("InProgress") != std::string::npos ||
+ bearer_err.find("AlreadyConnected") != std::string::npos) {
err = bearer_err;
return ConnectResult::Failed;
}
}
- set_preferred_bearer("bredr");
- return call(device->path, IFACE_DEVICE, "Connect", err) ? ConnectResult::Requested
- : ConnectResult::Failed;
+
+ if (!device->le_link_up())
+ set_preferred_bearer("bredr");
+ if (call(device->path, IFACE_DEVICE, "Connect", err))
+ return ConnectResult::Requested;
+ // per-bearer refusal is the more specific one
+ if (!bearer_err.empty())
+ err = bearer_err;
+ return ConnectResult::Failed;
}
bool le_connect_outstanding() const override {
@@ -694,7 +707,7 @@ namespace tether::bluetooth {
// Some stacks only answer for the folder they are standing in. Walking
// into the inbox costs the sent folder but keeps messages working, so it
// is worth one attempt before declaring the session dead.
- if (!err.empty() && map_lists_subfolders) {
+ if (!err.empty() && map_lists_subfolders && !map_session_dead(err)) {
debug::log(
WARN, "bluetooth: listing '{}' failed ({}); falling back to the inbox alone", MAP_FOLDER_INBOX, err);
map_lists_subfolders = false;
@@ -712,7 +725,7 @@ namespace tether::bluetooth {
// ponytail: a fail count, not an obexd ObjectManager watcher. Costs up
// to MAP_FAILURES_BEFORE_REOPEN polls of latency; subscribe to
// org.bluez.obex InterfacesRemoved if that ever proves too slow.
- if (++map_failures >= MAP_FAILURES_BEFORE_REOPEN) {
+ if (map_session_dead(err) || ++map_failures >= MAP_FAILURES_BEFORE_REOPEN) {
debug::log(WARN, "bluetooth: MAP session is not answering; reopening it");
map_failures = 0;
profiles->drop_map();
@@ -731,9 +744,12 @@ namespace tether::bluetooth {
std::string sent_err;
auto sent = session->list_messages(MAP_FOLDER_SENT, MESSAGE_LIST_MAX, sent_err);
if (!sent_err.empty()) {
- debug::log(
- WARN, "bluetooth: the sent folder is unavailable ({}); showing received messages only", sent_err);
- map_lists_sent = false;
+ if (!map_session_dead(sent_err)) {
+ debug::log(WARN,
+ "bluetooth: the sent folder is unavailable ({}); showing received messages only",
+ sent_err);
+ map_lists_sent = false;
+ }
} else {
// An empty sent folder is just a folder with nothing new in it.
// Only an error means the phone will not serve it.
@@ -945,9 +961,9 @@ namespace tether::bluetooth {
profiles->tick(now, link_ready);
const auto& bearer = bearers->status();
- supervise_ancs_solicitation(*monitor,
- ancs_enabled && bearer.classic_connected && bearer.le_available &&
- !bearer.le_connected && !bearer.le_dialling);
+
+ supervise_ancs_solicitation(
+ *monitor, ancs_enabled && bearer.le_available && !bearer.le_connected && !bearer.le_dialling);
// publish() drops a payload identical to the last one, so refreshing
// every tick costs nothing and cannot miss a transition.
diff --git a/test/test_bluetooth_supervisor.cpp b/test/test_bluetooth_supervisor.cpp
index 6b9da17..016327b 100644
--- a/test/test_bluetooth_supervisor.cpp
+++ b/test/test_bluetooth_supervisor.cpp
@@ -665,3 +665,87 @@ TEST(BearerSupervisor, RepeatedRefusalNamesTheRemedy) {
sup.tick(++now);
EXPECT_TRUE(sup.status().classic_connected);
}
+
+// Walking back into range must not be held behind the backoff the absence grew.
+TEST(BearerSupervisor, LeComingUpClearsTheClassicBackoff) {
+ FakeBearer ops;
+ BearerSupervisor sup(ops, true);
+
+ ops.classic_succeeds = false;
+ ops.classic_error = "br-connection-unknown";
+
+ // Out of range: BR/EDR fails until the backoff reaches its ceiling.
+ int64_t now = 0;
+ while (now < 1200) {
+ sup.tick(now);
+ now += BEARER_POLL_SECONDS;
+ }
+ ASSERT_EQ(sup.status().classic_backoff, BEARER_BACKOFF_MAX_SECONDS)
+ << "expected the absence to grow the backoff to its ceiling";
+ const int attempts_while_away = ops.classic_attempts;
+
+ // Back in range: the phone sees the solicitation and opens LE inbound.
+ ops.le = true;
+ ops.classic_succeeds = true;
+ sup.tick(now);
+
+ EXPECT_EQ(ops.classic_attempts, attempts_while_away + 1)
+ << "LE came up and BR/EDR still sat out the backoff grown while the phone was away";
+ EXPECT_EQ(sup.status().classic_backoff, 0);
+}
+
+// The "phone keeps refusing" advice must not survive a phone that was merely away.
+TEST(BearerSupervisor, LeComingUpClearsTheRefusalAdvice) {
+ FakeBearer ops;
+ BearerSupervisor sup(ops, true);
+
+ ops.classic_succeeds = false;
+ ops.classic_error = "br-connection-unknown";
+
+ int64_t now = 0;
+ for (int i = 0; i < 40; ++i) {
+ sup.tick(now);
+ now += BEARER_POLL_SECONDS;
+ }
+ ASSERT_NE(sup.status().reason.find("keeps refusing"), std::string::npos);
+
+ ops.le = true;
+ sup.tick(now);
+ EXPECT_EQ(sup.status().reason.find("keeps refusing"), std::string::npos)
+ << "blamed the phone for refusing after it had only been out of range";
+}
+
+// A live LE link is standing proof the phone is present, not a one-off event.
+TEST(BearerSupervisor, ClassicBackoffStaysShortWhileLeIsUp) {
+ FakeBearer ops;
+ BearerSupervisor sup(ops, true);
+
+ ops.classic_succeeds = false;
+ ops.classic_error = "br-connection-unknown";
+ ops.le = true; // phone answered the solicitation; BR/EDR still will not page
+
+ int64_t now = 0;
+ while (now < 1200) {
+ sup.tick(now);
+ now += BEARER_POLL_SECONDS;
+ EXPECT_LE(sup.status().classic_backoff, LE_UP_CLASSIC_BACKOFF_MAX_SECONDS)
+ << "backed off for minutes against a phone that was answering on LE";
+ }
+}
+
+// Telling the user to cycle Bluetooth would drop the LE link carrying notifications.
+TEST(BearerSupervisor, DoesNotBlameThePhoneWhileItAnswersOnLe) {
+ FakeBearer ops;
+ BearerSupervisor sup(ops, true);
+
+ ops.classic_succeeds = false;
+ ops.le = true;
+
+ int64_t now = 0;
+ while (now < 1200) {
+ sup.tick(now);
+ now += BEARER_POLL_SECONDS;
+ }
+ EXPECT_EQ(sup.status().reason.find("keeps refusing"), std::string::npos)
+ << "told the user to cycle Bluetooth while notifications were mirroring over LE";
+}