Skip to content

Linux + iPhone Continuity / iMessage / SMS

fix: single adapter machines can have a different dev index

Zack Bartel2fd85ba46ad6
diff --git a/docs/BLUETOOTH.md b/docs/BLUETOOTH.md
index fdcfb30..d6bac0d 100644
--- a/docs/BLUETOOTH.md
+++ b/docs/BLUETOOTH.md
@@ -856,6 +856,7 @@ checks the daemon does not make.
|---|---|---|
| `systemctl enable --now tether-btclass@hci0` hangs in `activating (start)` forever | `btmgmt` epolls its stdin before running the command, and epoll rejects the `/dev/null` systemd hands it, so it waits having done nothing | Update the unit -- it pipes into `btmgmt` now. On an older build, `sudo btmgmt class 4 8` by hand sets the class until `bluetoothd` restarts, see 2026-09-01 below |
| `systemctl enable --now tether-btclass@hci0` says `Unit [email protected] does not exist` | A portable build (AppImage, Flatpak) installed no unit -- only the distro packages do | `tether --bt-setup` and run the command it prints, which writes the unit first, see 2026-09-05 below |
+| `tether-btclass@hci0` fails with `Invalid Index`, having worked for months | The controller re-enumerated -- a failed firmware handshake resets it over USB and it comes back as `hci1` -- so the instance name points at an adapter that no longer exists | Update the unit -- it resolves the adapter itself now and the instance name is only a hint, see 2026-09-11 below. By hand, `ls /sys/class/bluetooth` names the live adapter |
| Messages and contacts worked, then stopped, and the error mentions a service record | `bluetoothd` restarted and reset the Class of Device | `sudo systemctl enable --now tether-btclass@hci0`, then re-pair if the phone dropped the bond |
| The phone never offers notifications / Sync Contacts | The class is wrong, or the ANCS advertisement is not running | Check for `class=ok` in `tether --bt-status`, can take minutes |
| MAP or PBAP reports `forbidden` | The matching toggle on the phone is off | Turn it on. This is not a pairing failure |
@@ -3232,3 +3233,35 @@ Not yet verified on hardware: the full sequence on Pro 3, iPhone media rather th
the owner bit on Pro 2, and whether an `off` profile persists if tetherd dies while the buds
are away. WirePlumber restores a saved `off` profile unless `session.dont-restore-off-profile`
is set.
+
+### 2026-09-11 - The Class of Device unit was pinned to an index the adapter had left
+
+`tether-btclass@hci0` started failing with `Invalid Index` on a machine where it had worked
+for months. Nothing in Tether had changed. The kernel log has the whole story:
+
+```
+Bluetooth: hci0: Execution of wmt command timed out
+Bluetooth: hci0: Failed to send wmt func ctrl (-110)
+usb 3-5: reset high-speed USB device number 4 using xhci_hcd
+Bluetooth: hci1: Device setup in 1693823 usecs
+```
+
+The MediaTek controller's firmware handshake timed out, the USB device was reset, and the
+controller came back under the next free index. `hci0` was gone; `/sys/class/bluetooth` held
+only `hci1`. A unit instantiated on the index cannot survive that, and the failure reads like
+a missing adapter rather than a renamed one.
+
+The instance name is now a hint rather than the target. Each attempt uses `%i` if
+`/sys/class/bluetooth/%i` exists and otherwise takes the first adapter present, so an already
+enabled `tether-btclass@hci0` keeps working under any index and every documented command
+stays as written. Resolving inside the loop rather than once also covers a re-enumeration
+that lands mid-loop. The retry window went from 10s to 30s: the reset above put the new
+adapter on the bus 13s after boot, which the old window missed even with a correct name.
+
+`$$` in `ExecStart` is a literal `$` -- systemd expands `$a` as one of its own variables and
+would hand the shell an empty string.
+
+Not covered: a controller that re-enumerates at runtime with no `bluetoothd` restart. Nothing
+re-runs the unit there, and `bluetoothd` applies its own default class to the new adapter, so
+the class is wrong until `bluetooth.service` restarts. A udev rule tagging adapter `add` with
+`SYSTEMD_WANTS` would close that, and would also remove the manual enable step.
diff --git a/nix/module.nix b/nix/module.nix
index c99d27a..68d2792 100644
--- a/nix/module.nix
+++ b/nix/module.nix
@@ -17,12 +17,19 @@ let
Type = "oneshot";
RemainAfterExit = true;
# btmgmt epolls its stdin before it runs the command,
+ # ${adapter} is a hint: a controller that re-enumerates comes back under
+ # the next free index, so resolve the adapter on every attempt.
ExecStart = pkgs.writeShellScript "tether-btclass-${adapter}" ''
- for attempt in 1 2 3 4 5 6 7 8 9 10; do
- echo | ${pkgs.bluez}/bin/btmgmt --index ${adapter} class 4 8 >/dev/null 2>&1
- if echo | ${pkgs.bluez}/bin/btmgmt --index ${adapter} info 2>/dev/null \
- | ${pkgs.gnugrep}/bin/grep -q "class 0x..0408"; then
- exit 0
+ for attempt in $(${pkgs.coreutils}/bin/seq 30); do
+ hci=${adapter}
+ [ -e /sys/class/bluetooth/$hci ] \
+ || hci=$(${pkgs.coreutils}/bin/ls /sys/class/bluetooth 2>/dev/null | ${pkgs.coreutils}/bin/head -n1)
+ if [ -n "$hci" ]; then
+ echo | ${pkgs.bluez}/bin/btmgmt --index $hci class 4 8 >/dev/null 2>&1
+ if echo | ${pkgs.bluez}/bin/btmgmt --index $hci info 2>/dev/null \
+ | ${pkgs.gnugrep}/bin/grep -q "class 0x..0408"; then
+ exit 0
+ fi
fi
${pkgs.coreutils}/bin/sleep 1
done
diff --git a/packaging/systemd/[email protected] b/packaging/systemd/[email protected]
index 96a8e99..c7f2f2d 100644
--- a/packaging/systemd/[email protected]
+++ b/packaging/systemd/[email protected]
@@ -3,8 +3,9 @@
# bluetoothd resets the class to its own default every time it
# starts, and when it does, MAP and PBAP stop working with an OBEX error.
#
-# %i is the adapter, e.g. [email protected].
-Description=Set Bluetooth Class of Device to A/V Hands-Free on %i for Tether
+# %i is a hint, not a requirement. Contollers can fail handshake and comes back
+# under the next free index, so the instance name is wrong while the machine still has exactly one adapter.
+Description=Set Bluetooth Class of Device to A/V Hands-Free for Tether
Documentation=https://github.com/zackb/tether/blob/main/docs/BLUETOOTH.md
After=bluetooth.service
PartOf=bluetooth.service
@@ -13,9 +14,13 @@ PartOf=bluetooth.service
Type=oneshot
RemainAfterExit=yes
# btmgmt epolls its stdin before it runs the command, rejects /dev/null with EPERM.
-ExecStart=/bin/sh -c 'for i in 1 2 3 4 5 6 7 8 9 10; do \
- echo | btmgmt --index %i class 4 8 >/dev/null 2>&1; \
- echo | btmgmt --index %i info 2>/dev/null | grep -q "class 0x..0408" && exit 0; \
+ExecStart=/bin/sh -c 'for t in $$(seq 30); do \
+ a=%i; \
+ [ -e /sys/class/bluetooth/$$a ] || a=$$(ls /sys/class/bluetooth 2>/dev/null | head -n1); \
+ if [ -n "$$a" ]; then \
+ echo | btmgmt --index $$a class 4 8 >/dev/null 2>&1; \
+ echo | btmgmt --index $$a info 2>/dev/null | grep -q "class 0x..0408" && exit 0; \
+ fi; \
sleep 1; \
done; exit 1'
TimeoutStartSec=60