Skip to content

Linux + iPhone Continuity / iMessage / SMS

fix(package): easiest yet uninvasive --experimental install

Zack Bartel2a6c01774b8b
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 38f704f..85fc565 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -127,8 +127,23 @@ install(FILES "${CMAKE_CURRENT_BINARY_DIR}/man/tether.1" "${CMAKE_CURRENT_BINARY
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/man/tetherd.8"
DESTINATION ${CMAKE_INSTALL_MANDIR}/man8)
-# Bluetooth CoD unit. Installed but not enabled: it changes how the machine presents itself over Bluetooth, so turning it on is the user's call.
-# Not CMAKE_INSTALL_LIBDIR: that is multiarch on Debian, where units still live in /usr/lib/systemd.
+# bluetoothd's path is distro-specific and the drop-in has to name it. Detected
+# for this machine; packagers cross-building for another layout override it.
+if(NOT DEFINED BLUETOOTHD_PATH)
+ if(EXISTS "/usr/libexec/bluetooth/bluetoothd")
+ set(BLUETOOTHD_PATH "/usr/libexec/bluetooth/bluetoothd")
+ else()
+ set(BLUETOOTHD_PATH "/usr/lib/bluetooth/bluetoothd")
+ endif()
+endif()
+set(BLUETOOTHD_PATH "${BLUETOOTHD_PATH}" CACHE FILEPATH "Path to the bluetoothd binary named by the drop-in")
+
+configure_file(packaging/systemd/bluetooth-experimental.conf.in
+ "${CMAKE_CURRENT_BINARY_DIR}/bluetooth-experimental.conf" @ONLY)
+
+# shipped for the user to copy, not ours to decide!
+install(FILES "${CMAKE_CURRENT_BINARY_DIR}/bluetooth-experimental.conf"
+ DESTINATION "${CMAKE_INSTALL_DATADIR}/tether")
set(SYSTEMD_UNIT_DIR "lib/systemd/system" CACHE PATH "systemd system unit directory")
install(FILES packaging/systemd/[email protected]
DESTINATION "${SYSTEMD_UNIT_DIR}")
diff --git a/README.md b/README.md
index d83165b..30eaf4a 100644
--- a/README.md
+++ b/README.md
@@ -90,7 +90,9 @@ The extension communicates with `tetherd` via native messaging. This allows user
- `bluez`, `bluez-utils`, and `bluez-obex` (for messages and notifications)
#### Bluetooth (for Messages and Notifications)
-- BlueZ 5.86+ must be running with experimental bearer API.
+- BlueZ 5.86+ must be running with experimental bearer API. Tether ships the
+ systemd drop-in; `tether --bt-setup` prints the one command that applies it.
+ Do this **before** pairing.
- A controller with BR/EDR, LE, and advertising support.
- Notification mirroring does not work on iOS 18 and earlier.
diff --git a/docs/BLUETOOTH.md b/docs/BLUETOOTH.md
index b6a3756..0a355e3 100644
--- a/docs/BLUETOOTH.md
+++ b/docs/BLUETOOTH.md
@@ -53,16 +53,25 @@ sudo systemctl enable --now tether-btclass@hci0
`PartOf=bluetooth.service` re-runs it on every `bluetooth.service` restart. It writes the
class, reads it back, and retries for ten seconds.
-**BlueZ needs the experimental bearer API** for ANCS. On Arch:
+**BlueZ needs the experimental bearer API** for ANCS, and it must be active
+*before* pairing: a bond made without it has no LE half. The package ships the
+drop-in, already pointing at this distro's `bluetoothd`:
```bash
sudo mkdir -p /etc/systemd/system/bluetooth.service.d
-printf '[Service]\nExecStart=\nExecStart=/usr/lib/bluetooth/bluetoothd --experimental\n' \
- | sudo tee /etc/systemd/system/bluetooth.service.d/experimental.conf
+sudo cp /usr/share/tether/bluetooth-experimental.conf /etc/systemd/system/bluetooth.service.d/
sudo systemctl daemon-reload && sudo systemctl restart bluetooth
```
-The executable lives at `/usr/libexec/bluetooth/bluetoothd` on Debian based.
+It is shipped to `/usr/share` rather than installed into
+`bluetooth.service.d` directly, because a drop-in there takes effect the moment
+the package lands, and changing how `bluetoothd` runs for the whole machine is
+the user's decision.
+
+Without it `bluetoothd` still registers `org.bluez.Bearer.LE1`, but as an empty
+marker: no properties, no `Connect()`. So the interface being present is not
+evidence the API is available, and code that reads it that way sees an LE bearer
+that can never connect and a bond that never looks dual.
**`obexd` must be running** (user service `obex`) for MAP and PBAP. It is socket-activated under normal use.
diff --git a/docs/man/man1/tether.1.in b/docs/man/man1/tether.1.in
index 8ae9c64..42432e3 100644
--- a/docs/man/man1/tether.1.in
+++ b/docs/man/man1/tether.1.in
@@ -121,6 +121,12 @@ tether \-\-bt-setup
Sets the Bluetooth adapter's Class of Device to A/V Hands\-Free, which iOS
requires before it will offer its Messages and Contacts permissions. Installed
but not enabled; see \fB\-\-bt-setup\fR.
+.TP
+\fB/usr/share/tether/bluetooth\-experimental.conf\fR
+systemd drop\-in that runs \fBbluetoothd\fR with \fB\-\-experimental\fR, which
+exposes the LE bearer interface ANCS notification mirroring needs. Copy it into
+\fB/etc/systemd/system/bluetooth.service.d/\fR to apply it; see
+\fB\-\-bt-setup\fR. It must be in place before pairing.
.SH SEE ALSO
.BR tetherd (8),
.BR tether-gtk (1)
diff --git a/packaging/systemd/bluetooth-experimental.conf.in b/packaging/systemd/bluetooth-experimental.conf.in
new file mode 100644
index 0000000..3825281
--- /dev/null
+++ b/packaging/systemd/bluetooth-experimental.conf.in
@@ -0,0 +1,12 @@
+# Exposes BlueZ's per-transport Bearer.LE1 interface, which carries the LE half
+# of the iPhone bond that ANCS notification mirroring runs over.
+#
+# Not installed into bluetooth.service.d by the package: it changes how
+# bluetoothd runs for everything on this machine, so putting it there is your
+# call. `tether --bt-setup` prints the command.
+#
+# ExecStart must name the bluetoothd binary, and its path differs by distro.
+# Configured here for this build; override with -DBLUETOOTHD_PATH=... .
+[Service]
+ExecStart=
+ExecStart=@BLUETOOTHD_PATH@ --experimental
diff --git a/packaging/tether.install b/packaging/tether.install
index b88d714..034c5d6 100644
--- a/packaging/tether.install
+++ b/packaging/tether.install
@@ -6,6 +6,10 @@ Bluetooth (iPhone messages and notifications) needs one-time system setup.
[email protected] is installed but NOT enabled. Enabling it changes how
this machine presents itself over Bluetooth, so that is your call to make.
+Notification mirroring also needs a bluetooth.service drop-in, shipped at
+/usr/share/tether/bluetooth-experimental.conf and likewise not applied for you.
+Apply it BEFORE pairing an iPhone: a bond made without it has no LE half.
+
To see exactly what is left, and the commands to run:
tether --bt-setup
diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt
index d137478..e276734 100644
--- a/src/core/CMakeLists.txt
+++ b/src/core/CMakeLists.txt
@@ -44,6 +44,11 @@ target_include_directories(tether PUBLIC
${CMAKE_BINARY_DIR}/generated
)
+# Where the bluetooth.service drop-in is shipped, so --bt-setup can name it.
+target_compile_definitions(tether PRIVATE
+ TETHER_DATADIR="${CMAKE_INSTALL_FULL_DATADIR}/tether"
+)
+
target_link_libraries(tether PUBLIC
nlohmann_json::nlohmann_json
diff --git a/src/core/src/bluetooth/objects.cpp b/src/core/src/bluetooth/objects.cpp
index eb1cf56..5e4548d 100644
--- a/src/core/src/bluetooth/objects.cpp
+++ b/src/core/src/bluetooth/objects.cpp
@@ -149,7 +149,8 @@ namespace tether::bluetooth {
g_variant_unref(props);
if (GVariant* le = g_variant_lookup_value(ifaces, IFACE_BEARER_LE, G_VARIANT_TYPE("a{sv}"))) {
- d.has_le_bearer = true;
+ // without --experimental bluetoothd still registers the interface name, but empty.
+ d.has_le_bearer = g_variant_n_children(le) > 0;
d.le_paired = get_bool(le, "Paired");
d.le_bonded = get_bool(le, "Bonded", d.le_paired);
d.le_connected = get_bool(le, "Connected");
@@ -262,6 +263,25 @@ namespace tether::bluetooth {
return "/usr/lib/bluetooth/bluetoothd";
}
+ // The package ships the drop-in for the user to copy.
+ std::string enable_experimental_command() {
+ const std::string shipped = std::string(TETHER_DATADIR) + "/bluetooth-experimental.conf";
+ std::error_code ec;
+ if (std::filesystem::exists(shipped, ec))
+ return "sudo mkdir -p /etc/systemd/system/bluetooth.service.d\n"
+ "sudo cp " +
+ shipped +
+ " /etc/systemd/system/bluetooth.service.d/\n"
+ "sudo systemctl daemon-reload && sudo systemctl restart bluetooth";
+
+ return "sudo mkdir -p /etc/systemd/system/bluetooth.service.d\n"
+ "printf '[Service]\\nExecStart=\\nExecStart=" +
+ bluetoothd_path() +
+ " --experimental\\n' \\\n"
+ " | sudo tee /etc/systemd/system/bluetooth.service.d/experimental.conf\n"
+ "sudo systemctl daemon-reload && sudo systemctl restart bluetooth";
+ }
+
} // namespace
Capability resolve_capability(const BluezObjects& objects) {
@@ -292,8 +312,10 @@ namespace tether::bluetooth {
cap.advertising = adapter->has_advertising_manager && adapter->advertising_instances > 0;
cap.class_ok = adapter->class_is_handsfree();
+ // Only a populated Bearer.LE1 settles this. Bearer.BREDR1 is marker-only on
+ // some packaged builds, so it is not evidence either way.
for (const auto& d : objects.devices) {
- if (d.has_le_bearer || d.has_classic_bearer)
+ if (d.has_le_bearer)
cap.bearer_api = BearerApi::Confirmed;
}
if (cap.bearer_api != BearerApi::Confirmed)
@@ -324,13 +346,9 @@ namespace tether::bluetooth {
}
if (cap.bearer_api == BearerApi::Absent) {
cap.setup.push_back({"Notification mirroring needs BlueZ's experimental bearer API "
- "(org.bluez.Bearer.LE1), which bluetoothd is not exposing.",
- "sudo mkdir -p /etc/systemd/system/bluetooth.service.d\n"
- "printf '[Service]\\nExecStart=\\nExecStart=" +
- bluetoothd_path() +
- " --experimental\\n' \\\n"
- " | sudo tee /etc/systemd/system/bluetooth.service.d/experimental.conf\n"
- "sudo systemctl daemon-reload && sudo systemctl restart bluetooth"});
+ "(org.bluez.Bearer.LE1), which bluetoothd is not exposing. Set this up before "
+ "pairing: a bond made without it has no LE half.",
+ enable_experimental_command()});
cap.mode = DeliveryMode::Compatibility;
} else if (cap.bearer_api == BearerApi::Unknown) {
cap.reasons.emplace_back("Bearer API support is unconfirmed until a device is bonded.");
diff --git a/test/test_bluetooth_objects.cpp b/test/test_bluetooth_objects.cpp
index c078353..b0a14ab 100644
--- a/test/test_bluetooth_objects.cpp
+++ b/test/test_bluetooth_objects.cpp
@@ -206,16 +206,16 @@ TEST(Capability, CompatibilityWhenExperimentalIsOff) {
EXPECT_NE(cap.setup[0].command.find("--experimental"), std::string::npos);
}
-// BlueZ stopped gating the Bearer API on --experimental, so bluetoothd's command
-// line is not evidence against it. Reading it as proof told users whose
-// notification mirroring already worked to install a drop-in that changes nothing.
-// A bearer object is the observation that settles it, and BREDR1 answers the
-// question without an LE phone in range.
-TEST(Capability, AClassicBearerConfirmsTheApiWithoutTheExperimentalFlag) {
+// Without --experimental bluetoothd registers Bearer.LE1 as an empty marker: no
+// properties, no Connect(). Reading its mere presence as proof reported a usable
+// LE bearer, suppressed the drop-in advice, and left le_bonded permanently false
+// -- which in turn latched notification mirroring off after every pairing.
+TEST(Capability, AnEmptyBearerInterfaceIsNotProofOfTheApi) {
Payload p(join(ADAPTER_FULL, R"({
- '/org/bluez/hci0/dev_F8_D3_F0_3C_84_4A': {
+ '/org/bluez/hci0/dev_60_57_C8_30_6A_F7': {
'org.bluez.Device1': { 'Paired': <true>, 'Bonded': <true> },
- 'org.bluez.Bearer.BREDR1': { 'Bonded': <true>, 'Connected': <false> }
+ 'org.bluez.Bearer.LE1': {},
+ 'org.bluez.Bearer.BREDR1': {}
}
})")
.c_str());
@@ -223,14 +223,13 @@ TEST(Capability, AClassicBearerConfirmsTheApiWithoutTheExperimentalFlag) {
objects.experimental_api = false;
auto cap = resolve_capability(objects);
- EXPECT_EQ(cap.bearer_api, BearerApi::Confirmed);
- EXPECT_EQ(cap.mode, DeliveryMode::Full);
- EXPECT_TRUE(cap.setup.empty());
+ ASSERT_FALSE(objects.devices.empty());
+ EXPECT_FALSE(objects.devices[0].has_le_bearer);
+ EXPECT_EQ(cap.bearer_api, BearerApi::Absent);
+ ASSERT_EQ(cap.setup.size(), 1u);
+ EXPECT_NE(cap.setup[0].command.find("--experimental"), std::string::npos);
}
-// Headsets and game controllers are bonded but never expose a bearer under any
-// build, so treating any bond as proof of absence gives a false negative and
-// silently disables ANCS on a machine that supports it.
TEST(Capability, ClassicOnlyBondDoesNotDisproveBearerApi) {
Payload p(join(ADAPTER_FULL, R"({
'/org/bluez/hci0/dev_F8_D3_F0_3C_84_4A': {