From c9e5f2758f38850d56d3384c581bc6e83255e186 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 18:09:56 -0400 Subject: [PATCH 01/21] build: move to btleplug 0.13.5, the first release with the fixes for both library defects aranet works around aranet works around two defects of btleplug 0.11.8. On macOS its CoreBluetooth thread never drained an autorelease pool, so memory grew while scanning (btleplug's issue 494). On Linux a connect failed with "Service discovery timed out" when BlueZ needed more than 5 s to resolve a sensor's services (btleplug's issue 496). By its changelog, btleplug 0.13.5 fixes both: it drains a pool for every message, and through bluez-async 0.9.0 it waits 30 s. Neither effect has been measured here yet. This commit moves the dependency and changes nothing else. Both workarounds stay as they are. The BlueZ test double still waits 5 s; the double, the tests, the comments and the changelog follow in later commits of this pull request. The requirement is `"0.13.5"`, a floor and not a pin: it accepts 0.13.6. `"0.13"` would let a project that already has 0.13.1 to 0.13.4 in its lock file build aranet-core against a release with neither fix. 0.13.0 is yanked. `Cargo.lock` comes from `cargo update -p btleplug --precise 0.13.5`. btleplug, bluez-async (0.8.2 to 0.9.0) and objc2-core-bluetooth (0.2.2 to 0.3.2) move. itertools 0.15.0, which bluez-async 0.9.0 uses on Linux, is added, and so are eight `windows` crates, which only btleplug's Windows backend uses. cesu8, dashmap 5.5.3, jni 0.19.0 and jni-utils go. No other package moves, `cargo update --workspace` changes nothing more, and the lock goes from 763 to 768 packages. `ValueNotification` has a new field, `service_uuid`. The one literal in the tree is in the test double `link/fake.rs`, which now names the service that its characteristics already use. With the new lock and without that line, the test build of aranet-core stops at E0063; no other code needs a change. Checked on macOS arm64: rustfmt 1.90; clippy with `-D warnings` on Rust 1.99, with and without `--all-features`, and on 1.90; `cargo test --locked --workspace` (1,591 passed, 83 ignored); aranet-core's own tests, which give 423 passed and 59 ignored before and after the change; each feature of aranet-core with cargo-hack; the docs build with `-D warnings`; and `cargo audit`. In a Linux arm64 container with Rust 1.90: clippy with `--all-features` and aranet-core's tests (431 passed, 60 ignored). Nothing Windows-specific has been compiled yet: this pull request's Windows jobs are the first to do that. --- Cargo.lock | 190 +++++++++++++++++----------- Cargo.toml | 4 +- crates/aranet-core/src/link/fake.rs | 1 + 3 files changed, 120 insertions(+), 75 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index d1ba71f..924dfca 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -151,7 +151,7 @@ dependencies = [ "android-properties", "bitflags 2.13.2", "cc", - "jni 0.22.4", + "jni", "libc", "log", "ndk", @@ -849,16 +849,16 @@ dependencies = [ [[package]] name = "bluez-async" -version = "0.8.2" +version = "0.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "84ae4213cc2a8dc663acecac67bbdad05142be4d8ef372b6903abf878b0c690a" +checksum = "23a32d8f6aedb42c4ec4ed4e39720ee0e807e72c93feb7cd6483f51d08ca1f65" dependencies = [ "bitflags 2.13.2", "bluez-generated", "dbus", "dbus-tokio", "futures", - "itertools", + "itertools 0.15.0", "log", "serde", "serde-xml-rs", @@ -878,30 +878,29 @@ dependencies = [ [[package]] name = "btleplug" -version = "0.11.8" +version = "0.13.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c9a11621cb2c8c024e444734292482b1ad86fb50ded066cf46252e46643c8748" +checksum = "3d836502de731602ea87cbb307065e8feaed4fd10f0855a75b0b87944ee011dc" dependencies = [ "async-trait", "bitflags 2.13.2", "bluez-async", - "dashmap 6.2.1", + "dashmap", "dbus", "futures", - "jni 0.19.0", - "jni-utils", + "jni", "log", - "objc2 0.5.2", + "objc2 0.6.4", "objc2-core-bluetooth", - "objc2-foundation 0.2.2", + "objc2-foundation 0.3.2", "once_cell", "static_assertions", "thiserror 2.0.21", "tokio", "tokio-stream", "uuid", - "windows 0.61.3", - "windows-future", + "windows 0.62.2", + "windows-future 0.3.2", ] [[package]] @@ -1051,12 +1050,6 @@ dependencies = [ "shlex", ] -[[package]] -name = "cesu8" -version = "1.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c" - [[package]] name = "cfg-expr" version = "0.15.8" @@ -1466,19 +1459,6 @@ dependencies = [ "syn 3.0.6", ] -[[package]] -name = "dashmap" -version = "5.5.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "978747c1d849a7d2ee5e8adc0159961c48fb7e5db2f06af6723b80123bb53856" -dependencies = [ - "cfg-if", - "hashbrown 0.14.5", - "lock_api", - "once_cell", - "parking_lot_core", -] - [[package]] name = "dashmap" version = "6.2.1" @@ -2559,7 +2539,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9efcab3c1958580ff1f25a2a41be1668f7603d849bb63af523b208a3cc1223b8" dependencies = [ "cfg-if", - "dashmap 6.2.1", + "dashmap", "futures-sink", "futures-timer", "futures-util", @@ -3110,24 +3090,19 @@ dependencies = [ ] [[package]] -name = "itoa" -version = "1.0.18" +name = "itertools" +version = "0.15.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +checksum = "8b4baf93f58d4425749ca49a51c50ebab072c5df6994d08fed93541c331481dc" +dependencies = [ + "either", +] [[package]] -name = "jni" -version = "0.19.0" +name = "itoa" +version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c6df18c2e3db7e453d3c6ac5b3e9d5182664d28788126d39b91f2d1e22b017ec" -dependencies = [ - "cesu8", - "combine", - "jni-sys 0.3.1", - "log", - "thiserror 1.0.69", - "walkdir", -] +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" [[package]] name = "jni" @@ -3187,21 +3162,6 @@ dependencies = [ "syn 2.0.119", ] -[[package]] -name = "jni-utils" -version = "0.1.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "259e9f2c3ead61de911f147000660511f07ab00adeed1d84f5ac4d0386e7a6c4" -dependencies = [ - "dashmap 5.5.3", - "futures", - "jni 0.19.0", - "log", - "once_cell", - "static_assertions", - "uuid", -] - [[package]] name = "jobserver" version = "0.1.35" @@ -3909,13 +3869,13 @@ dependencies = [ [[package]] name = "objc2-core-bluetooth" -version = "0.2.2" +version = "0.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5a644b62ffb826a5277f536cf0f701493de420b13d40e700c452c36567771111" +checksum = "79b30b9eacc37434a61377866f68b27acef9fa5496f25cc9ca8b2549032e0394" dependencies = [ "bitflags 2.13.2", - "objc2 0.5.2", - "objc2-foundation 0.2.2", + "objc2 0.6.4", + "objc2-foundation 0.3.2", ] [[package]] @@ -4939,7 +4899,7 @@ dependencies = [ "compact_str", "critical-section", "hashbrown 0.17.1", - "itertools", + "itertools 0.14.0", "kasuari", "lru", "palette", @@ -5004,7 +4964,7 @@ dependencies = [ "hashbrown 0.17.1", "indoc", "instability", - "itertools", + "itertools 0.14.0", "line-clipping", "ratatui-core", "serde", @@ -6566,7 +6526,7 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5" dependencies = [ - "itertools", + "itertools 0.14.0", "unicode-segmentation", "unicode-width", ] @@ -6929,7 +6889,7 @@ version = "1.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "62c35be770821a214dbc362fc26908c853e776c0004294d0b10b8a6bad582f94" dependencies = [ - "jni 0.22.4", + "jni", "log", "ndk-context", "objc2 0.6.4", @@ -7236,11 +7196,23 @@ version = "0.61.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893" dependencies = [ - "windows-collections", + "windows-collections 0.2.0", "windows-core 0.61.2", - "windows-future", + "windows-future 0.2.1", "windows-link 0.1.3", - "windows-numerics", + "windows-numerics 0.2.0", +] + +[[package]] +name = "windows" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580" +dependencies = [ + "windows-collections 0.3.2", + "windows-core 0.62.2", + "windows-future 0.3.2", + "windows-numerics 0.3.1", ] [[package]] @@ -7252,6 +7224,15 @@ dependencies = [ "windows-core 0.61.2", ] +[[package]] +name = "windows-collections" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610" +dependencies = [ + "windows-core 0.62.2", +] + [[package]] name = "windows-core" version = "0.58.0" @@ -7278,6 +7259,19 @@ dependencies = [ "windows-strings 0.4.2", ] +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement 0.60.2", + "windows-interface 0.59.3", + "windows-link 0.2.1", + "windows-result 0.4.1", + "windows-strings 0.5.1", +] + [[package]] name = "windows-future" version = "0.2.1" @@ -7286,7 +7280,18 @@ checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e" dependencies = [ "windows-core 0.61.2", "windows-link 0.1.3", - "windows-threading", + "windows-threading 0.1.0", +] + +[[package]] +name = "windows-future" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb" +dependencies = [ + "windows-core 0.62.2", + "windows-link 0.2.1", + "windows-threading 0.2.1", ] [[package]] @@ -7355,6 +7360,16 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-numerics" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26" +dependencies = [ + "windows-core 0.62.2", + "windows-link 0.2.1", +] + [[package]] name = "windows-result" version = "0.2.0" @@ -7373,6 +7388,15 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link 0.2.1", +] + [[package]] name = "windows-strings" version = "0.1.0" @@ -7392,6 +7416,15 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link 0.2.1", +] + [[package]] name = "windows-sys" version = "0.48.0" @@ -7494,6 +7527,15 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-threading" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37" +dependencies = [ + "windows-link 0.2.1", +] + [[package]] name = "windows-version" version = "0.1.7" diff --git a/Cargo.toml b/Cargo.toml index b41c356..94a8dbe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,7 +31,9 @@ aranet-service = { version = "0.2.1", path = "crates/aranet-service" } # workspace entry already does, so it is set here. aranet-cli = { version = "0.2.1", path = "crates/aranet-cli", default-features = false } -btleplug = "0.11" +# At least 0.13.5: the first release with the fixes for btleplug's issues #494 (macOS memory +# growth while scanning) and #496 (the 5 s BlueZ service-discovery wait). 0.13.0 is yanked. +btleplug = "0.13.5" tokio = { version = "1", features = ["full"] } thiserror = "2" bytes = "1" diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index 568cfeb..41121d3 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -97,6 +97,7 @@ impl State { // Sending fails only to a stream that has been dropped. let _ = stream.unbounded_send(ValueNotification { uuid, + service_uuid: SAF_TEHNIKA_SERVICE_NEW, value: value.to_vec(), }); } From 8b04ec3131af74772dabe57e04612a55966951fe Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 18:54:18 -0400 Subject: [PATCH 02/21] fix: read a device's name through `peripheral_name`, so that a BlueZ alias never replaces it btleplug 0.13.5 gives `PeripheralProperties::local_name` a different meaning on each operating system. On Linux it is BlueZ's `Alias`: a sensor that the user renamed in a Bluetooth settings dialog would lose its Aranet name and with it its detected type, and a sensor without a type is read and parsed as an Aranet4. A device that BlueZ has no name for would be listed under its address with dashes. On Windows a connect replaces the field with the system's name for the device. On both, the new field `advertisement_name` holds what `local_name` held in 0.11.8. `aranet_core::peripheral_name` is now the one rule for a name: `advertisement_name`, and on macOS only, `local_name` when no name was advertised, which there is CoreBluetooth's own name for the peripheral. The scan, the device lookup, the connect, the passive monitor, the `discover_services` example and the hardware tests' peripheral lookup all take the name from it. It is public because the example and the hardware tests are separate crates, and because a program that calls `properties()` on a peripheral it got from aranet needs the same rule. On macOS it returns what `local_name` holds, so nothing changes there. The test double of a peripheral reports the name in both fields, as the backends do for a named sensor, and the link test reads it through `peripheral_name`: with `local_name` alone it would fail on Linux. Tests: the rule for each backend, through a private function that takes the choice per OS as a flag; one test of the constant that makes the choice, which expects the fallback on macOS and nowhere else; `is_aranet_device`, which had no test; and a guard that reads the sources under `crates/aranet-core/src` and fails if any file but `util.rs` reads `local_name` or `advertisement_name`. Five of the six places that need a name take a real peripheral and cannot be unit-tested, and a read of `advertisement_name` would pass every other test and lose the system's name on macOS for a sensor that has not advertised one. The example and the hardware tests are outside `src`, so the guard does not cover them. Eight hand mutants of the constant, the rule and two read sites, one reading `local_name` again and one reading `advertisement_name`, each failed a test. The mutant that sets the fallback on every OS is the same program on macOS and was run in the Linux container. --- .../aranet-core/examples/discover_services.rs | 7 +- crates/aranet-core/src/device.rs | 7 +- crates/aranet-core/src/lib.rs | 2 +- crates/aranet-core/src/link.rs | 7 +- crates/aranet-core/src/link/fake.rs | 4 + crates/aranet-core/src/passive.rs | 5 +- crates/aranet-core/src/scan.rs | 44 ++- crates/aranet-core/src/util.rs | 261 ++++++++++++++++++ crates/aranet-core/tests/hardware_tests.rs | 4 +- 9 files changed, 328 insertions(+), 13 deletions(-) diff --git a/crates/aranet-core/examples/discover_services.rs b/crates/aranet-core/examples/discover_services.rs index 24c8afd..8c52aa4 100644 --- a/crates/aranet-core/examples/discover_services.rs +++ b/crates/aranet-core/examples/discover_services.rs @@ -77,7 +77,12 @@ async fn main() -> Result<(), Box> { std::process::exit(1); } }; - let name = p.properties().await?.and_then(|props| props.local_name); + let name = p + .properties() + .await? + .as_ref() + .and_then(aranet_core::peripheral_name) + .map(str::to_owned); println!("\nFound: {}", name.as_deref().unwrap_or(&identifier)); diff --git a/crates/aranet-core/src/device.rs b/crates/aranet-core/src/device.rs index 3d76386..b3e8a54 100644 --- a/crates/aranet-core/src/device.rs +++ b/crates/aranet-core/src/device.rs @@ -17,7 +17,7 @@ use uuid::Uuid; use crate::error::{Error, Result}; use crate::scan::ScanOptions; use crate::traits::AranetDevice; -use crate::util::{create_identifier, format_peripheral_id}; +use crate::util::{create_identifier, format_peripheral_id, peripheral_name}; use crate::uuid::{ BATTERY_LEVEL, BATTERY_SERVICE, CURRENT_READINGS_DETAIL, CURRENT_READINGS_DETAIL_ALT, DEVICE_INFO_SERVICE, DEVICE_NAME, FIRMWARE_REVISION, GAP_SERVICE, HARDWARE_REVISION, @@ -602,7 +602,10 @@ impl Device { characteristics_cache.len() ); - let name = properties.as_ref().and_then(|p| p.local_name.clone()); + let name = properties + .as_ref() + .and_then(peripheral_name) + .map(str::to_owned); // Get address - on macOS this may be 00:00:00:00:00:00, so we use peripheral ID as fallback let address = properties diff --git a/crates/aranet-core/src/lib.rs b/crates/aranet-core/src/lib.rs index 74b831c..4cec9fe 100644 --- a/crates/aranet-core/src/lib.rs +++ b/crates/aranet-core/src/lib.rs @@ -246,7 +246,7 @@ pub use reconnect::{ReconnectOptions, ReconnectingDevice}; pub use retry::{RetryConfig, with_retry}; pub use streaming::{ReadingStream, StreamOptions, StreamOptionsBuilder}; pub use thresholds::{Co2Level, ThresholdConfig, Thresholds}; -pub use util::{create_identifier, format_peripheral_id}; +pub use util::{create_identifier, format_peripheral_id, peripheral_name}; pub use validation::{ReadingValidator, ValidationResult, ValidationWarning}; // Re-export from aranet-types diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index b009989..7db693e 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -746,6 +746,7 @@ mod tests { use crate::device::ConnectionConfig; use crate::error::{ConnectionFailureReason, Error}; use crate::test_support::within; + use crate::util::peripheral_name; /// Run a connect on `fake` that must fail, with the default config and the /// test's runtime for cleanup, and return its error. @@ -791,8 +792,12 @@ mod tests { open.pending.disarm(); assert_eq!(open.services, aranet_services()); + // The name, read as every other place in the crate reads it. The + // test double reports it in both name fields: with `local_name` + // alone this would fail on Linux and Windows, where + // `peripheral_name` takes only the advertised name. assert_eq!( - open.properties.and_then(|p| p.local_name).as_deref(), + open.properties.as_ref().and_then(peripheral_name), Some("Aranet4 12345") ); tokio::time::sleep(Duration::from_secs(1)).await; diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index 41121d3..b09f707 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -302,8 +302,12 @@ impl GattLink for FakeGatt { async fn properties(&self) -> btleplug::Result> { let outcome = self.lock().properties.pop_front(); run(outcome).await?; + // Both name fields hold the advertised name, as btleplug 0.13.5 reports + // a named sensor on BlueZ while no alias is set, on CoreBluetooth once + // a name has been advertised, and on WinRT before a connect. Ok(Some(PeripheralProperties { local_name: Some("Aranet4 12345".to_string()), + advertisement_name: Some("Aranet4 12345".to_string()), ..Default::default() })) } diff --git a/crates/aranet-core/src/passive.rs b/crates/aranet-core/src/passive.rs index cfd255d..4221f16 100644 --- a/crates/aranet-core/src/passive.rs +++ b/crates/aranet-core/src/passive.rs @@ -46,6 +46,7 @@ use tracing::{debug, info, warn}; use crate::advertisement::{AdvertisementData, parse_advertisement_with_name}; use crate::error::Result; use crate::scan::get_adapter; +use crate::util::peripheral_name; use crate::uuid::MANUFACTURER_ID; /// Bitwise-exact comparison of two `Option` values (handles NaN correctly). @@ -296,7 +297,7 @@ impl PassiveMonitor { } // Try to parse the advertisement - match parse_advertisement_with_name(data, props.local_name.as_deref()) { + match parse_advertisement_with_name(data, peripheral_name(&props)) { Ok(adv_data) => { // Check for deduplication let should_emit = if self.options.deduplicate { @@ -308,7 +309,7 @@ impl PassiveMonitor { if should_emit { let reading = PassiveReading { device_id: device_id.clone(), - device_name: props.local_name.clone(), + device_name: peripheral_name(&props).map(str::to_owned), rssi: props.rssi, data: adv_data.clone(), received_at: std::time::Instant::now(), diff --git a/crates/aranet-core/src/scan.rs b/crates/aranet-core/src/scan.rs index 747c0a6..4b8930f 100644 --- a/crates/aranet-core/src/scan.rs +++ b/crates/aranet-core/src/scan.rs @@ -63,7 +63,7 @@ async fn reset_manager() { } use crate::error::{Error, Result}; -use crate::util::create_identifier; +use crate::util::{create_identifier, peripheral_name}; use crate::uuid::{MANUFACTURER_ID, SAF_TEHNIKA_SERVICE_NEW, SAF_TEHNIKA_SERVICE_OLD}; use aranet_types::DeviceType; @@ -532,7 +532,7 @@ async fn process_peripheral( let id = peripheral.id(); let address = properties.address.to_string(); - let name = properties.local_name.clone(); + let name = peripheral_name(&properties).map(str::to_owned); let rssi = properties.rssi; // Check if this is an Aranet device @@ -586,7 +586,7 @@ fn is_aranet_device(properties: &btleplug::api::PeripheralProperties) -> bool { } // Check device name for Aranet - if let Some(name) = &properties.local_name { + if let Some(name) = peripheral_name(properties) { let name_lower = name.to_lowercase(); if name_lower.contains("aranet") { return true; @@ -879,7 +879,9 @@ struct KnownPeripheral { peripheral_id: String, /// The Bluetooth address; `00:00:00:00:00:00` on macOS. address: String, - /// The advertised name. + /// The device's name as `peripheral_name` gives it: the advertised name, + /// or on macOS CoreBluetooth's own name for a peripheral that advertised + /// none. name: Option, } @@ -1046,7 +1048,7 @@ async fn search_known_peripherals(adapter: &Adapter, query: &str) -> Result btleplug::api::PeripheralProperties { + btleplug::api::PeripheralProperties { + local_name: Some(local_name.to_string()), + advertisement_name: Some(advertisement_name.to_string()), + ..Default::default() + } + } + + #[test] + fn is_aranet_device_recognises_a_sensor_by_its_name_alone() { + // No manufacturer data and no service: the name is all there is. Both + // fields hold it, as every backend reports a named sensor that has no + // BlueZ alias, so the answer is the same on every host. + assert!(is_aranet_device(&named("Aranet4 12345", "Aranet4 12345"))); + assert!(is_aranet_device(&named("ARANET2 2751B", "ARANET2 2751B"))); + assert!(!is_aranet_device(&named("Standing desk", "Standing desk"))); + let unnamed = btleplug::api::PeripheralProperties::default(); + assert!(!is_aranet_device(&unnamed)); + } + + #[test] + fn is_aranet_device_takes_the_name_from_peripheral_name() { + // As BlueZ reports a sensor that the user has renamed: the first name + // is the alias, the second the sensor's own. + assert!(is_aranet_device(&named("Kitchen", "Aranet4 12345"))); + // A device that the user has named after a sensor is not one. + assert!(!is_aranet_device(&named("Aranet shelf", "Standing desk"))); + } + // ==================== Device Lookup Tests ==================== /// CoreBluetooth UUIDs as `aranet scan` prints them on macOS. The first two diff --git a/crates/aranet-core/src/util.rs b/crates/aranet-core/src/util.rs index 008b9ff..2e78779 100644 --- a/crates/aranet-core/src/util.rs +++ b/crates/aranet-core/src/util.rs @@ -2,6 +2,7 @@ //! //! This module contains shared utility functions used across the crate. +use btleplug::api::PeripheralProperties; use btleplug::platform::PeripheralId; /// Format a peripheral ID as a string. @@ -38,6 +39,80 @@ pub fn create_identifier(address: &str, peripheral_id: &PeripheralId) -> String } } +/// Whether a peripheral that has advertised no name is named by btleplug's +/// `local_name`. Only on macOS, where `local_name` is then CoreBluetooth's own +/// name for the peripheral (btleplug 0.13.5 +/// `src/corebluetooth/internal.rs:1003-1008`). On Linux it is then BlueZ's +/// `Alias` (`src/bluez/peripheral.rs:155`), which for a device BlueZ has no +/// name for is a name the user chose, or else the address with dashes. On +/// Windows a connect sets it to the system's name for the device +/// (`src/winrtble/peripheral.rs:523-531`). aranet has never used either as a +/// sensor's name. +const UNADVERTISED_NAME_IS_LOCAL_NAME: bool = cfg!(target_os = "macos"); + +/// The name of a peripheral as aranet uses it: the name aranet shows, matches +/// a device query against and detects the sensor type from. +/// +/// It is the name the device advertises, which btleplug reports as +/// `advertisement_name`. On macOS only, a peripheral that has advertised no +/// name gets the name CoreBluetooth holds for it, which btleplug reports as +/// `local_name`. +/// +/// Call this function and do not read either field yourself. +/// `advertisement_name` alone leaves a macOS peripheral that has advertised +/// no name without one. `local_name` means something different on each +/// operating system in btleplug 0.13.5 (the files named below are that +/// version's): +/// +/// - **Linux:** BlueZ's `Alias` (`src/bluez/peripheral.rs:155`): the name the +/// user gave the device, else the device's own name, else its address with +/// dashes, such as `60-C0-BF-48-CB-8D` (BlueZ 5.82 `src/device.c:959-980`). +/// Read as a name, it would take a renamed sensor's Aranet name away, and +/// with it the sensor type that is detected from the name, and it would +/// give a name to a device that has none. `advertisement_name` is BlueZ's +/// `Name` (`src/bluez/peripheral.rs:156`), which is what `local_name` was +/// in btleplug 0.11.8. +/// - **Windows:** the advertised name, until a connect replaces it with the +/// system's name for the device (`src/winrtble/peripheral.rs:523-531`). +/// `advertisement_name` is the name from the last advertisement that carried +/// one (`src/winrtble/peripheral.rs:173-180`), which is what `local_name` +/// was in btleplug 0.11.8. +/// - **macOS:** the advertised name once one has been heard, and until then +/// the name CoreBluetooth holds for the peripheral +/// (`src/corebluetooth/internal.rs:1003-1008`, +/// `src/corebluetooth/peripheral.rs:221-235`). On macOS this function +/// returns what `local_name` holds. +/// +/// # Example +/// +/// ``` +/// use aranet_core::peripheral_name; +/// use btleplug::api::PeripheralProperties; +/// +/// // A sensor as BlueZ reports it after the user has renamed it "Kitchen". +/// let properties = PeripheralProperties { +/// local_name: Some("Kitchen".to_string()), +/// advertisement_name: Some("Aranet4 12345".to_string()), +/// ..Default::default() +/// }; +/// assert_eq!(peripheral_name(&properties), Some("Aranet4 12345")); +/// ``` +pub fn peripheral_name(properties: &PeripheralProperties) -> Option<&str> { + name_from(properties, UNADVERTISED_NAME_IS_LOCAL_NAME) +} + +/// `peripheral_name` with the choice that depends on the operating system as a +/// parameter, so that one host can test every rule: the advertised name, or, +/// if there is none and `or_local_name` is set, `local_name`. +fn name_from(properties: &PeripheralProperties, or_local_name: bool) -> Option<&str> { + let advertised = properties.advertisement_name.as_deref(); + if or_local_name { + advertised.or(properties.local_name.as_deref()) + } else { + advertised + } +} + #[cfg(test)] mod tests { // Note: We can't easily create PeripheralId in tests, so we test the logic @@ -59,3 +134,189 @@ mod tests { assert_eq!(address, "00:00:00:00:00:00"); } } + +#[cfg(test)] +mod peripheral_name_tests { + use super::*; + + use std::path::{Path, PathBuf}; + + use aranet_types::DeviceType; + + /// What `name_from` is given on Linux and Windows. + const ADVERTISED_NAME_ONLY: bool = false; + /// What `name_from` is given on macOS. + const OR_LOCAL_NAME: bool = true; + + /// Properties that carry nothing but the two names. + fn named(local_name: Option<&str>, advertisement_name: Option<&str>) -> PeripheralProperties { + PeripheralProperties { + local_name: local_name.map(str::to_owned), + advertisement_name: advertisement_name.map(str::to_owned), + ..Default::default() + } + } + + #[test] + fn bluez_alias_does_not_replace_the_sensors_name() { + // BlueZ, for a sensor the user has renamed: `local_name` is the alias + // and `advertisement_name` is BlueZ's `Name`. + let properties = named(Some("Kitchen"), Some("Aranet2 2751B")); + let name = name_from(&properties, ADVERTISED_NAME_ONLY); + assert_eq!(name, Some("Aranet2 2751B")); + // The sensor type is detected from the name, and a sensor without a + // type is read and parsed as an Aranet4. + assert_eq!( + name.and_then(DeviceType::from_name), + Some(DeviceType::Aranet2) + ); + } + + #[test] + fn bluez_device_without_a_name_has_none() { + // BlueZ, for a device it has no name for: the alias is the address + // with dashes. + let properties = named(Some("60-C0-BF-48-CB-8D"), None); + assert_eq!(name_from(&properties, ADVERTISED_NAME_ONLY), None); + } + + #[test] + fn winrt_connect_does_not_change_the_name() { + // WinRT after a connect: `local_name` is the system's name for the + // device. + let connected = named(Some("Bedroom sensor"), Some("Aranet4 17C3C")); + assert_eq!( + name_from(&connected, ADVERTISED_NAME_ONLY), + Some("Aranet4 17C3C") + ); + // A device that never advertised a name stays without one. + let never_named = named(Some("Bedroom sensor"), None); + assert_eq!(name_from(&never_named, ADVERTISED_NAME_ONLY), None); + } + + #[test] + fn corebluetooth_uses_the_advertised_name() { + // CoreBluetooth once a name has been advertised: both fields hold it. + let properties = named(Some("Aranet4 1A2B3"), Some("Aranet4 1A2B3")); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), Some("Aranet4 1A2B3")); + } + + #[test] + fn corebluetooth_falls_back_to_the_systems_name() { + // CoreBluetooth before any name has been advertised: `local_name` is + // its own name for the peripheral. + let properties = named(Some("Kitchen"), None); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), Some("Kitchen")); + } + + #[test] + fn corebluetooth_peripheral_without_a_name_has_none() { + let properties = named(None, None); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), None); + } + + #[test] + fn an_advertised_name_wins_over_local_name() { + // CoreBluetooth never reports two different names (btleplug 0.13.5 + // `src/corebluetooth/peripheral.rs:221-235`). This pins the order of + // the rule: `local_name` is used only when no name was advertised. + let properties = named(Some("Kitchen"), Some("Aranet2 2751B")); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), Some("Aranet2 2751B")); + } + + /// The one test of `UNADVERTISED_NAME_IS_LOCAL_NAME`. Every other test + /// passes the rule to `name_from` itself, so without this one the constant + /// could be `true` on Linux, which makes a BlueZ alias a sensor's name + /// again, with every other test passing. CI runs it on macOS, Linux and + /// Windows. + #[test] + fn peripheral_name_uses_local_name_only_on_macos() { + let properties = named(Some("Kitchen"), None); + let expected = cfg!(target_os = "macos").then_some("Kitchen"); + assert_eq!(peripheral_name(&properties), expected); + } + + /// Every `.rs` file under `dir`, at any depth. + fn rust_files(dir: &Path, found: &mut Vec) { + for entry in std::fs::read_dir(dir).expect("read a source directory") { + let path = entry.expect("read a directory entry").path(); + if path.is_dir() { + rust_files(&path, found); + } else if path.extension().is_some_and(|extension| extension == "rs") { + found.push(path); + } + } + } + + /// Guard: in aranet-core only `name_from` (this file) reads btleplug's + /// `local_name` and `advertisement_name`. + /// + /// Six places in the crate need a peripheral's name: the scan + /// (`process_peripheral` and `is_aranet_device`), the device lookup + /// (`search_known_peripherals`), the connect + /// (`Device::from_peripheral_with_config`) and the passive monitor, twice. + /// Five of them take a real btleplug peripheral and cannot be unit-tested, + /// so no other test would notice if one of them read a field itself. A + /// site that read `local_name` would name a sensor on Linux by its BlueZ + /// alias, and the sensor would lose its type. A site that read + /// `advertisement_name` directly would pass every other test and lose the + /// system's name on macOS for a sensor that has not advertised one. + /// + /// So this test reads the source files. It fails on either field's name + /// after a dot, in code or in a comment, in any file but this one. A + /// struct literal that sets the fields has no dot before their names and + /// passes: the test double of a peripheral (`link/fake.rs`) sets them + /// that way. + /// + /// It searches `src` only. The `discover_services` example and the + /// hardware tests' `known_peripheral` take the name from `peripheral_name` + /// too, but they are outside `src`, and this test does not read them. + #[test] + fn only_peripheral_name_reads_the_name_fields() { + // Each in two halves, so that this test is not itself an occurrence of + // the texts it searches for. + let field_reads = [ + [".local", "_name"].concat(), + [".advertisement", "_name"].concat(), + ]; + let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src"); + // The one file that may read the fields: `name_from` is above. + let exempt = Path::new("util.rs"); + + let mut files = Vec::new(); + rust_files(&src, &mut files); + files.sort(); + + let mut exempt_seen = false; + let mut reads = Vec::new(); + for file in &files { + let relative = file.strip_prefix(&src).expect("a path under src"); + if relative == exempt { + exempt_seen = true; + continue; + } + let text = std::fs::read_to_string(file).expect("read a source file"); + for (index, line) in text.lines().enumerate() { + if field_reads.iter().any(|field| line.contains(field)) { + reads.push(format!( + "{}:{}: {}", + relative.display(), + index + 1, + line.trim() + )); + } + } + } + + assert!( + exempt_seen, + "util.rs is not under {}; if it was renamed, rename it here too", + src.display() + ); + assert!( + reads.is_empty(), + "these lines read `local_name` or `advertisement_name`; use `peripheral_name`:\n{}", + reads.join("\n") + ); + } +} diff --git a/crates/aranet-core/tests/hardware_tests.rs b/crates/aranet-core/tests/hardware_tests.rs index 9cee3eb..b42822f 100644 --- a/crates/aranet-core/tests/hardware_tests.rs +++ b/crates/aranet-core/tests/hardware_tests.rs @@ -1468,7 +1468,9 @@ async fn known_peripheral(device: &str) -> Option Date: Sun, 11 Oct 2026 19:09:40 -0400 Subject: [PATCH 03/21] refactor: remove the matching of either half of a macOS combined name, which btleplug 0.13.5 never builds btleplug 0.11.8 named a macOS peripheral `" []"` when CoreBluetooth's name for it differed from the name it advertised, and since f04ade7 a device lookup also matched either half of such a name. 0.13.5 never builds that form: the name is the advertised one. The rule could only still match a device whose own name ends in `]`, and no release has had it: f04ade7 is later than v0.2.1. `name_matches` now compares the whole name and nothing else, ignoring case and the spaces around it as before. Its two copies go too, in the `lifecycle_soak` example and in the hardware tests' peripheral lookup. The rustdoc of `find_device` loses the sentence that described the rule and points to `peripheral_name` for what a device's name is. Tests: a name with a bracketed part is found by the whole name and by neither half, in `lookup` and in the example, and both tests failed against the old code. A name with spaces around it is still found. With the branch put back, the trim removed, the comparison made case-sensitive or `==` turned into `contains`, a lookup test fails each time. The copy in the hardware tests needs a sensor and was only compiled. Nothing else in the upgrade depends on this commit: without it the branch is dead code for every name btleplug 0.13.5 reports. --- crates/aranet-core/examples/lifecycle_soak.rs | 17 ++----- crates/aranet-core/src/scan.rs | 48 ++++++++++++------- crates/aranet-core/tests/hardware_tests.rs | 15 ++---- 3 files changed, 40 insertions(+), 40 deletions(-) diff --git a/crates/aranet-core/examples/lifecycle_soak.rs b/crates/aranet-core/examples/lifecycle_soak.rs index 23cfc03..e6bd152 100644 --- a/crates/aranet-core/examples/lifecycle_soak.rs +++ b/crates/aranet-core/examples/lifecycle_soak.rs @@ -245,16 +245,9 @@ fn parse_args(args: impl IntoIterator) -> Result, St Ok(Some(parsed)) } -/// Whether `name` is `query`, ignoring case, or either half of CoreBluetooth's -/// combined `" []"`. +/// Whether `name` is `query`, ignoring case. Only the whole name counts. fn name_matches(name: &str, query: &str) -> bool { name.eq_ignore_ascii_case(query) - || name - .strip_suffix(']') - .and_then(|rest| rest.split_once(" [")) - .is_some_and(|(gap, advertised)| { - gap.eq_ignore_ascii_case(query) || advertised.eq_ignore_ascii_case(query) - }) } /// Which driver a link cut or an event belongs to. @@ -1334,12 +1327,12 @@ mod tests { } #[test] - fn name_matching_is_exact_but_accepts_either_half_of_a_corebluetooth_name() { + fn name_matching_is_exact_apart_from_case() { assert!(name_matches("Aranet2 2751B", "aranet2 2751b")); assert!(!name_matches("Aranet2 2751B", "2751B")); - assert!(name_matches("Kitchen [Aranet4 1A2B3]", "Aranet4 1A2B3")); - assert!(name_matches("Kitchen [Aranet4 1A2B3]", "kitchen")); - assert!(!name_matches("Kitchen [Aranet4 1A2B3]", "Aranet4")); + // A bracketed part is part of the name like any other. + assert!(name_matches("Hall [Aranet2 2751B]", "hall [aranet2 2751b]")); + assert!(!name_matches("Hall [Aranet2 2751B]", "hall")); } #[test] diff --git a/crates/aranet-core/src/scan.rs b/crates/aranet-core/src/scan.rs index 4b8930f..b426145 100644 --- a/crates/aranet-core/src/scan.rs +++ b/crates/aranet-core/src/scan.rs @@ -678,8 +678,8 @@ fn after_missed_scan( /// - btleplug's device ID as [`DiscoveredDevice::id`] displays it /// (`hci0/dev_AA_BB_CC_DD_EE_FF` on Linux); /// - the MAC address, with or without colons; -/// - the whole advertised name. On macOS a name shown as -/// `"Kitchen [Aranet4 1A2B3]"` also matches `Kitchen` or `Aranet4 1A2B3`. +/// - the device's whole name, as [`peripheral_name`] gives it and +/// [`DiscoveredDevice::name`] holds it. /// /// An address or identifier match wins over a name match. /// @@ -915,9 +915,12 @@ fn parse_query(identifier: &str) -> Result<&str> { /// 1. an identifier: the one `aranet scan` prints, btleplug's device ID (the /// `hci0/dev_…` form on Linux), or the Bluetooth address with or without /// colons, never `00:00:00:00:00:00`; -/// 2. the whole advertised name, or either half of CoreBluetooth's combined -/// `" []"` (btleplug 0.11.8, -/// `corebluetooth/internal.rs:577-585`). +/// 2. the whole name, ignoring the spaces around it. Part of a name never +/// matches, and that includes a name with a bracketed part: btleplug +/// 0.11.8 named some macOS peripherals +/// `" []"`, and 0.13.5 never builds that +/// form (`src/corebluetooth/internal.rs:1003-1008`, +/// `src/corebluetooth/peripheral.rs:221-235`). /// /// One match is `Found` and several are `Ambiguous`. With no match, `NotFound` /// lists the peripherals whose name contains both `query` and `aranet`, so a @@ -975,15 +978,10 @@ fn decide(indices: Vec) -> Option { } } -/// Whether the advertised `name` is `query` (lower case): the whole name, or -/// either half of CoreBluetooth's `" []"`. +/// Whether `name` is `query` (lower case): the whole name, ignoring case and +/// the spaces around it. fn name_matches(name: &str, query: &str) -> bool { - let name = name.trim().to_lowercase(); - name == query - || name - .strip_suffix(']') - .and_then(|combined| combined.rsplit_once(" [")) - .is_some_and(|(gap, advertised)| gap.trim() == query || advertised.trim() == query) + name.trim().to_lowercase() == query } /// What a search of the known peripherals found. @@ -1823,17 +1821,35 @@ mod tests { } } + /// Only the whole name matches, also when the name has a bracketed part. + /// btleplug 0.11.8 named some macOS peripherals + /// `" []"`, and while aranet used it, each + /// half of such a name matched too. btleplug 0.13.5 never builds that form. #[test] - fn lookup_matches_either_half_of_a_corebluetooth_combined_name() { + fn lookup_matches_a_name_with_a_bracketed_part_only_as_a_whole() { let devices = [ on_macos(UUID_2, "AranetRn+ 306B8"), on_macos(UUID_1, "Kitchen [Aranet4 1A2B3]"), ]; - for query in ["Aranet4 1A2B3", "kitchen", "Kitchen [Aranet4 1A2B3]"] { - assert_eq!(lookup(query, &devices), Lookup::Found(1), "{query:?}"); + assert_eq!( + lookup("kitchen [aranet4 1a2b3]", &devices), + Lookup::Found(1) + ); + for half in ["Kitchen", "Aranet4 1A2B3"] { + assert_eq!( + lookup(half, &devices), + Lookup::NotFound { similar: vec![1] }, + "{half:?}" + ); } } + #[test] + fn lookup_ignores_spaces_around_a_device_name() { + let devices = [on_macos(UUID_1, " Aranet2 2751B ")]; + assert_eq!(lookup("aranet2 2751b", &devices), Lookup::Found(0)); + } + #[test] fn lookup_prefers_an_identifier_match_over_a_name_match() { let devices = [ diff --git a/crates/aranet-core/tests/hardware_tests.rs b/crates/aranet-core/tests/hardware_tests.rs index b42822f..5d7ca85 100644 --- a/crates/aranet-core/tests/hardware_tests.rs +++ b/crates/aranet-core/tests/hardware_tests.rs @@ -1455,9 +1455,8 @@ fn test_get_adapter_still_discovers_after_its_runtime_shuts_down() { // ============================================================================= /// The adapter's peripheral for `device`: its scan identifier, its btleplug ID, or its -/// name (either half of CoreBluetooth's "GAP [advertised]" form), any case. `None` -/// when the adapter doesn't know it: CoreBluetooth forgets a peripheral once it -/// has disconnected, until a scan finds it again. +/// whole name, any case. `None` when the adapter doesn't know it: CoreBluetooth +/// forgets a peripheral once it has disconnected, until a scan finds it again. async fn known_peripheral(device: &str) -> Option { use btleplug::api::{Central as _, Peripheral as _}; @@ -1472,15 +1471,7 @@ async fn known_peripheral(device: &str) -> Option Date: Sun, 11 Oct 2026 19:22:49 -0400 Subject: [PATCH 04/21] test: make the BlueZ test double wait 30 s, as bluez-async 0.9.0 does btleplug 0.13.5 brings bluez-async 0.9.0, whose `connect` waits 30 s for BlueZ's `ServicesResolved` where 0.8.2 waited 5 s. The test double still modelled 5 s, so the tests described a library that aranet no longer uses. `BLUEZ_ASYNC_WAIT` is now 30 s, and its doc says how a first connect must be scripted at a 30 s connect limit. With the constant alone at 30 s, seven tests of `link::bluez_discovery_tests` fail: each scripts a library timeout that aranet's own 15 s connect limit or 20 s wait now ends first. They are restated: - Five keep their path, which starts with the library's timeout, by setting a 45 s connect limit (`LONG_CONNECT_LIMIT`). One of them now sees exactly two connects where it saw at least five. - Two start at aranet's connect limit. They script the one re-ask that the wait makes there now, in place of 5 s rounds. `a_longer_discovery_timeout_waits_longer` passed on a tie: the end of the wait and the end of a library round fell on the same instant. It now uses a 40 s `discovery_timeout`, so the wait ends between two rounds. `a_connect_timeout_with_the_link_up_gives_up_after_the_wait` asserts its exact calls. Two tests are new, the default-limit twins of `another_error_ends_the_wait` and `the_zero_services_retry_waits_too`. No production code changes: everything above `mod tests` in `link.rs` is unchanged. The module's 18 tests pass, the crate's tests pass, and the format check and clippy on stable and on 1.90 are clean. --- crates/aranet-core/src/link.rs | 226 ++++++++++++++++++++++------ crates/aranet-core/src/link/fake.rs | 16 +- 2 files changed, 191 insertions(+), 51 deletions(-) diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index 7db693e..13c6853 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -1679,6 +1679,14 @@ mod bluez_discovery_tests { /// when BlueZ answered `In Progress` (`BLUEZ_IN_PROGRESS_PAUSE`). const IN_PROGRESS_PAUSE: Duration = Duration::from_secs(1); + /// A connect limit longer than bluez-async's 30 s wait for the services + /// (`BLUEZ_ASYNC_WAIT`). Only under such a limit can bluez-async's own + /// "Service discovery timed out" end a first connect: under the default + /// 15 s, and under `aranet watch`'s 30 s, the connect's limit ends it + /// first. The tests of the paths that start with the library's timeout + /// use this limit. + const LONG_CONNECT_LIMIT: Duration = Duration::from_secs(45); + /// Connect `fake` with `config` and the test's runtime for cleanup, and /// disarm the link if the connect succeeds. pub(super) async fn connect_with(fake: &FakeGatt, config: &ConnectionConfig) -> Result<()> { @@ -1711,8 +1719,13 @@ mod bluez_discovery_tests { } } - /// A connect that bluez-async gives up on while BlueZ is still discovering - /// asks again until BlueZ has resolved the services, then discovers them. + /// Under a connect limit longer than bluez-async's wait, a connect that + /// bluez-async gives up on while BlueZ is still discovering asks again + /// until BlueZ has resolved the services, then discovers them. The second + /// "Service discovery timed out" here comes from a re-ask inside the + /// wait, which needs a `discovery_timeout` above bluez-async's 30 s too: + /// at the default limits the wait's own limit ends the first re-ask + /// (`a_connect_timeout_with_the_link_up_gives_up_after_the_wait`). #[tokio::test(start_paused = true)] async fn waits_while_bluez_is_still_discovering() { within(Duration::from_secs(600), async { @@ -1722,12 +1735,18 @@ mod bluez_discovery_tests { Outcome::DiscoveryTimedOut, Outcome::Ok, ]); + let config = ConnectionConfig::default() + .connection_timeout(LONG_CONNECT_LIMIT) + .discovery_timeout(Duration::from_secs(70)); let start = Instant::now(); - connect_with(&fake, &ConnectionConfig::default()) + connect_with(&fake, &config) .await .expect("the connect should wait for BlueZ's service discovery"); + // The library gives up at 30 s. The wait then lasts until 100 s + // (30 + 70): the first re-ask gives up at 60 s (30 + 30) and the + // second succeeds at once. assert_eq!(start.elapsed(), 2 * BLUEZ_ASYNC_WAIT); assert_eq!( fake.calls(), @@ -1739,56 +1758,78 @@ mod bluez_discovery_tests { /// A discovery that never finishes fails as a "discover services" timeout /// `MIN_WAIT` after bluez-async gave up, even with a shorter - /// `discovery_timeout`, and disconnects. + /// `discovery_timeout`, and disconnects. The wait makes one re-ask: + /// bluez-async waits 30 s on it, longer than the 20 s the wait has. #[tokio::test(start_paused = true)] async fn gives_up_after_the_minimum_wait_and_disconnects() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.script_connect(std::iter::repeat_with(|| Outcome::DiscoveryTimedOut).take(10)); - let config = ConnectionConfig::default().discovery_timeout(Duration::from_secs(5)); + let config = ConnectionConfig::default() + .connection_timeout(LONG_CONNECT_LIMIT) + .discovery_timeout(Duration::from_secs(5)); let start = Instant::now(); let result = connect_with(&fake, &config).await; assert_discovery_timeout(result, MIN_WAIT); + // The library gives up at 30 s. The wait ends at 50 s (30 + 20), + // before the re-ask's own 30 s are over (60 s). assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + MIN_WAIT); - let calls = fake.calls(); - assert_eq!(calls.last(), Some(&Call::Disconnect), "calls: {calls:?}"); - assert!(!calls.contains(&Call::Discover), "calls: {calls:?}"); - let connects = calls.iter().filter(|call| **call == Call::Connect).count(); - assert!(connects >= 5, "calls: {calls:?}"); + assert_eq!( + fake.calls(), + [Call::Connect, Call::Connect, Call::Disconnect] + ); }) .await; } - /// A `discovery_timeout` longer than `MIN_WAIT` lengthens the wait. + /// A `discovery_timeout` longer than `MIN_WAIT` lengthens the wait. With + /// 40 s the wait ends between two of bluez-async's 30 s rounds, so the + /// end of the wait and the end of a round can't be mistaken for each + /// other. #[tokio::test(start_paused = true)] async fn a_longer_discovery_timeout_waits_longer() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.script_connect(std::iter::repeat_with(|| Outcome::DiscoveryTimedOut).take(10)); - let config = ConnectionConfig::challenging_environment(); + let config = ConnectionConfig::default() + .connection_timeout(Duration::from_secs(90)) + .discovery_timeout(Duration::from_secs(40)); let start = Instant::now(); let result = connect_with(&fake, &config).await; - assert_discovery_timeout(result, Duration::from_secs(30)); - assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + Duration::from_secs(30)); - assert_eq!(fake.calls().last(), Some(&Call::Disconnect)); + assert_discovery_timeout(result, Duration::from_secs(40)); + // The library gives up at 30 s and the wait ends at 70 s + // (30 + 40). The first re-ask gives up at 60 s; the second would + // at 90 s. + assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + Duration::from_secs(40)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::Connect, + Call::Connect, + Call::Disconnect, + ] + ); }) .await; } - /// Any other error ends the wait at once and fails the connect: here the - /// link dropped and BlueZ's new connection attempt failed. + /// Any other error ends the wait at once and fails the connect: here + /// bluez-async gave up under a long connect limit, the link had dropped, + /// and BlueZ's new connection attempt failed. #[tokio::test(start_paused = true)] async fn another_error_ends_the_wait() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.script_connect([Outcome::DiscoveryTimedOut, Outcome::Fail]); + let config = ConnectionConfig::default().connection_timeout(LONG_CONNECT_LIMIT); let start = Instant::now(); - let result = connect_with(&fake, &ConnectionConfig::default()).await; + let result = connect_with(&fake, &config).await; assert_eq!( fake.calls(), @@ -1801,24 +1842,65 @@ mod bluez_discovery_tests { ), "got {result:?}" ); + // The library gives up at 30 s and the re-ask fails at once. assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT); }) .await; } - /// The reconnect of the zero-services retry waits for BlueZ too. + /// The same at the default limits, where the wait starts at the connect's + /// own time limit: any other error from the re-ask ends the wait at once + /// and fails the connect. + #[tokio::test(start_paused = true)] + async fn another_error_ends_the_wait_after_a_connect_timeout() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::Hang, Outcome::Fail]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + let result = connect_with(&fake, &config).await; + + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Disconnect, + ] + ); + assert!( + matches!( + result, + Err(Error::Bluetooth(btleplug::Error::RuntimeError(_))) + ), + "got {result:?}" + ); + // The connect's limit ends at 15 s and the re-ask fails at once. + assert_eq!(start.elapsed(), config.connection_timeout); + }) + .await; + } + + /// The reconnect of the zero-services retry waits for BlueZ too: here + /// after bluez-async gave up on it, under a long connect limit. #[tokio::test(start_paused = true)] async fn the_zero_services_retry_waits_too() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.service_rounds([BTreeSet::new()]); fake.script_connect([Outcome::Ok, Outcome::DiscoveryTimedOut, Outcome::Ok]); + let config = ConnectionConfig::default().connection_timeout(LONG_CONNECT_LIMIT); let start = Instant::now(); - connect_with(&fake, &ConnectionConfig::default()) + connect_with(&fake, &config) .await .expect("the retry should wait for BlueZ's service discovery"); + // The retry's 2 s pause, then the library gives up 30 s into the + // reconnect and the re-ask succeeds at once: 32 s. assert_eq!(start.elapsed(), Duration::from_secs(2) + BLUEZ_ASYNC_WAIT); assert_eq!( fake.calls(), @@ -1835,32 +1917,67 @@ mod bluez_discovery_tests { .await; } - /// On BlueZ, a connect that runs out of time after the link came up, too - /// late for bluez-async's 5 s wait for the services to run out first, - /// waits for BlueZ's service discovery in the same way. The wait's limit - /// starts when the connect's ends and also covers the connection-state - /// query, which answers at once here, so the wait and the discovery get - /// all of it. + /// The same at the default limits: the retry's reconnect runs out of time + /// with the link up, the wait asks again, and BlueZ resolves the services + /// 4 s into the wait. #[tokio::test(start_paused = true)] - async fn a_connect_timeout_with_the_link_up_waits_on_bluez() { + async fn the_zero_services_retry_connects_after_a_connect_timeout() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.set_bluez(true); + fake.service_rounds([BTreeSet::new()]); fake.script_connect([ + Outcome::Ok, Outcome::Hang, - Outcome::DiscoveryTimedOut, - Outcome::DiscoveryTimedOut, - Outcome::DiscoveryTimedOut, Outcome::After(Duration::from_secs(4)), ]); let config = ConnectionConfig::default(); let start = Instant::now(); + connect_with(&fake, &config) + .await + .expect("the retry should wait for BlueZ's service discovery"); + + // 2 s pause + 15 s connect limit + 4 s into the wait = 21 s. + assert_eq!(start.elapsed(), Duration::from_secs(21)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::Discover, + Call::Disconnect, + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } + + /// On BlueZ at the default limits, a connect whose discovery outlasts the + /// connect's 15 s runs out of time with the link up: bluez-async is still + /// inside its own 30 s wait for the services then. The connect waits for + /// BlueZ's service discovery by asking again. The wait's limit starts + /// when the connect's ends and also covers the connection-state query, + /// which answers at once here, so the wait and the discovery get all of + /// it: BlueZ may take 19 of its 20 s. + #[tokio::test(start_paused = true)] + async fn a_connect_timeout_with_the_link_up_waits_on_bluez() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(19))]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + connect_with(&fake, &config) .await .expect("the connect should wait for BlueZ's service discovery"); - // BlueZ resolves the services 19 s into the wait: 1 s inside it. + // BlueZ resolves the services 19 s into the wait: 1 s inside it + // (15 + 19 = 34 s). assert_eq!( start.elapsed(), config.connection_timeout + MIN_WAIT - Duration::from_secs(1) @@ -1871,9 +1988,6 @@ mod bluez_discovery_tests { Call::Connect, Call::IsConnected, Call::Connect, - Call::Connect, - Call::Connect, - Call::Connect, Call::Discover, ] ); @@ -1882,7 +1996,11 @@ mod bluez_discovery_tests { } /// On BlueZ, when that wait never ends, the connect fails as a "discover - /// services" timeout after the wait's limit, and disconnects. + /// services" timeout after the wait's limit, and disconnects. The wait + /// makes one re-ask, which is still inside bluez-async's 30 s when the + /// wait's 20 s are over. This is also how a link ends that BlueZ still + /// reports as connected after it has died: the connection check passes, + /// and no re-ask ever finds the services. #[tokio::test(start_paused = true)] async fn a_connect_timeout_with_the_link_up_gives_up_after_the_wait() { within(Duration::from_secs(600), async { @@ -1896,22 +2014,28 @@ mod bluez_discovery_tests { let result = connect_with(&fake, &config).await; assert_discovery_timeout(result, MIN_WAIT); + // The connect's limit ends at 15 s and the wait at 35 s + // (15 + 20). The re-ask's own 30 s would last until 45 s. assert_eq!(start.elapsed(), config.connection_timeout + MIN_WAIT); - let calls = fake.calls(); assert_eq!( - calls[..3], - [Call::Connect, Call::IsConnected, Call::Connect], - "calls: {calls:?}" + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Disconnect, + ] ); - assert_eq!(calls.last(), Some(&Call::Disconnect), "calls: {calls:?}"); - assert!(!calls.contains(&Call::Discover), "calls: {calls:?}"); }) .await; } /// On BlueZ, a connect that runs out of time with the link down fails as /// before, with the "connect to device" timeout, and disconnects without - /// waiting. + /// waiting. The link may never have come up, or it came up and dropped + /// while bluez-async was still waiting for the services: bluez-async + /// does not watch the link during that wait. Neither case is asked again + /// inside the connect. #[tokio::test(start_paused = true)] async fn a_connect_timeout_with_the_link_down_fails_on_bluez() { within(Duration::from_secs(600), async { @@ -2066,7 +2190,8 @@ mod bluez_discovery_tests { /// refuses the wait's first re-asks with `In Progress` until it has /// answered the timed-out `Device1.Connect`, which it does once the ATT /// channel is up. The wait asks again after a pause each time, then waits - /// for the discovery as before. + /// for the discovery as before: here BlueZ takes another 5 s once it has + /// accepted a re-ask. #[tokio::test(start_paused = true)] async fn a_connect_timeout_waits_while_bluez_is_still_connecting() { within(Duration::from_secs(600), async { @@ -2077,8 +2202,7 @@ mod bluez_discovery_tests { Outcome::InProgress, Outcome::InProgress, Outcome::InProgress, - Outcome::DiscoveryTimedOut, - Outcome::Ok, + Outcome::After(Duration::from_secs(5)), ]); let config = ConnectionConfig::default(); let start = Instant::now(); @@ -2087,9 +2211,10 @@ mod bluez_discovery_tests { .await .expect("the connect should wait while BlueZ is still connecting"); + // 15 s connect limit + three 1 s pauses + 5 s = 23 s. assert_eq!( start.elapsed(), - config.connection_timeout + 3 * IN_PROGRESS_PAUSE + BLUEZ_ASYNC_WAIT + config.connection_timeout + 3 * IN_PROGRESS_PAUSE + Duration::from_secs(5) ); assert!(start.elapsed() <= config.connection_timeout + MIN_WAIT); assert_eq!( @@ -2101,7 +2226,6 @@ mod bluez_discovery_tests { Call::Connect, Call::Connect, Call::Connect, - Call::Connect, Call::Discover, ] ); @@ -2146,17 +2270,23 @@ mod bluez_discovery_tests { /// After bluez-async's own discovery timeout, BlueZ has answered /// `Device1.Connect`, so an `In Progress` comes from another connect to /// the device or a pairing of it, and ends the wait at once, as before. + /// This path needs a connect limit above bluez-async's 30 s wait. Under + /// the default limits every wait starts at the connect's own time limit, + /// and there `In Progress` is asked again + /// (`a_connect_timeout_gives_up_while_bluez_stays_in_progress`). #[tokio::test(start_paused = true)] async fn in_progress_ends_the_wait_after_bluez_async_gave_up() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.set_bluez(true); fake.script_connect([Outcome::DiscoveryTimedOut, Outcome::InProgress]); + let config = ConnectionConfig::default().connection_timeout(LONG_CONNECT_LIMIT); let start = Instant::now(); - let result = connect_with(&fake, &ConnectionConfig::default()).await; + let result = connect_with(&fake, &config).await; assert_in_progress(result); + // The library gives up at 30 s and the re-ask is refused at once. assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT); assert_eq!( fake.calls(), diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index b09f707..629b036 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -38,9 +38,19 @@ pub(super) enum Outcome { } /// How long bluez-async's `connect` waits for BlueZ's `ServicesResolved` -/// before it fails (`SERVICE_DISCOVERY_TIMEOUT`, bluez-async 0.8.2 -/// `src/lib.rs:61`). -pub(super) const BLUEZ_ASYNC_WAIT: std::time::Duration = std::time::Duration::from_secs(5); +/// before it fails (`SERVICE_DISCOVERY_TIMEOUT`, bluez-async 0.9.0 +/// `src/lib.rs:61`). It was 5 s before btleplug 0.13.5. +/// +/// Never script `Outcome::DiscoveryTimedOut` for a first connect whose +/// `connection_timeout` is 30 s: script `Outcome::Hang`. bluez-async starts +/// this wait only once BlueZ has answered `Device1.Connect`, so on a real +/// host its timeout comes more than 30 s after the call, and a connect limit +/// of 30 s or less always ends first. This fake starts the wait at the call. +/// With a limit of exactly 30 s both would end at the same instant of the +/// paused clock, `tokio::time::timeout` polls the call before its own timer, +/// and the test would see the library's timeout first: an order that cannot +/// happen. Under a shorter limit the fake keeps the real order. +pub(super) const BLUEZ_ASYNC_WAIT: std::time::Duration = std::time::Duration::from_secs(30); /// A call made on a `FakeGatt`, in the order it was made. #[derive(Debug, Clone, PartialEq, Eq)] From 1ec34addfdc3481853a91679cb7cb1a1658d758f Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 19:37:01 -0400 Subject: [PATCH 05/21] test: cover the BlueZ connect paths that a 30 s library wait makes the usual ones With a 30 s wait in the library, a slow service discovery at the default limits ends at aranet's own 15 s connect limit with the link up, and the wait after it makes one re-ask. No test scripted that as its own case. Eight tests are added, on the 30 s double: - the usual slow first connect, and the same after a pairing step that used its whole budget; - `aranet watch`'s 30 s limit: a 20 s discovery needs no wait, and a link that is down at the limit is not asked again inside the connect; - a 90 s limit: the library gives up first and the re-ask connects; - the library's 30 s limit on the D-Bus call, through a new outcome of the double, `DbusTimeout`: the connect fails with "Timeout waiting for reply", without a connection check or a wait; - a discovery that BlueZ ends itself with no services goes into the zero-services retry; - a guard that fails if the double's wait is ever set to the default connect limit or below. No production code changes: everything above `mod tests` in `link.rs` is unchanged. `link::bluez_discovery_tests` has 25 tests and `link::pairing_tests` 6; they and the crate's other tests pass, and the format check and clippy on stable, on 1.90 and for each feature of aranet-core are clean. --- crates/aranet-core/src/link.rs | 265 +++++++++++++++++++++++++++- crates/aranet-core/src/link/fake.rs | 18 ++ 2 files changed, 282 insertions(+), 1 deletion(-) diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index 13c6853..b77b85f 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -1665,7 +1665,7 @@ mod bluez_discovery_tests { use tokio::time::Instant; use super::connect; - use super::fake::{BLUEZ_ASYNC_WAIT, Call, FakeGatt, Outcome}; + use super::fake::{BLUEZ_ASYNC_WAIT, BLUEZ_DBUS_TIMEOUT, Call, FakeGatt, Outcome}; use super::tests::assert_timeout; use crate::device::ConnectionConfig; use crate::error::{Error, Result}; @@ -2314,6 +2314,234 @@ mod bluez_discovery_tests { }) .await; } + + /// The usual slow first connect on BlueZ at the default limits: BlueZ is + /// still discovering when the connect's 15 s end, the link is up, and + /// BlueZ resolves the services 8 s into the wait. The connect succeeds + /// with one connection-state query and one re-ask. + #[tokio::test(start_paused = true)] + async fn a_discovery_that_outlasts_the_connect_limit_connects_through_the_wait() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(8))]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // 15 s connect limit + 8 s into the wait = 23 s. + assert_eq!(start.elapsed(), Duration::from_secs(23)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } + + /// `aranet watch` connects with a 30 s limit by default. There a + /// discovery that takes 20 s finishes inside bluez-async's own wait for + /// the services, so the connect succeeds without a connection-state + /// query or a re-ask. + #[tokio::test(start_paused = true)] + async fn a_slow_discovery_inside_a_30_s_connect_limit_needs_no_wait() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::After(Duration::from_secs(20))]); + let config = ConnectionConfig::default().connection_timeout(Duration::from_secs(30)); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("bluez-async's own wait should cover the discovery"); + + // The one connect returns at 20 s, inside the 30 s limit. + assert_eq!(start.elapsed(), Duration::from_secs(20)); + assert_eq!(fake.calls(), [Call::Connect, Call::Discover]); + }) + .await; + } + + /// At `aranet watch`'s 30 s limit too, a connect that runs out of time + /// with the link down fails with its own timeout and is not asked again + /// inside the connect. That covers a link that came up and dropped while + /// bluez-async was waiting for the services: under a limit of 30 s or + /// less nothing re-dials it here, and the caller's own retry does. + #[tokio::test(start_paused = true)] + async fn a_30_s_connect_timeout_with_the_link_down_is_not_asked_again() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.set_connected(false); + fake.script_connect([Outcome::Hang]); + let config = ConnectionConfig::default().connection_timeout(Duration::from_secs(30)); + let start = Instant::now(); + + let error = connect_with(&fake, &config) + .await + .expect_err("the connect should fail"); + + assert_timeout(&error, "connect to device", Duration::from_secs(30)); + // The connect's limit ends at 30 s; the query finds the link down. + assert_eq!(start.elapsed(), Duration::from_secs(30)); + assert_eq!( + fake.calls(), + [Call::Connect, Call::IsConnected, Call::Disconnect] + ); + }) + .await; + } + + /// Under a connect limit longer than bluez-async's wait + /// (`ConnectionConfig::challenging_environment()`: a 90 s connect limit + /// and a 30 s `discovery_timeout`), bluez-async gives up first, 30 s in. + /// The wait asks again, and BlueZ resolves the services 6 s later. No + /// connection-state query is made: bluez-async's timeout itself shows + /// that BlueZ had answered `Device1.Connect`. Under such a limit this is + /// also how a link that dropped during bluez-async's wait is dialled + /// again: the re-ask makes BlueZ open a new one. + #[tokio::test(start_paused = true)] + async fn bluez_async_gives_up_first_under_a_long_connect_limit() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([ + Outcome::DiscoveryTimedOut, + Outcome::After(Duration::from_secs(6)), + ]); + let config = ConnectionConfig::challenging_environment(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // The library gives up at 30 s; the re-ask succeeds 6 s later. + assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + Duration::from_secs(6)); + assert_eq!(fake.calls(), [Call::Connect, Call::Connect, Call::Discover]); + }) + .await; + } + + /// bluez-async gives each D-Bus call 30 s. When BlueZ sends no reply to + /// `Device1.Connect` in that time, a connect whose own limit is longer + /// fails with bluez-async's error, "Timeout waiting for reply". That is + /// not a timeout of the connect itself, so no connection-state query is + /// made and no wait starts: the connect disconnects and returns the + /// error. + #[tokio::test(start_paused = true)] + async fn a_dbus_reply_timeout_fails_the_connect_without_a_wait() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::DbusTimeout]); + let config = ConnectionConfig::challenging_environment(); + let start = Instant::now(); + + let result = connect_with(&fake, &config).await; + + match result { + Err(Error::Bluetooth(btleplug::Error::Other(e))) => { + assert_eq!(e.to_string(), "Timeout waiting for reply"); + } + other => panic!("expected the D-Bus reply timeout, got {other:?}"), + } + // The D-Bus call's limit ends at 30 s, inside the 90 s connect + // limit. + assert_eq!(start.elapsed(), BLUEZ_DBUS_TIMEOUT); + assert_eq!(fake.calls(), [Call::Connect, Call::Disconnect]); + }) + .await; + } + + /// A guard on the fake. bluez-async waits 30 s for the services, so at + /// the default 15 s connect limit its "Service discovery timed out" can + /// never arrive before the connect's own limit ends. This script would + /// let it: with `BLUEZ_ASYNC_WAIT` at the default connect limit or below, + /// the library's timeout would start the wait, with no connection-state + /// query, and the test fails. With the wait at 30 s the connect's limit + /// ends the first call and the scripted timeout is never seen. + #[tokio::test(start_paused = true)] + async fn bluez_async_cannot_give_up_first_at_the_default_connect_limit() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([ + Outcome::DiscoveryTimedOut, + Outcome::After(Duration::from_secs(2)), + ]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // 15 s connect limit + 2 s into the wait = 17 s. The scripted + // library timeout would have come at 30 s. + assert_eq!(start.elapsed(), Duration::from_secs(17)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } + + /// A discovery that stalls is ended by BlueZ itself: BlueZ 5.82 gives an + /// ATT request 30 s (`src/shared/att.c`, `ATT_TIMEOUT_INTERVAL`), then + /// shuts the channel down and marks the services as resolved although it + /// found none. A connect at the default limits waits up to 35 s in all + /// (15 s to its own limit, then a 20 s wait), so it can still be waiting + /// at that moment. Then the re-ask returns, the discovery finds no + /// services, and the connect goes into the zero-services retry. Here the + /// retry's fresh connection finds them. + #[tokio::test(start_paused = true)] + async fn a_discovery_that_bluez_ends_with_no_services_goes_into_the_retry() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.service_rounds([BTreeSet::new()]); + fake.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(17))]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the retry's connection should find the services"); + + // 15 s connect limit + 17 s into the wait (3 s inside it) + the + // retry's 2 s pause = 34 s. + assert_eq!(start.elapsed(), Duration::from_secs(34)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + Call::Disconnect, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } } #[cfg(test)] @@ -2531,4 +2759,39 @@ mod pairing_tests { }) .await; } + + /// Pairing, then the usual slow first connect on BlueZ: the pairing step + /// uses its whole 35 s budget, the connect after it runs out of its 15 s + /// with the link up, and BlueZ resolves the services 10 s into the wait. + /// The connect's limit and the wait start only when the pairing step has + /// returned. + #[tokio::test(start_paused = true)] + async fn pairing_then_a_discovery_that_outlasts_the_connect_limit_connects() { + within(Duration::from_secs(600), async { + let link = FakeGatt::new(); + link.set_bluez(true); + link.script_pair([Outcome::After(DEFAULT_BUDGET)]); + link.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(10))]); + let start = Instant::now(); + + connect_with(&link, &ConnectionConfig::default()) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // 35 s of pairing + 15 s connect limit + 10 s into the wait + // = 60 s. + assert_eq!(start.elapsed(), Duration::from_secs(60)); + assert_eq!( + link.calls(), + [ + Call::Pair(DEFAULT_BUDGET), + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } } diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index 629b036..c8b3601 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -31,6 +31,12 @@ pub(super) enum Outcome { /// to the same device is still pending (`org.bluez.Error.InProgress`), /// with `btleplug::Error::Other("In Progress")`. InProgress, + /// Fail as bluez-async's `connect` does when BlueZ sends no reply to + /// `Device1.Connect` within the D-Bus call's own limit: after + /// `BLUEZ_DBUS_TIMEOUT`, with + /// `btleplug::Error::Other("Timeout waiting for reply")`. A caller whose + /// own limit is shorter never sees it. + DbusTimeout, /// Wait this long on the tokio clock, then succeed like `Ok`. A /// `disconnect` that ends this way notifies `disconnected()` at the end /// of the wait. @@ -52,6 +58,11 @@ pub(super) enum Outcome { /// happen. Under a shorter limit the fake keeps the real order. pub(super) const BLUEZ_ASYNC_WAIT: std::time::Duration = std::time::Duration::from_secs(30); +/// How long bluez-async waits for BlueZ's reply to a D-Bus method call, such +/// as the `Device1.Connect` that its `connect` starts with, before the call +/// fails (`DBUS_METHOD_CALL_TIMEOUT`, bluez-async 0.9.0 `src/lib.rs:57`). +pub(super) const BLUEZ_DBUS_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); + /// A call made on a `FakeGatt`, in the order it was made. #[derive(Debug, Clone, PartialEq, Eq)] pub(super) enum Call { @@ -264,6 +275,13 @@ async fn run(outcome: Option) -> btleplug::Result<()> { // bluez-async's `BluetoothError::DbusError`, whose text is the D-Bus // error's message, wrapped in `Error::Other` by btleplug. Outcome::InProgress => Err(btleplug::Error::Other("In Progress".into())), + Outcome::DbusTimeout => { + tokio::time::sleep(BLUEZ_DBUS_TIMEOUT).await; + // The same kind of error: the D-Bus call ran out of time, and + // this is the message it fails with (dbus 0.9.12 + // `src/nonblock.rs:512`). + Err(btleplug::Error::Other("Timeout waiting for reply".into())) + } Outcome::After(delay) => { tokio::time::sleep(delay).await; Ok(()) From b7142e430a9644ca6f9f930d573fcc7c0b01f8a2 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 19:58:25 -0400 Subject: [PATCH 06/21] docs: say in the Linux connect comments that bluez-async waits 30 s, not 5 s The comments on the BlueZ wait in `link.rs` and on its test double gave bluez-async's wait for `ServicesResolved` as 5 s, and cited bluez-async 0.8.2 and btleplug 0.11.8 by line. With btleplug 0.13.5 the wait is 30 s (bluez-async 0.9.0 `src/lib.rs:61`), and that turns around which limit ends a slow connect: under a `connection_timeout` of 30 s or less, the 15 s default included, aranet's own limit ends it first, and the library's "Service discovery timed out" needs a longer limit. The comments now say so, with the upstream lines of the new versions. The reason given for the 20 s minimum wait is rewritten around what BlueZ's discovery gets in all, 35 s less the time BlueZ takes to answer at the default limits; the value does not change. The docs of the wait also say what follows from one 30 s re-ask inside a 20 s wait: a link that drops during the wait is not reopened, and an `In Progress` from another client is asked again. The double's `Hang`, `DiscoveryTimedOut` and `After` say what each stands for now. btleplug's issue 496, about the 5 s wait, is cited where the wait is explained. Comments and rustdoc only: with comment lines left out, the three files are unchanged. The task gate is clean: the format check, clippy on stable, on 1.90 and for each feature of aranet-core, the crate's tests, the docs build, and clippy and the tests in the Linux container. --- crates/aranet-core/src/link.rs | 147 +++++++++++++++++++--------- crates/aranet-core/src/link/fake.rs | 24 +++-- crates/aranet-core/src/pairing.rs | 2 +- 3 files changed, 118 insertions(+), 55 deletions(-) diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index b77b85f..e53af8a 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -60,9 +60,11 @@ pub(crate) trait GattLink: Clone + Send + Sync + 'static { /// Whether the connection goes through BlueZ. There `connect` doesn't /// return when the link comes up: BlueZ answers `Device1.Connect` only /// once the ATT channel is up, a few seconds later, and bluez-async then - /// waits up to 5 s more for BlueZ to resolve the services. So a `connect` - /// can run out of time with the link already up and BlueZ still setting - /// up the ATT channel or discovering. + /// waits up to 30 s more for BlueZ to resolve the services (bluez-async + /// 0.9.0 `src/lib.rs:61`). So a `connect` can run out of time with the + /// link already up and BlueZ still setting up the ATT channel or + /// discovering. Under a limit of 30 s or less, such as the 15 s default, + /// that is how every connect ends whose discovery outlasts the limit. fn is_bluez(&self) -> bool; /// Enable notifications on `characteristic` (the CCCD write). @@ -441,14 +443,18 @@ pub(crate) async fn connect( /// On BlueZ, a connect (the first one or the retry's) can end while BlueZ is /// still discovering the services on the live link. BlueZ answers /// `Device1.Connect` only once the ATT channel is up, a few seconds after the -/// link, and bluez-async stops waiting for the services 5 s after that answer. -/// A link that comes up late can also use up `connection_timeout` first, while -/// BlueZ is still setting up the ATT channel or discovering; `connect_link` -/// then asks whether the link is up. Either way the discovery after it first -/// waits for BlueZ to finish (`wait_for_bluez_discovery`), and that -/// connection-state query, the wait and the discovery share one -/// `bluez_discovery_limit` (20 s at defaults), whose end fails the connect -/// with a "discover services" (or "rediscover services") timeout. +/// link, and bluez-async then waits 30 s for the services (bluez-async 0.9.0 +/// `src/lib.rs:61`). It waited 5 s before btleplug 0.13.5 +/// (). So under a +/// `connection_timeout` of 30 s or less, the 15 s default included, a connect +/// whose discovery is unfinished at that limit runs out of time first, and +/// `connect_link` then asks whether the link is up. bluez-async gives up +/// first ("Service discovery timed out") only under a longer limit. Either +/// way the discovery after it first waits for BlueZ to finish +/// (`wait_for_bluez_discovery`), and that connection-state query, the wait +/// and the discovery share one `bluez_discovery_limit` (20 s at defaults), +/// whose end fails the connect with a "discover services" (or "rediscover +/// services") timeout. /// /// `connect` disconnects the link when any step fails. async fn connect_and_discover( @@ -524,22 +530,38 @@ async fn connect_and_discover( } /// What bluez-async's `connect` fails with when BlueZ hasn't resolved the -/// services 5 s after `Device1.Connect` returned, although the link is up and -/// BlueZ is still discovering (`BluetoothError::ServiceDiscoveryTimedOut`, -/// bluez-async 0.8.2 `src/lib.rs:61`, `:90-92`, `:696-724`). btleplug passes -/// it on as `btleplug::Error::Other` (`src/bluez/adapter.rs:125-129`). No -/// other btleplug backend produces it. aranet-core can't name bluez-async's -/// type (it isn't a dependency), so this matches the message. +/// services 30 s after `Device1.Connect` returned, although the link is up +/// and BlueZ is still discovering (`BluetoothError::ServiceDiscoveryTimedOut`, +/// bluez-async 0.9.0 `src/lib.rs:61`, `:90-92`, `:699-727`). btleplug passes +/// it on as `btleplug::Error::Other` (btleplug 0.13.5 +/// `src/bluez/adapter.rs:182-186`). No other btleplug backend produces it. +/// aranet-core can't name bluez-async's type (it isn't a dependency), so this +/// matches the message. A connect gets it only under a `connection_timeout` +/// longer than those 30 s; a shorter limit ends the call first. const BLUEZ_DISCOVERY_TIMED_OUT: &str = "Service discovery timed out"; /// The least time a connect waits for BlueZ to finish discovering the services -/// once bluez-async has given up, or the connect has run out of time with the -/// link up (BR-25). An Aranet4 that BlueZ hasn't cached needs about 30-48 ATT +/// once the connect has run out of time with the link up, or bluez-async has +/// given up (BR-25). An Aranet4 that BlueZ hasn't cached needs about 30-48 ATT /// requests at 0.3-0.45 s each: 9-22 s from the moment BlueZ answers /// `Device1.Connect`, which on an LE link it does once the ATT channel is up, -/// a few seconds after the link. bluez-async has already waited 5 s of that -/// when it gives up. When the connect runs out of time with the link up, less -/// than 5 s of it has passed, or none if BlueZ hasn't answered yet. +/// a few seconds after the link. +/// +/// Counted from that answer, BlueZ's discovery gets +/// `min(a + 30 s, connection_timeout) + wait - a` in all, where `a` is the +/// time BlueZ took to answer and the 30 s are bluez-async's own wait for the +/// services (bluez-async 0.9.0 `src/lib.rs:61`). At the default limits that +/// is `15 s + 20 s - a`: 33 s when BlueZ answers after 2 s, and little more +/// than this wait alone when it answers just before the connect's limit. If +/// BlueZ hasn't answered by then, the wait also has to cover the rest of the +/// ATT set-up. When bluez-async gives up first, which needs a +/// `connection_timeout` above 30 s, the discovery has already had 30 s. +/// +/// bluez-async waited only 5 s until btleplug 0.13.5 moved to bluez-async +/// 0.9.0 (), and this wait +/// was added to make up for that. It is still needed: a connect whose limit +/// is 30 s or less ends before bluez-async's wait does, and without this wait +/// it would fail and disconnect in the middle of BlueZ's discovery. pub(crate) const BLUEZ_DISCOVERY_MIN_WAIT: Duration = Duration::from_secs(20); /// How long a connect waits for BlueZ to finish discovering the services once @@ -577,10 +599,13 @@ fn is_bluez_in_progress(error: &btleplug::Error) -> bool { #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum BluezWaitReason { /// bluez-async's `connect` gave up waiting for the services, so BlueZ has - /// answered `Device1.Connect`. + /// answered `Device1.Connect`. bluez-async waits 30 s (bluez-async 0.9.0 + /// `src/lib.rs:61`), so this needs a `connection_timeout` above 30 s. DiscoveryTimedOut, - /// The connect ran out of time with the link up. BlueZ may not have - /// answered that `Device1.Connect` yet. + /// The connect ran out of time with the link up. Under a + /// `connection_timeout` of 30 s or less this is the reason for every + /// wait. BlueZ has usually answered that `Device1.Connect` by then, but + /// it may not have answered yet. ConnectTimedOut, } @@ -638,10 +663,12 @@ async fn connect_link( } // BlueZ answers `Device1.Connect` only once the ATT channel is up, a // few seconds after the link, and bluez-async's `connect` then waits - // up to 5 s more for the services. So a link that comes up late in - // `connection_timeout` runs out of time here while BlueZ is still - // setting up the ATT channel or discovering on it. Disconnecting - // would cancel that, and every retry would start it again. + // up to 30 s more for the services (bluez-async 0.9.0 + // `src/lib.rs:61`). So under a `connection_timeout` of 30 s or less, + // every connect whose discovery is unfinished at the limit runs out + // of time here, with BlueZ still setting up the ATT channel or + // discovering on the link. Disconnecting would cancel that, and + // every retry would start it again. Err(timeout @ Error::Timeout { .. }) if link.is_bluez() => { // The query counts against the wait's limit, so the connect still // takes at most `connection_timeout`, and the query and the wait @@ -699,17 +726,29 @@ async fn discover( /// /// Once BlueZ has answered the connect that started the wait, it answers /// `Device1.Connect` at once while the device is connected (`src/device.c`, -/// `dev_connect`), and bluez-async then waits up to 5 s more for -/// `ServicesResolved`, or returns at once if it is already set. If the link -/// has dropped, `Device1.Connect` opens a new one, as the caller's own retry -/// would. +/// `dev_connect`), and bluez-async then waits up to 30 s more for +/// `ServicesResolved` (bluez-async 0.9.0 `src/lib.rs:61`), or returns at once +/// if it is already set. Those 30 s are longer than the default 20 s wait, so +/// at the default limits the wait makes one such call: BlueZ finishes during +/// it, or the caller's deadline ends it. Another call after a "Service +/// discovery timed out" needs a `discovery_timeout` above 30 s. +/// +/// If the link has dropped, a `Device1.Connect` made after the drop opens a +/// new one, as the caller's own retry would. A call that is already waiting +/// for the services does not notice a drop (bluez-async 0.9.0 +/// `src/lib.rs:711-726`), so at the default limits a link that drops during +/// the wait is not reopened. /// /// After a connect timeout (`BluezWaitReason::ConnectTimedOut`), BlueZ may not /// have answered the timed-out `Device1.Connect` yet, and until it does it /// refuses the next one with `In Progress`. Then the wait asks again after -/// `BLUEZ_IN_PROGRESS_PAUSE`. After bluez-async's discovery timeout BlueZ has -/// answered, so an `In Progress` there comes from another connect to the -/// device or a pairing of it, and ends the wait. +/// `BLUEZ_IN_PROGRESS_PAUSE`. Under a `connection_timeout` of 30 s or less +/// every wait starts this way, so there an `In Progress` that comes from +/// another connect to the device or a pairing of it is asked again as well, +/// until the caller's deadline. After bluez-async's discovery timeout, which +/// needs a longer `connection_timeout`, BlueZ has answered, so an +/// `In Progress` there comes from another connect to the device or a pairing +/// of it, and ends the wait. /// /// Any other result ends the wait. The caller limits it. async fn wait_for_bluez_discovery( @@ -1648,14 +1687,23 @@ mod tests { } } -/// BR-25: bluez-async's `connect` gives BlueZ 5 s to resolve the services +/// BR-25: bluez-async's `connect` gives BlueZ 30 s to resolve the services /// after BlueZ answers `Device1.Connect`, which on an LE link it does once the -/// ATT channel is up, a few seconds after the link. A sensor with a large GATT -/// table and a slow link, such as an Aranet4 that BlueZ hasn't cached yet, -/// needs longer, and BlueZ keeps discovering on the live link after -/// bluez-async has given up. When the link itself is slow to come up, the -/// connect's own time limit can run out first, again with the link up and -/// BlueZ still setting up the ATT channel or discovering on it. +/// ATT channel is up, a few seconds after the link (bluez-async 0.9.0 +/// `src/lib.rs:61`). It gave 5 s before btleplug 0.13.5 +/// (). A connect's own +/// time limit is 15 s by default, so when a sensor with a large GATT table +/// and a slow link, such as an Aranet4 that BlueZ hasn't cached yet, needs +/// longer than that, the connect's limit runs out first, with the link up +/// and BlueZ still setting up the ATT channel or discovering on it. The +/// connect then waits for BlueZ by asking it to connect again. bluez-async +/// gives up before the connect's limit only when that limit is longer than +/// its 30 s; the tests of that path set such a limit (`LONG_CONNECT_LIMIT`, +/// or `ConnectionConfig::challenging_environment()`). Either way BlueZ keeps +/// discovering on the live link. +/// +/// The fake's `fake::BLUEZ_ASYNC_WAIT` models bluez-async's wait, and its +/// doc says how a first connect must be scripted. #[cfg(test)] mod bluez_discovery_tests { use std::collections::BTreeSet; @@ -1671,7 +1719,8 @@ mod bluez_discovery_tests { use crate::error::{Error, Result}; use crate::test_support::within; - /// The least time a connect waits for BlueZ once bluez-async has given up + /// The least time a connect waits for BlueZ once the connect has run out + /// of time with the link up, or bluez-async has given up /// (`BLUEZ_DISCOVERY_MIN_WAIT`). const MIN_WAIT: Duration = Duration::from_secs(20); @@ -2646,8 +2695,9 @@ mod pairing_tests { /// `Duration::MAX` is how a caller says "no limit". A connect must not /// panic on it: not when the pairing budget adds two of them, and not on /// BlueZ when the wait for BlueZ's service discovery starts with a - /// deadline `discovery_timeout` away, after bluez-async gave up waiting - /// for the services or after a connect timeout. + /// deadline `discovery_timeout` away. The wait starts after bluez-async + /// gave up waiting for the services, which a connect without a limit + /// lets it do after its 30 s, or after a finite connect limit ran out. #[tokio::test(start_paused = true)] async fn connect_with_unlimited_timeouts_does_not_panic() { within(Duration::from_secs(600), async { @@ -2665,8 +2715,9 @@ mod pairing_tests { [Call::Pair(Duration::MAX), Call::Connect, Call::Discover] ); - // On BlueZ, bluez-async gives up waiting for the services, so the - // connect waits for BlueZ to finish. + // On BlueZ, a connect without a limit lasts until bluez-async + // gives up waiting for the services, 30 s in (the fake's + // `BLUEZ_ASYNC_WAIT`), so the connect waits for BlueZ to finish. let bluez = FakeGatt::new(); bluez.set_bluez(true); bluez.script_pair([Outcome::Ok]); diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index c8b3601..8a2eaa6 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -20,12 +20,21 @@ pub(super) enum Outcome { /// Fail at once with a Bluetooth error, as a refused connection or a /// failed discovery does. Fail, - /// Never answer, as btleplug does on macOS once CoreBluetooth has dropped - /// the peripheral. + /// Never answer. It stands for two things. One is a BlueZ `connect` that + /// is still waiting when aranet's own limit ends: bluez-async waits up to + /// 30 s for BlueZ's reply to `Device1.Connect` and then 30 s for the + /// services (bluez-async 0.9.0 `src/lib.rs:57`, `:61`), so under the 15 s + /// default limit this is how a slow first connect is scripted. The other + /// is a call that the stack never answers, such as a CoreBluetooth + /// connect to a sensor that has gone. Hang, /// Fail as bluez-async's `connect` does while BlueZ is still discovering /// the services of a connected device: after `BLUEZ_ASYNC_WAIT`, with - /// `btleplug::Error::Other("Service discovery timed out")`. + /// `btleplug::Error::Other("Service discovery timed out")`. The wait + /// starts at the call, as if BlueZ answered `Device1.Connect` at once, + /// which it does when a wait asks again on a live link. The caller sees + /// this outcome only if its own limit is longer than `BLUEZ_ASYNC_WAIT`; + /// that constant's doc says how to script a first connect. DiscoveryTimedOut, /// Fail at once as BlueZ refuses a `Device1.Connect` while an earlier one /// to the same device is still pending (`org.bluez.Error.InProgress`), @@ -39,7 +48,10 @@ pub(super) enum Outcome { DbusTimeout, /// Wait this long on the tokio clock, then succeed like `Ok`. A /// `disconnect` that ends this way notifies `disconnected()` at the end - /// of the wait. + /// of the wait. As a BlueZ `connect` it stands for BlueZ resolving the + /// services that long after the call: bluez-async's `connect` can succeed + /// up to `BLUEZ_ASYNC_WAIT` after BlueZ's answer, which for a re-ask on a + /// live link comes at once. After(std::time::Duration), } @@ -268,8 +280,8 @@ async fn run(outcome: Option) -> btleplug::Result<()> { Outcome::DiscoveryTimedOut => { tokio::time::sleep(BLUEZ_ASYNC_WAIT).await; // bluez-async's `BluetoothError::ServiceDiscoveryTimedOut` - // (`src/lib.rs:90-92`), which btleplug wraps in `Error::Other` - // (`src/bluez/adapter.rs:125-129`). + // (bluez-async 0.9.0 `src/lib.rs:90-92`), which btleplug wraps in + // `Error::Other` (btleplug 0.13.5 `src/bluez/adapter.rs:182-186`). Err(btleplug::Error::Other("Service discovery timed out".into())) } // bluez-async's `BluetoothError::DbusError`, whose text is the D-Bus diff --git a/crates/aranet-core/src/pairing.rs b/crates/aranet-core/src/pairing.rs index 2755eab..ceca9ca 100644 --- a/crates/aranet-core/src/pairing.rs +++ b/crates/aranet-core/src/pairing.rs @@ -53,7 +53,7 @@ //! battery plugin reads the Battery Level, which needs encryption) and finds //! no agent on a headless host, so after a timeout or a lost link the next //! connect pairs again. -//! - btleplug 0.11.8 has no pairing call. +//! - btleplug 0.13.5 has no pairing call. use std::collections::HashMap; use std::fmt; From ec9a3a6311e0be1fb362cfdbd1c836640097c9d0 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 20:11:24 -0400 Subject: [PATCH 07/21] test: pin what the zero-services retry does when its reconnect is refused On macOS with btleplug 0.13.5 a service discovery can succeed with no services. 0.11.8 could not report that: its connect never returned then. aranet's retry for an empty discovery disconnects, waits 2 s and connects again on the same handle. The disconnect makes btleplug's CoreBluetooth backend forget the peripheral, so 0.13.5 refuses that reconnect at once with "Peripheral no longer available" (src/corebluetooth/internal.rs:1300-1304). The new test scripts that sequence on the test double: a connect that succeeds, one empty discovery, then a connect that fails at once. It expects the Bluetooth error 2 s after the start and the calls connect, discover, disconnect, connect, disconnect. Until now only a reconnect that never answers was covered. No production code changes, and the test passed as soon as it was written. With the pause in `connect_and_discover` set to 3 s it fails on the elapsed time (left: 3s, right: 2s); that edit was undone. --- crates/aranet-core/src/link.rs | 36 ++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index e53af8a..a5c6722 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -1092,6 +1092,42 @@ mod tests { .await; } + /// A reconnect that is refused at once during the zero-services retry + /// fails the connect with that Bluetooth error as soon as the retry's 2 s + /// pause is over, and disconnects before the error returns. This is what + /// the retry meets on macOS with btleplug 0.13.5: the disconnect before + /// the pause makes btleplug forget the peripheral, and a connect on the + /// same handle then fails at once with "Peripheral no longer available" + /// (`src/corebluetooth/internal.rs:1300-1304`). The test pins what the + /// caller gets in that case. It adds no code path: the retry is the one + /// that `failed_reconnect_during_retry_disconnects` covers for a + /// reconnect that never answers, and it is unchanged. + #[tokio::test(start_paused = true)] + async fn reconnect_refused_during_retry_fails_after_the_pause() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.service_rounds([BTreeSet::new()]); + fake.script_connect([Outcome::Ok, Outcome::Fail]); + let start = Instant::now(); + + let error = failed_connect(&fake).await; + + assert!(matches!(error, Error::Bluetooth(_)), "got {error:?}"); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::Discover, + Call::Disconnect, + Call::Connect, + Call::Disconnect, + ] + ); + assert_eq!(start.elapsed(), Duration::from_secs(2)); + }) + .await; + } + /// The rediscovery of the zero-services retry is limited by /// `discovery_timeout`, and running out is reported as "rediscover /// services". From 24e3e010ca7e5abdae7b4328c04960669dffd046 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 20:14:14 -0400 Subject: [PATCH 08/21] docs: describe the CoreBluetooth backend as btleplug 0.13.5 implements it Comments and rustdoc in aranet-core still described btleplug 0.11.8 on macOS, where a call on a peripheral the backend had forgotten was never answered and `connect()` included the service discovery. Only comments change; no code, constant or test does. - `GattLink::is_connected`, `Device::is_connected`, the hardware tests and the lifecycle soak: 0.13.5 answers "not connected" at once for a forgotten peripheral, and the time limits stay as guards. - `connect_and_discover`: on macOS the zero-services retry can now be reached, by an empty discovery or by a "services changed" callback during one, and its reconnect on the same handle is refused at once. - `CLOSES_TIME_OUT_AFTER_DROP`: what the constant does, that 0.13.5 answers the disconnect it was written for, the one case its source does not settle, and the state of the hardware check of that case. The link to issue 494 is gone: that issue is about memory. The value is unchanged. - `DeviceManager`: a close can fail by running out of time. The macOS example given for it was no longer true. - `ConnectionConfig::discovery_timeout`: it now limits the service discovery on macOS. - `scan.rs`: the adapter-thread check loses its example of a panic that 0.13.5 no longer has. The search filter's comment says which of its reasons still holds: every scanned device is still kept, the growth per advertisement is fixed by source and not yet measured, and its figures are from 0.11.8. Each statement about 0.13.5 was read from its source and names the file and line. A diff check shows that every changed line is a comment line, and the docs build with `-D warnings` passes. --- crates/aranet-core/examples/lifecycle_soak.rs | 6 ++- crates/aranet-core/src/connector.rs | 42 +++++++++++---- crates/aranet-core/src/device.rs | 16 +++++- crates/aranet-core/src/link.rs | 35 +++++++++++-- crates/aranet-core/src/manager.rs | 14 ++--- crates/aranet-core/src/scan.rs | 52 +++++++++++++------ crates/aranet-core/tests/hardware_tests.rs | 4 +- 7 files changed, 125 insertions(+), 44 deletions(-) diff --git a/crates/aranet-core/examples/lifecycle_soak.rs b/crates/aranet-core/examples/lifecycle_soak.rs index e6bd152..13b7b35 100644 --- a/crates/aranet-core/examples/lifecycle_soak.rs +++ b/crates/aranet-core/examples/lifecycle_soak.rs @@ -643,8 +643,10 @@ impl Snapshot { /// connected, each with the identifier it matched. A sensor that the adapter /// doesn't list, or whose query doesn't answer within 2 s, counts as not /// connected: on macOS a disconnect removes the peripheral from the adapter's -/// list until a scan finds it again, and a handle kept from before the -/// disconnect gets no answer. `Err` means the adapter couldn't list its +/// list until a scan finds it again, and until then a handle kept from before +/// the disconnect is answered "not connected" at once (btleplug 0.13.5 +/// `src/corebluetooth/internal.rs:1318-1332`; 0.11.8 gave it no answer). The +/// 2 s limit is a guard. `Err` means the adapter couldn't list its /// peripherals. async fn connected_peripherals(ids: &[String]) -> Result, String> { let adapter = get_adapter() diff --git a/crates/aranet-core/src/connector.rs b/crates/aranet-core/src/connector.rs index 22c0168..c0328e7 100644 --- a/crates/aranet-core/src/connector.rs +++ b/crates/aranet-core/src/connector.rs @@ -62,17 +62,39 @@ pub(crate) async fn release_link( .map_err(std::io::Error::from)? } -/// Whether closing a link that has already dropped on its own times out on -/// this platform. Where it does, a close that times out usually means only -/// that the link had dropped, not that the sensor is still connected. True -/// only on macOS: once CoreBluetooth reports a link down, btleplug's -/// CoreBluetooth backend forgets the peripheral and never answers a disconnect -/// for it, so the close runs into its time limit. Links to unpaired sensors -/// can drop on their own there a few minutes after they come up. +/// Whether a close that times out counts as expected on this platform. It +/// only sets the log level of a failed `release_link` in +/// `log_failed_release`, which `ReconnectingDevice` and `DeviceManager` +/// call: debug where this is true and the close timed out, a warning in +/// every other case. True only on macOS. /// -/// Workaround for btleplug 0.11.8 -/// (); re-check when -/// upgrading btleplug. +/// It was written for btleplug 0.11.8. Once CoreBluetooth reports a link +/// down, btleplug's CoreBluetooth backend forgets the peripheral, and 0.11.8 +/// never answered a disconnect for a peripheral it had forgotten. So closing +/// a link that had already dropped on its own always ran into its time +/// limit, and a close that timed out usually meant only that the link had +/// dropped, not that the sensor was still connected. With 0.11.8, links to +/// unpaired sensors were seen to drop on their own on macOS a few minutes +/// after they came up. +/// +/// btleplug 0.13.5 still forgets the peripheral +/// (`src/corebluetooth/internal.rs:1156-1181`), but it answers that +/// disconnect with `Ok` at once for as long as it has no entry for the +/// sensor (`src/corebluetooth/internal.rs:1307-1316`). By its source, +/// closing a link that has dropped on its own therefore no longer times +/// out. The source can't settle one case: a scan finds the sensor again +/// before the old handle is closed. btleplug then has a new entry for the +/// sensor, and the close asks CoreBluetooth to cancel that entry's +/// connection and waits for the disconnect callback +/// (`src/corebluetooth/internal.rs:1309-1312`). Whether CoreBluetooth sends +/// that callback for a peripheral that isn't connected is not in btleplug's +/// source. +/// +/// Hardware check H2 of the btleplug 0.13.5 upgrade (2026-10-11, on macOS: a +/// sensor whose link had ended and that a scan had found again) saw the +/// close through the old handle get no answer before its time limit. So the +/// classifier still has one real case: a close of a dropped link after a +/// scan has found the sensor again. const CLOSES_TIME_OUT_AFTER_DROP: bool = cfg!(target_os = "macos"); /// Whether `error`, from a failed `release_link`, is expected and so no sign diff --git a/crates/aranet-core/src/device.rs b/crates/aranet-core/src/device.rs index b3e8a54..7cc8d95 100644 --- a/crates/aranet-core/src/device.rs +++ b/crates/aranet-core/src/device.rs @@ -198,6 +198,16 @@ pub struct ConnectionConfig { pub write_timeout: Duration, /// Timeout for service discovery after connection. /// + /// On macOS this limits the service discovery itself. With btleplug + /// 0.13.5 a connect ends when the link is up + /// (`src/corebluetooth/peripheral.rs:433-456`) and the services are + /// discovered in a step of their own (`:479-500`), so the link has + /// `connection_timeout` to come up and the discovery has this limit. A + /// discovery that takes longer fails the connect with a "discover + /// services" timeout. With btleplug 0.11.8 the discovery ran inside the + /// connect, under `connection_timeout`, and this limit had no effect on + /// macOS. + /// /// On Linux, when BlueZ is still discovering the services of a device it /// has just connected (a first connection to a sensor with many /// characteristics, such as an Aranet4), a connect waits for BlueZ to @@ -638,8 +648,10 @@ impl Device { /// /// Returns `false` if the Bluetooth stack reports an error or doesn't answer /// within the connection's `validation_timeout` (3 s by default, set with - /// [`ConnectionConfig::validation_timeout`]). On macOS the stack stops - /// answering once the sensor has dropped the connection. + /// [`ConnectionConfig::validation_timeout`]). On macOS the limit is only a + /// guard: once the sensor has dropped the connection, btleplug 0.13.5 + /// answers `false` at once (`src/corebluetooth/internal.rs:1318-1332`), + /// where 0.11.8 gave no answer. /// /// Note: This only checks the BLE stack's connection state, which may be stale, /// especially on macOS. For a more reliable check, use [`Self::validate_connection`]. diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index a5c6722..ec83245 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -52,9 +52,12 @@ pub(crate) trait GattLink: Clone + Send + Sync + 'static { &self, ) -> impl Future>> + Send; - /// Whether the Bluetooth stack reports the link as up. On macOS nobody - /// answers this once CoreBluetooth has dropped the peripheral, so callers - /// use this module's time-limited `is_connected` function instead. + /// Whether the Bluetooth stack reports the link as up. Callers use this + /// module's time-limited `is_connected` function instead, as a guard + /// against a stack that doesn't answer. On macOS, btleplug 0.11.8 gave no + /// answer once its CoreBluetooth backend had forgotten the peripheral; + /// 0.13.5 answers "not connected" at once + /// (`src/corebluetooth/internal.rs:1318-1332`). fn is_connected(&self) -> impl Future> + Send; /// Whether the connection goes through BlueZ. There `connect` doesn't @@ -438,6 +441,12 @@ pub(crate) async fn connect( /// and discover once more ("reconnect to device", "rediscover services"). /// If that discovery finds none either, fail with a retryable /// `Error::ConnectionFailed` ("the device reported no GATT services"). +/// On macOS the retry doesn't help: the disconnect makes btleplug 0.13.5 +/// forget the peripheral, so the reconnect on the same handle fails at +/// once with a retryable `Error::Bluetooth` ("Peripheral no longer +/// available", `src/corebluetooth/internal.rs:1300-1304`), unless a scan +/// has found the sensor again during the pause. A caller that retries +/// then searches for the sensor again. /// 5. Read the properties, giving up after `read_timeout`. /// /// On BlueZ, a connect (the first one or the retry's) can end while BlueZ is @@ -494,6 +503,19 @@ async fn connect_and_discover( // If service discovery returned nothing, BlueZ may have stale state // from a previous failed connection (e.g., auth failure during GATT // discovery). Disconnect, wait, and retry once with a clean connection. + // + // On macOS, btleplug 0.11.8 never returned an empty set: its connect + // didn't return when the discovery found no services. btleplug 0.13.5 + // does, in two ways. A discovery that CoreBluetooth ends with no error + // and no services succeeds with none + // (`src/corebluetooth/internal.rs:364-365`), and a "services changed" + // callback during a discovery can end it with only the services that + // are left, which may be none (`:968-985`). The retry doesn't help + // there: the disconnect makes btleplug forget the peripheral (`:1175`), + // so the reconnect on this handle fails at once with "Peripheral no + // longer available" (`:1300-1304`), unless a scan has found the sensor + // again during the pause. That error is retryable, and a caller that + // retries searches for the sensor again. if services.is_empty() { warn!("Service discovery returned 0 services — retrying with fresh connection"); if let Err(e) = disconnect(link).await { @@ -1272,8 +1294,11 @@ mod tests { .await; } - /// A connection-state query that the stack never answers (CoreBluetooth - /// after the sensor has gone) reports `false` after `validation_timeout`. + /// A connection-state query that the stack never answers reports `false` + /// after `validation_timeout`. The limit is a guard against a stack that + /// has stopped answering. btleplug 0.11.8 gave no answer on macOS once it + /// had forgotten the peripheral; 0.13.5 answers "not connected" at once + /// there (`src/corebluetooth/internal.rs:1318-1332`). #[tokio::test(start_paused = true)] async fn is_connected_reports_false_when_the_stack_never_answers() { within(Duration::from_secs(600), async { diff --git a/crates/aranet-core/src/manager.rs b/crates/aranet-core/src/manager.rs index c5057e7..48e5279 100644 --- a/crates/aranet-core/src/manager.rs +++ b/crates/aranet-core/src/manager.rs @@ -883,9 +883,9 @@ impl ManagerCore { }; // The link has left the manager: say so before the close, as `detach` - // does. The close can fail (on macOS, closing a link that dropped on - // its own times out) or go on in the background if this future is - // dropped, and nothing would send the event later. + // does. The close can fail (it gives up when the Bluetooth stack + // doesn't confirm the disconnect in time) or go on in the background + // if this future is dropped, and nothing would send the event later. self.events.send(DeviceEvent::Disconnected { device: DeviceId::new(identifier), reason: DisconnectReason::UserRequested, @@ -2696,10 +2696,10 @@ mod lifecycle_tests { } /// A disconnect sends `Disconnected` once it has taken the link out of - /// the manager, even if closing the link then fails (as closing a link - /// that dropped on its own does on macOS): the manager reports the device - /// as disconnected from then on, and nothing sends the event later. The - /// error is still returned. + /// the manager, even if closing the link then fails (as it does when the + /// Bluetooth stack doesn't confirm the disconnect in time): the manager + /// reports the device as disconnected from then on, and nothing sends + /// the event later. The error is still returned. #[tokio::test(start_paused = true)] async fn disconnects_send_disconnected_even_if_the_close_fails() { within(TEST_LIMIT, async { diff --git a/crates/aranet-core/src/scan.rs b/crates/aranet-core/src/scan.rs index b426145..1bc3f59 100644 --- a/crates/aranet-core/src/scan.rs +++ b/crates/aranet-core/src/scan.rs @@ -241,11 +241,16 @@ async fn cached_adapter() -> Result { /// Whether the cached adapter's CoreBluetooth thread still takes requests. /// -/// btleplug's CoreBluetooth thread can panic (for example when services are -/// discovered after a connect has timed out). Every later request on that -/// adapter then fails with "Channel closed", so it has to be replaced. A reply -/// that is merely slow keeps the adapter: only a closed channel proves the -/// thread is gone. +/// btleplug's CoreBluetooth thread runs a loop that never returns (btleplug +/// 0.13.5 `src/corebluetooth/internal.rs:2030-2038`), so it stops only if it +/// panics. btleplug 0.11.8 panicked on a discovery callback that came late, +/// for a service it no longer knew or with no connect waiting; 0.13.5 +/// ignores those (`:397-400`, `:534-538`). This check stays as a guard +/// against any other panic: every later request on an adapter whose thread +/// has stopped fails with "Channel closed" +/// (`src/corebluetooth/peripheral.rs:678-682`), so the adapter has to be +/// replaced. A reply that is merely slow keeps the adapter: only a closed +/// channel proves the thread is gone. async fn adapter_thread_is_running(adapter: &Adapter) -> bool { let adapter = adapter.clone(); // Run on aranet-core's runtime so the timeout works even if the caller's @@ -606,24 +611,37 @@ fn aranet_service_filter() -> ScanFilter { /// Whether every scan window of a device search asks the Bluetooth stack only for /// devices that advertise an Aranet service (see `search_filter`). Only on macOS: -/// btleplug's CoreBluetooth backend keeps every device a scan reports for the -/// rest of the process and leaks a little memory for every advertisement it -/// receives, so unfiltered searches near many Bluetooth devices make a -/// long-running program grow by 1-2 MB an hour. Leaving only a search's last -/// window unfiltered wasn't enough: in a 12 h macOS soak, the 8.5% of the -/// service's polls whose search reached that window added about 106 kB each -/// (about 80% of the growth, against about 2 kB for a search that ended -/// earlier), and a sensor out of range runs it on every poll, about 6 MB an hour. +/// btleplug's CoreBluetooth backend keeps every device a scan reports (its +/// `CBPeripheral`, an entry in the adapter's list and a task of its own) until +/// the device disconnects after a connection, Bluetooth is switched off or +/// `clear_peripherals()` is called (btleplug 0.13.5 +/// `src/corebluetooth/internal.rs:1010-1013`; removed at `:1175`, `:1153` and +/// `:1924`). aranet never calls `clear_peripherals()` and shares one adapter for +/// the life of the process, so a device that is only scanned stays until +/// Bluetooth is switched off or the process ends. With the filter, a device +/// search adds only Aranet sensors to that list. +/// +/// The filter was added on btleplug 0.11.8, which also leaked a little memory +/// for every advertisement it received, and the figures here were measured on +/// it. Unfiltered searches near many Bluetooth devices made a long-running +/// program grow by 1-2 MB an hour. Leaving only a search's last window +/// unfiltered wasn't enough: in a 12 h macOS soak, the 8.5% of the service's +/// polls whose search reached that window added about 106 kB each (about 80% of +/// the growth, against about 2 kB for a search that ended earlier), and a +/// sensor out of range ran it on every poll, about 6 MB an hour. +/// +/// btleplug 0.13.5 drains an autorelease pool for every message on its +/// CoreBluetooth thread (`src/corebluetooth/internal.rs:1990-2014`, +/// `:2034-2036`), which by its source ends the growth per advertisement +/// (). That has not been +/// measured, and the list of kept devices is as it was, so the filter stays +/// unchanged until a memory measurement on 0.13.5 says otherwise. /// /// The cost: a macOS search doesn't find a sensor that advertises neither Aranet /// service UUID. All four current Aranet sensor types advertise 0xFCE0; older /// firmware is untested. `aranet scan`, `scan_with_options` and the passive /// monitor still see every device. Linux and Windows searches ask for every /// device. -/// -/// Workaround for btleplug 0.11.8 -/// (); re-check when -/// upgrading btleplug. const FILTER_SEARCH_WINDOWS: bool = cfg!(target_os = "macos"); /// The scan filter of every window of a device search: with `aranet_only`, it diff --git a/crates/aranet-core/tests/hardware_tests.rs b/crates/aranet-core/tests/hardware_tests.rs index 5d7ca85..a49b462 100644 --- a/crates/aranet-core/tests/hardware_tests.rs +++ b/crates/aranet-core/tests/hardware_tests.rs @@ -1491,7 +1491,9 @@ async fn find_peripheral(device: &str) -> btleplug::platform::Peripheral { /// Whether the Bluetooth stack reports `device` as connected. `false` when the /// adapter doesn't know it (see `known_peripheral`) or doesn't answer within -/// 5 s: btleplug never answers for a peripheral that CoreBluetooth has dropped. +/// 5 s. The limit is a guard: btleplug 0.13.5 answers "not connected" at once +/// for a peripheral that its CoreBluetooth backend has forgotten +/// (`src/corebluetooth/internal.rs:1318-1332`), where 0.11.8 gave no answer. async fn peripheral_connected(device: &str) -> bool { let Some(p) = known_peripheral(device).await else { return false; From 3c8e075c6a06bc9d0043334620293d99f2066370 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 20:34:08 -0400 Subject: [PATCH 09/21] fix: hide the error line btleplug 0.13.5 logs after every successful disconnect on macOS On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level for every disconnect that CoreBluetooth confirms, and then returns Ok (src/corebluetooth/peripheral.rs:468-476): the disconnect's own reply is answered with "Device disconnected", like every other pending operation (src/corebluetooth/internal.rs:678-698). 0.11.8 had the same statement and never reached it. A hardware run on the commit that only moves to 0.13.5 showed the line. Every `aranet` command that connects ends with a disconnect, and the service disconnects after every poll. So each successful `aranet read` would print an error on stderr, `--quiet` included, and the service would log one per poll per device. The directive `btleplug::corebluetooth::peripheral=off` joins three default filters: - the CLI's default and `--quiet`. `-v` and a `RUST_LOG` of the user's own are used as before and still show the line; - the GUI's default, which stays at errors only. `fmt::init()` becomes the same filter written out, so that the directive can be added when `RUST_LOG` is unset or empty; - the service's `DEFAULT_LOG_DIRECTIVES`. There a default directive replaces a `RUST_LOG` directive for the same target, so no `RUST_LOG` directive for that target, or for a shorter one such as `btleplug=trace`, can show the module's lines. The line is that module's only warning or error, and the target is not widened: btleplug's warnings about Bluetooth being off, a missing permission and a failed characteristic discovery come from other modules and stay visible. A program that uses aranet-core with its own logger still gets the line. Each site says when the directive goes: with the btleplug release that no longer logs the line. The CLI and the GUI take their default from one function, `log_filter::default_directives`. Its file is a module of the library, for the GUI, and of the `aranet` binary, for the CLI, because the binary cannot call a private function of the library and the filter is not public API. New tests log one line per btleplug module under each filter and compare what is shown: the default shows what its level shows minus that one line, `--quiet` equals the default, `-v` and `RUST_LOG` are untouched, and the service drops the line under four `RUST_LOG` values. Each test of a changed filter failed before its change. Eight hand-made mutants (the target widened to `btleplug`, `=off` as `=error`, the directive dropped from a site or added to `-v`, the GUI's condition inverted) each fail a test. --- crates/aranet-cli/src/gui/mod.rs | 71 +++++++++++- crates/aranet-cli/src/lib.rs | 5 + crates/aranet-cli/src/log_filter.rs | 171 ++++++++++++++++++++++++++++ crates/aranet-cli/src/main.rs | 92 +++++++++++++-- crates/aranet-service/src/lib.rs | 70 +++++++++++- 5 files changed, 399 insertions(+), 10 deletions(-) create mode 100644 crates/aranet-cli/src/log_filter.rs diff --git a/crates/aranet-cli/src/gui/mod.rs b/crates/aranet-cli/src/gui/mod.rs index 273f1f3..906f3cf 100644 --- a/crates/aranet-cli/src/gui/mod.rs +++ b/crates/aranet-cli/src/gui/mod.rs @@ -36,6 +36,7 @@ use aranet_store::default_db_path; use eframe::egui::{self, IconData}; use tokio::sync::mpsc; use tracing::{debug, info, warn}; +use tracing_subscriber::EnvFilter; use aranet_core::messages::{Command, SensorEvent}; @@ -95,6 +96,35 @@ impl GuiOptions { } } +/// The GUI's log filter: `rust_log`, the value of `RUST_LOG`, when it holds anything, and +/// otherwise errors only. +/// +/// That is the filter `tracing_subscriber::fmt::init()` builds, with one line taken out +/// of the default: the error that btleplug 0.13.5 logs on macOS for every disconnect +/// that CoreBluetooth confirms. `crate::log_filter` says where the line comes from. A +/// `RUST_LOG` of the user's own is used as it is and still shows the line. +/// +/// When aranet moves to a btleplug release that no longer logs the line, the branch for +/// an empty `RUST_LOG` goes, and this function is `EnvFilter::new(rust_log)` again. +fn gui_log_filter(rust_log: &str) -> EnvFilter { + if rust_log.is_empty() { + EnvFilter::new(crate::log_filter::default_directives("error")) + } else { + EnvFilter::new(rust_log) + } +} + +/// Start logging to stdout, with the filter that `gui_log_filter` builds from `RUST_LOG`. +/// +/// This is `tracing_subscriber::fmt::init()` written out, so that the filter can differ +/// from the library's. Like `init()`, it panics if a global logger is already installed. +fn init_logging() { + let rust_log = std::env::var(EnvFilter::DEFAULT_ENV).unwrap_or_default(); + tracing_subscriber::fmt() + .with_env_filter(gui_log_filter(&rust_log)) + .init(); +} + /// Run the GUI application. /// /// This is the main entry point for the GUI. It: @@ -103,7 +133,7 @@ impl GuiOptions { /// 3. Spawns the background sensor worker /// 4. Runs the egui/eframe main loop pub fn run() -> Result<()> { - tracing_subscriber::fmt::init(); + init_logging(); // Load config to get service URL let config = Config::load_or_default()?; @@ -276,7 +306,7 @@ pub fn run() -> Result<()> { /// /// This allows running in demo mode with mock data for screenshots. pub fn run_with_options(options: GuiOptions) -> Result<()> { - tracing_subscriber::fmt::init(); + init_logging(); if options.demo { info!("Running in demo mode with mock data"); @@ -487,3 +517,40 @@ pub fn run_with_options(options: GuiOptions) -> Result<()> { Ok(()) } + +#[cfg(test)] +mod tests { + use super::*; + + use crate::log_filter::testing::{ + lines_shown_by, shows_disconnect_error, without_disconnect_error, + }; + + /// With `RUST_LOG` unset or empty the GUI logs errors only, as `fmt::init()` did, + /// without the error that btleplug logs on macOS for every disconnect. + #[test] + fn the_default_gui_log_leaves_out_btleplugs_disconnect_error() { + let errors = lines_shown_by(EnvFilter::new("error")); + assert!(shows_disconnect_error(&errors), "{errors:?}"); + + assert_eq!( + lines_shown_by(gui_log_filter("")), + without_disconnect_error(errors) + ); + } + + /// A `RUST_LOG` of the user's own is used as it is, as `fmt::init()` used it, so it + /// still shows the line that the default hides. + #[test] + fn rust_log_replaces_the_default_gui_log_filter() { + for rust_log in ["warn", "btleplug=trace", "aranet_core=debug"] { + assert_eq!( + lines_shown_by(gui_log_filter(rust_log)), + lines_shown_by(EnvFilter::new(rust_log)), + "RUST_LOG={rust_log}" + ); + } + let shown = lines_shown_by(gui_log_filter("warn")); + assert!(shows_disconnect_error(&shown), "{shown:?}"); + } +} diff --git a/crates/aranet-cli/src/lib.rs b/crates/aranet-cli/src/lib.rs index 9b1f9d6..fb79b6b 100644 --- a/crates/aranet-cli/src/lib.rs +++ b/crates/aranet-cli/src/lib.rs @@ -116,3 +116,8 @@ pub mod tui; // GUI module - publicly exposed for aranet-gui crate to use #[cfg(feature = "gui")] pub mod gui; + +// The default log filter. The library needs it only for the GUI; the `aranet` binary +// compiles the same file for the CLI. The file's own comment says why. +#[cfg(feature = "gui")] +mod log_filter; diff --git a/crates/aranet-cli/src/log_filter.rs b/crates/aranet-cli/src/log_filter.rs new file mode 100644 index 0000000..68f4939 --- /dev/null +++ b/crates/aranet-cli/src/log_filter.rs @@ -0,0 +1,171 @@ +//! The log filter that the `aranet` commands and the GUI use when the user has chosen +//! none. +//! +//! This file is a module of two crates. The library compiles it for the GUI (feature +//! `gui`), and the `aranet` binary compiles it again for the CLI (feature `cli`): the +//! binary cannot call a private function of the library, and the filter is not part of +//! the library's public API. Everything in this file must therefore be used by both. An +//! item that only one of them uses is dead code in the other, and clippy fails on it. + +/// Turns off the log target of btleplug's CoreBluetooth peripheral module. +/// +/// On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level for +/// every disconnect that CoreBluetooth confirms, and then returns `Ok` +/// (btleplug 0.13.5 `src/corebluetooth/peripheral.rs:468-476`). The disconnect's own +/// reply is answered with "Device disconnected", like every other pending operation +/// (`src/corebluetooth/internal.rs:678-698`), and `disconnect()` logs any reply but `Ok` +/// as an error. Every command that connects ends with a disconnect, so without this +/// directive each of them would log an error after it had succeeded. +/// +/// The line is that module's only warning or error. The target is not widened to +/// `btleplug`: other btleplug modules warn when Bluetooth is off or not permitted and +/// when a characteristic discovery fails, and those warnings are true. btleplug has the +/// module only on Apple platforms, so the directive does nothing on Linux and Windows. +/// +/// Remove the directive when aranet moves to a btleplug release that no longer logs the +/// line. +const BTLEPLUG_DISCONNECT_ERROR_OFF: &str = "btleplug::corebluetooth::peripheral=off"; + +/// The filter directives to use when neither a flag nor `RUST_LOG` chooses the filter: +/// `level` for every target, without btleplug's disconnect error. +pub(crate) fn default_directives(level: &str) -> String { + format!("{level},{BTLEPLUG_DISCONNECT_ERROR_OFF}") +} + +/// What the tests of the CLI's and the GUI's filters share: a fixed set of log lines, and +/// which of them a filter shows. +#[cfg(test)] +pub(crate) mod testing { + use std::sync::{Arc, Mutex, OnceLock}; + + use tracing_subscriber::EnvFilter; + + /// How btleplug's disconnect error starts, as `lines_shown_by` returns it. + const DISCONNECT_ERROR: &str = "ERROR btleplug::corebluetooth::peripheral: "; + + #[derive(Clone, Default)] + struct Captured(Arc>>); + + impl std::io::Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + + /// Keep a second, silent dispatcher registered for the rest of the test run. + /// + /// Tests on several threads call `lines_shown_by`, each with its own filter, and all + /// of them reach the log statements in it. tracing caches, for the whole process, + /// whether any subscriber wants a statement. While only one dispatcher is registered, + /// it fills that cache from the calling thread's subscriber alone and without a lock, + /// so the answer can overwrite the one just computed for a subscriber that another + /// thread registered. With a second dispatcher always registered, the answer is + /// computed over all of them, under the lock that registering takes. aranet-service's + /// tests keep one for the same reason. + fn register_silent_dispatcher() { + static SILENT: OnceLock = OnceLock::new(); + SILENT.get_or_init(|| tracing::Dispatch::new(tracing::subscriber::NoSubscriber::new())); + } + + /// Logs a fixed set of lines under a subscriber with `filter`, and returns the lines + /// the subscriber wrote, each as `LEVEL target: message`. + /// + /// The set has btleplug's disconnect error and an info line from the same module, + /// warnings and errors from btleplug's other CoreBluetooth modules, an error from the + /// crate's root and from its other backends, and lines of aranet's own. + /// + /// btleplug logs through the `log` crate. The bridge that the subscriber's `init` + /// installs asks the subscriber about each record with the record's own target + /// (tracing-log 0.2.0 `src/lib.rs:227-242`), so a filter treats these events as it + /// treats btleplug's lines. + pub(crate) fn lines_shown_by(filter: EnvFilter) -> Vec { + register_silent_dispatcher(); + let captured = Captured::default(); + let writer = captured.clone(); + let subscriber = tracing_subscriber::fmt() + .without_time() + .with_env_filter(filter) + .with_ansi(false) + .with_writer(move || writer.clone()) + .finish(); + let _guard = tracing::subscriber::set_default(subscriber); + + tracing::error!( + target: "btleplug::corebluetooth::peripheral", + "Shouldn't get anything but Ok!" + ); + tracing::info!( + target: "btleplug::corebluetooth::peripheral", + "Event receiver died, breaking out of corebluetooth device loop." + ); + tracing::warn!( + target: "btleplug::corebluetooth::internal", + "Adapter powered off, canceling all pending operations" + ); + tracing::error!( + target: "btleplug::corebluetooth::internal", + "Error sending notification event" + ); + tracing::warn!( + target: "btleplug::corebluetooth::central_delegate", + "Error discovering characteristics" + ); + tracing::error!( + target: "btleplug::corebluetooth::central_delegate", + "an error from the delegate" + ); + tracing::error!(target: "btleplug::corebluetooth::adapter", "an error from the adapter"); + tracing::error!(target: "btleplug::corebluetooth", "an error from the backend"); + tracing::error!(target: "btleplug", "an error from the crate root"); + tracing::error!(target: "btleplug::bluez::peripheral", "an error from BlueZ"); + tracing::error!(target: "btleplug::winrtble::peripheral", "an error from WinRT"); + tracing::warn!(target: "aranet_core::link", "a warning from aranet-core"); + tracing::error!(target: "aranet_cli::gui", "an error from aranet-cli"); + tracing::info!(target: "aranet_core::link", "an info line from aranet-core"); + + let text = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + text.lines() + .map(|line| line.trim_start().to_string()) + .collect() + } + + /// Whether `lines`, as `lines_shown_by` returns them, hold btleplug's disconnect error. + pub(crate) fn shows_disconnect_error(lines: &[String]) -> bool { + lines.iter().any(|line| line.starts_with(DISCONNECT_ERROR)) + } + + /// `lines` without btleplug's disconnect error. + pub(crate) fn without_disconnect_error(lines: Vec) -> Vec { + lines + .into_iter() + .filter(|line| !line.starts_with(DISCONNECT_ERROR)) + .collect() + } +} + +#[cfg(test)] +mod tests { + use tracing_subscriber::EnvFilter; + + use super::default_directives; + use super::testing::{lines_shown_by, shows_disconnect_error, without_disconnect_error}; + + /// At the CLI's level and at the GUI's, the default shows what the level alone shows + /// minus one line. btleplug's other modules and aranet's own lines are untouched. + #[test] + fn the_default_hides_only_btleplugs_disconnect_error() { + // Of the 14 lines `lines_shown_by` logs, 12 are warnings or errors and 9 are errors. + for (level, lines_at_level) in [("warn", 12), ("error", 9)] { + let plain = lines_shown_by(EnvFilter::new(level)); + assert_eq!(plain.len(), lines_at_level, "{level}: {plain:?}"); + assert!(shows_disconnect_error(&plain), "{level}: {plain:?}"); + + let shown = lines_shown_by(EnvFilter::new(default_directives(level))); + assert_eq!(shown, without_disconnect_error(plain), "{level}"); + } + } +} diff --git a/crates/aranet-cli/src/main.rs b/crates/aranet-cli/src/main.rs index afad1cf..0250861 100644 --- a/crates/aranet-cli/src/main.rs +++ b/crates/aranet-cli/src/main.rs @@ -17,6 +17,9 @@ mod cli; mod commands; #[cfg(feature = "cli")] mod format; +// Also a module of the library, for the GUI. The file's own comment says why. +#[cfg(feature = "cli")] +mod log_filter; #[cfg(feature = "cli")] mod style; #[cfg(feature = "cli")] @@ -128,13 +131,8 @@ async fn main() -> Result<()> { let mut config = Config::load_or_default()?; // Initialize tracing (write to stderr so stdout is clean for data) - let filter = if cli.quiet { - EnvFilter::new("warn") - } else if cli.verbose { - EnvFilter::new("debug") - } else { - EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("warn")) - }; + let rust_log = std::env::var(EnvFilter::DEFAULT_ENV).ok(); + let filter = cli_log_filter(cli.quiet, cli.verbose, rust_log.as_deref()); tracing_subscriber::fmt() .with_env_filter(filter) @@ -366,6 +364,31 @@ async fn main() -> Result<()> { Ok(()) } +/// The log filter of a CLI command. +/// +/// `--quiet` and `--verbose` each fix the filter. Without them a `RUST_LOG` that parses is +/// used as it is, and otherwise the filter is the default: warnings and errors. +/// +/// `--quiet` and the default leave out one line, through `log_filter::default_directives`: +/// the error that btleplug 0.13.5 logs on macOS for every disconnect that CoreBluetooth +/// confirms, which would follow every successful command that connects. `--verbose` and a +/// `RUST_LOG` of the user's own still show it. +/// +/// When aranet moves to a btleplug release that no longer logs the line, both calls of +/// `log_filter::default_directives` go back to `"warn"`. +#[cfg(feature = "cli")] +fn cli_log_filter(quiet: bool, verbose: bool, rust_log: Option<&str>) -> EnvFilter { + if quiet { + EnvFilter::new(log_filter::default_directives("warn")) + } else if verbose { + EnvFilter::new("debug") + } else { + rust_log + .and_then(|directives| EnvFilter::try_new(directives).ok()) + .unwrap_or_else(|| EnvFilter::new(log_filter::default_directives("warn"))) + } +} + #[cfg(feature = "cli")] fn handle_alias_command(action: &AliasSubcommand, quiet: bool) -> Result<()> { let alias_action = match action { @@ -674,6 +697,10 @@ fn print_examples() { mod tests { use super::*; + use crate::log_filter::testing::{ + lines_shown_by, shows_disconnect_error, without_disconnect_error, + }; + // ======================================================================== // resolve_format_with_config tests // ======================================================================== @@ -848,4 +875,55 @@ mod tests { "{text}" ); } + + // ======================================================================== + // cli_log_filter tests + // ======================================================================== + + /// `--quiet` and the default show warnings and errors, without the error that + /// btleplug logs on macOS for every disconnect. `--quiet` ignores `RUST_LOG` and wins + /// over `--verbose`; a `RUST_LOG` that does not parse gives the default. + #[test] + fn test_cli_log_filter_quiet_and_default_hide_btleplugs_disconnect_error() { + let warnings = lines_shown_by(EnvFilter::new("warn")); + assert!(shows_disconnect_error(&warnings), "{warnings:?}"); + let expected = without_disconnect_error(warnings); + + for (quiet, verbose, rust_log) in [ + (true, false, None), + (true, false, Some("debug")), + (true, true, None), + (false, false, None), + (false, false, Some("aranet_core=loud")), + ] { + assert_eq!( + lines_shown_by(cli_log_filter(quiet, verbose, rust_log)), + expected, + "quiet={quiet} verbose={verbose} RUST_LOG={rust_log:?}" + ); + } + } + + /// `--verbose` and a `RUST_LOG` of the user's own are used as they are, so both + /// still show the line that the default hides. + #[test] + fn test_cli_log_filter_verbose_and_rust_log_show_btleplugs_disconnect_error() { + for (verbose, rust_log, same_as) in [ + (true, None, "debug"), + (true, Some("error"), "debug"), + (false, Some("warn"), "warn"), + (false, Some("btleplug=trace"), "btleplug=trace"), + ] { + let shown = lines_shown_by(cli_log_filter(false, verbose, rust_log)); + assert!( + shows_disconnect_error(&shown), + "verbose={verbose} RUST_LOG={rust_log:?}: {shown:?}" + ); + assert_eq!( + shown, + lines_shown_by(EnvFilter::new(same_as)), + "verbose={verbose} RUST_LOG={rust_log:?}" + ); + } + } } diff --git a/crates/aranet-service/src/lib.rs b/crates/aranet-service/src/lib.rs index 832b990..edb3cbd 100644 --- a/crates/aranet-service/src/lib.rs +++ b/crates/aranet-service/src/lib.rs @@ -329,7 +329,23 @@ pub struct LoadedConfig { /// /// Each directive replaces a `RUST_LOG` directive for exactly its target: a /// known limit, so `RUST_LOG=aranet_store=debug`, for example, has no effect. -const DEFAULT_LOG_DIRECTIVES: &str = "aranet_service=info,tower_http=debug,aranet_store=warn"; +/// +/// The last directive turns off the log target of btleplug's CoreBluetooth +/// peripheral module. On macOS, btleplug 0.13.5 logs `Shouldn't get anything +/// but Ok!` at error level for every disconnect that CoreBluetooth confirms, +/// and then returns `Ok` (btleplug 0.13.5 +/// `src/corebluetooth/peripheral.rs:468-476`): the disconnect's own reply is +/// answered with "Device disconnected", like every other pending operation +/// (`src/corebluetooth/internal.rs:678-698`). The collector disconnects after +/// every poll, so the line would be logged once per poll per device. It is +/// that module's only warning or error. The cost is the limit above: no +/// `RUST_LOG` directive for that target, or for a shorter one such as +/// `btleplug=trace`, can show the module's lines (one error, one info and +/// four trace statements). btleplug has the module only on Apple platforms, +/// so the directive does nothing on Linux and Windows. Remove it when aranet +/// moves to a btleplug release that no longer logs the line. +const DEFAULT_LOG_DIRECTIVES: &str = "aranet_service=info,tower_http=debug,aranet_store=warn,\ + btleplug::corebluetooth::peripheral=off"; /// How long shutdown waits for background tasks after signalling them to /// stop, before aborting the ones left. @@ -1012,6 +1028,58 @@ mod tests { } } + /// On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error + /// level for every disconnect that CoreBluetooth confirms, and the + /// collector disconnects after every poll. The default directives turn + /// that module's log target off: no `RUST_LOG` directive for that target, + /// or for a shorter one such as `btleplug=trace`, can show its lines. + /// btleplug's other modules and this crate's own lines are left alone. + #[test] + fn btleplugs_disconnect_error_stays_out_of_the_service_log() { + crate::test_support::register_silent_dispatcher(); + for rust_log in [ + "", + "warn", + "btleplug=trace", + "error,btleplug::corebluetooth::peripheral=trace", + ] { + let captured = Captured::default(); + let writer = captured.clone(); + let filter = with_default_directives(tracing_subscriber::EnvFilter::new(rust_log)) + .expect("the default directives parse"); + let subscriber = tracing_subscriber::fmt() + .with_env_filter(filter) + .with_ansi(false) + .with_writer(move || writer.clone()) + .finish(); + let _guard = tracing::subscriber::set_default(subscriber); + + tracing::error!( + target: "btleplug::corebluetooth::peripheral", + "Shouldn't get anything but Ok!" + ); + tracing::error!( + target: "btleplug::corebluetooth::internal", + "another btleplug error" + ); + tracing::info!("a service info line"); + + let logs = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + assert!( + logs.contains("ERROR btleplug::corebluetooth::internal: another btleplug error"), + "RUST_LOG={rust_log:?}: {logs}" + ); + assert!( + logs.contains("INFO aranet_service::tests: a service info line"), + "RUST_LOG={rust_log:?}: {logs}" + ); + assert!( + !logs.contains("btleplug::corebluetooth::peripheral"), + "RUST_LOG={rust_log:?}: {logs}" + ); + } + } + /// A config that monitors one device every 60 s. fn one_device_config() -> Config { Config { From 6838c45860e6c72c7c4c8d67b93a5e7e6933649d Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 20:51:24 -0400 Subject: [PATCH 10/21] docs: correct the test comments about making a PeripheralId Comments in three test modules (four comment sites) gave reasons for not making a `PeripheralId` that the source of btleplug and of bluez-async does not bear out. The Windows reasons were wrong on 0.11.8 too; the Linux reason in format.rs stopped being true with bluez-async 0.9.0. - scan.rs said that the Windows `PeripheralId` wraps a u64. It wraps a `BDAddr`. - format.rs said that the tests which build a `DiscoveredDevice` run on macOS only because the constructors on Linux and Windows are private. On Windows `PeripheralId` has a public `From`; no helper was written for it. On Linux it is made from a `bluez_async::DeviceId`, a type aranet-cli can't name: btleplug doesn't re-export bluez-async and aranet-cli doesn't depend on it. - util.rs said, in two places, that a test can't easily create a `PeripheralId`. Only Linux lacks a conversion that aranet-core can reach. Each module's note now gives its reason with the btleplug 0.13.5 source line; the second comment in util.rs refers to the note above it. Comments only: every changed line is a `//` comment, and the tests of aranet-core and aranet-cli pass as before. --- crates/aranet-cli/src/format.rs | 9 +++++++-- crates/aranet-core/src/scan.rs | 14 +++++++++----- crates/aranet-core/src/util.rs | 15 ++++++++++++--- 3 files changed, 28 insertions(+), 10 deletions(-) diff --git a/crates/aranet-cli/src/format.rs b/crates/aranet-cli/src/format.rs index f2fc519..204998c 100644 --- a/crates/aranet-cli/src/format.rs +++ b/crates/aranet-cli/src/format.rs @@ -1530,8 +1530,13 @@ mod tests { // ======================================================================== // Note: DiscoveredDevice tests only run on macOS because: - // - Linux: bluez-async's DeviceId/AdapterId constructors are private - // - Windows: btleplug's PeripheralId constructor is not publicly accessible + // - Linux: PeripheralId is made from a bluez_async::DeviceId (btleplug + // 0.13.5 `src/bluez/peripheral.rs:358`), and these tests can't name that + // type: btleplug doesn't re-export bluez-async, and aranet-cli doesn't + // depend on it directly + // - Windows: PeripheralId can be made from a btleplug::api::BDAddr + // (btleplug 0.13.5 `src/winrtble/peripheral.rs:732`), but no helper like + // `make_test_peripheral_id` has been written for it // The formatting logic is still tested on macOS where PeripheralId can be created from UUID. /// Create a test PeripheralId for macOS (uses UUID) diff --git a/crates/aranet-core/src/scan.rs b/crates/aranet-core/src/scan.rs index 1bc3f59..e5b5216 100644 --- a/crates/aranet-core/src/scan.rs +++ b/crates/aranet-core/src/scan.rs @@ -2036,11 +2036,15 @@ mod tests { } // ==================== DiscoveredDevice Tests ==================== - // Note: DiscoveredDevice tests are removed because PeripheralId from btleplug - // has platform-specific implementations that cannot be easily mocked in tests. - // - macOS: PeripheralId wraps a UUID - // - Linux: PeripheralId wraps bluez_async::DeviceId (not directly accessible) - // - Windows: PeripheralId wraps a u64 + // Note: this module has no test that builds a DiscoveredDevice. Its `id` is + // btleplug's PeripheralId, which wraps a different type on each platform + // (btleplug 0.13.5): + // - macOS: PeripheralId wraps a UUID (`src/corebluetooth/peripheral.rs:46`) + // - Linux: PeripheralId wraps bluez_async::DeviceId + // (`src/bluez/peripheral.rs:49`). btleplug doesn't re-export bluez-async + // and aranet-core doesn't depend on it directly, so this crate can't name + // that type to make one + // - Windows: PeripheralId wraps a BDAddr (`src/winrtble/peripheral.rs:57`) // // The DiscoveredDevice struct derives Clone and Debug, so these traits are // guaranteed to work correctly by the compiler. diff --git a/crates/aranet-core/src/util.rs b/crates/aranet-core/src/util.rs index 2e78779..b7b73fd 100644 --- a/crates/aranet-core/src/util.rs +++ b/crates/aranet-core/src/util.rs @@ -115,14 +115,23 @@ fn name_from(properties: &PeripheralProperties, or_local_name: bool) -> Option<& #[cfg(test)] mod tests { - // Note: We can't easily create PeripheralId in tests, so we test the logic - // rather than calling the functions directly. + // Note: `test_create_identifier_with_valid_address` and + // `test_create_identifier_with_zero_address` don't call `create_identifier` + // or `format_peripheral_id`. Both functions take btleplug's PeripheralId, + // and a test that runs on every platform can't make one. btleplug 0.13.5 + // makes one from a UUID on macOS (`src/corebluetooth/peripheral.rs:672`) + // and from a BDAddr on Windows (`src/winrtble/peripheral.rs:732`), but on + // Linux only from a bluez_async::DeviceId (`src/bluez/peripheral.rs:358`). + // aranet-core can't name that type: btleplug doesn't re-export bluez-async, + // and aranet-core doesn't depend on it directly. So the two tests only + // compare an address with the all-zero one, as `create_identifier` does. #[allow(unused_imports)] use super::*; #[test] fn test_create_identifier_with_valid_address() { - // We can't easily create a PeripheralId in tests, but we can test the logic + // No PeripheralId here (see the note on PeripheralId in this module), + // so this only compares the address with the all-zero one. let address = "AA:BB:CC:DD:EE:FF"; // When address is valid, it should be used directly assert_ne!(address, "00:00:00:00:00:00"); From 52b0c486bc620fa2b7f751ffd9d2d568c4a97753 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 20:52:01 -0400 Subject: [PATCH 11/21] docs: reword the dependency version rule and name btleplug 0.13 in ARCHITECTURE.md The dependency policy said to pin to major versions only, with `btleplug = "0.11"` as its example. The workspace now asks for `btleplug = "0.13.5"`, the first release with two fixes aranet relies on, so the example named the old version and the rule contradicted the manifest. The policy now states the rule the btleplug requirement follows and new requirements should: ask for the major version, or the minor version of a 0.x crate, and for a later release only when the code needs something that release added, with a comment that says why. Its examples are lines of the root Cargo.toml. `tempfile = "3.10"` and the other requirements with a minor or patch version predate it and carry no comment. "What's Working Now" names btleplug 0.13, and the minimum version in the requirements table is 0.13.5. The two "(current)" labels in the survey of other Aranet crates are gone: they compared those crates with btleplug's newest release at the time the table was written. Checked in the rendered file: the block quote is one paragraph, and both tables keep their four columns. --- docs/ARCHITECTURE.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 35d3284..620a18a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,9 @@ Technical architecture and reference documentation for the Aranet Rust implement This project provides feature parity with [Aranet4-Python](https://github.com/Anrijs/Aranet4-Python) and beyond. > **Dependency Policy**: Always use the **latest stable versions** of all libraries, frameworks, and tools. -> Pin to major versions only (e.g., `btleplug = "0.11"` not `"0.11.4"`). Run `cargo update` regularly. +> Ask for the major version of a dependency, or for the minor version of a 0.x crate (`thiserror = "2"`, `tracing = "0.1"`). +> Ask for a later release only when the code needs something that release added, and say why in a comment above the +> requirement (`btleplug = "0.13.5"`). Run `cargo update` regularly. > Check [crates.io](https://crates.io) and [lib.rs](https://lib.rs) for current versions before adding dependencies. --- @@ -25,7 +27,7 @@ This project provides feature parity with [Aranet4-Python](https://github.com/An ### What's Working Now -- **aranet-core**: Complete BLE stack with btleplug 0.11 - scan, connect, device info, current readings, +- **aranet-core**: Complete BLE stack with btleplug 0.13 - scan, connect, device info, current readings, history download (V1+V2), settings read/write, auto-reconnection, streaming, notifications, RSSI, multi-device manager, event system, validation, thresholds, metrics, mock device - **aranet-types**: Shared types for CurrentReading, DeviceInfo, HistoryRecord, Status, DeviceType, all UUIDs @@ -236,7 +238,7 @@ path = "" # Empty = use default platform path | Dependency | Purpose | Min Version | Check Latest | |------------|---------|-------------|--------------| -| `btleplug` | Cross-platform BLE | 0.11+ | [crates.io/crates/btleplug](https://crates.io/crates/btleplug) | +| `btleplug` | Cross-platform BLE | 0.13.5+ | [crates.io/crates/btleplug](https://crates.io/crates/btleplug) | | `tokio` | Async runtime | 1.0+ | [crates.io/crates/tokio](https://crates.io/crates/tokio) | | `thiserror` | Error handling | 2.0+ | [crates.io/crates/thiserror](https://crates.io/crates/thiserror) | | `bytes` | Binary parsing | 1.0+ | [crates.io/crates/bytes](https://crates.io/crates/bytes) | @@ -902,8 +904,8 @@ Before building, learn from existing implementations: | Crate | Strengths | Weaknesses | btleplug Version | |-------|-----------|------------|------------------| -| `aranet` (m1guelpf) | Clean API, modern deps, device info | No history, no scanning | 0.11.4 (current) | -| `aranet-btle` (DDRBoxman) | BLE advertisement scanning | No device info, no history | 0.11 (current) | +| `aranet` (m1guelpf) | Clean API, modern deps, device info | No history, no scanning | 0.11.4 | +| `aranet-btle` (DDRBoxman) | BLE advertisement scanning | No device info, no history | 0.11 | | `aranet4` (lpraneis) | Historical data support | Uses OLD UUID only! | 0.9.1 (outdated) | | `aranet4-cli` (quentinms) | Multi-device, JSON output | CLI only, not a library | 0.9 (outdated) | From 064a3c1dd0adfdc2e8142c96a15dd6260e46aad6 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 20:53:26 -0400 Subject: [PATCH 12/21] docs: record the btleplug 0.13 upgrade in the changelog The unreleased section said nothing about the move from btleplug 0.11 to 0.13. It gains seven bullets, written against 0.2.1. Added: `aranet_core::peripheral_name`. Changed: on macOS, `discovery_timeout` now limits service discovery, errors that macOS reports for a read, a write or a subscribe are returned, and two failure texts are new; the combined macOS device name is gone; on Linux, adapters with a `bluetooth:` modalias are listed. One bullet marked "Breaking (library)" says that aranet-core's public API now carries btleplug 0.13 types, that `btleplug::Error` has a new variant, and that `local_name` means something different on each platform. The three bullets about macOS behaviour and the Linux adapters bullet carry the words "by the library's source": no hardware check has seen that behaviour yet. The early hardware check saw btleplug's error log line on a macOS disconnect, so the library bullet names the line and the log target that aranet's binaries leave out of their default output. The Linux connect path gets no new bullet: the entry about first connections to an Aranet4 is the statement against 0.2.1 and is still true. No existing line changed (7 lines added, none removed), and the file still has exactly one "Unreleased" heading. --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a631c85..e985785 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`DeviceNotFoundReason::Ambiguous` and `DeviceNotFoundReason::NoExactMatch`**, returned for a name that two nearby devices share and for a partial name (see Changed) - **`Device::connect_with_scan_options`**, to choose how long a connect searches for the device +- **`aranet_core::peripheral_name`**, the name aranet uses for a device, read from btleplug's `PeripheralProperties`: the name the device advertises, or on macOS, for a device that hasn't advertised one, the name macOS has stored for it. A program that reads `local_name` itself should call it instead (see Changed) - **Optional data retention** — `[storage.retention] readings_days` and `history_days` make the service delete older rows at startup and then hourly, in small batches. Off by default. `history_days` also prunes the history cache that `aranet sync` fills, which the next sync may download again. Both limits apply to everything in the database, including readings that the `aranet` CLI, TUI and GUI stored there when they share it (the default, except under the systemd system service and Docker) - **Setting `security.api_key_enabled = true` without `security.api_key`** now generates a key and saves it to `server.toml` - **The API key is also accepted as `Authorization: Bearer `**, so Prometheus can scrape an authenticated service with `authorization: { type: Bearer, credentials: … }`. A repeated `X-API-Key` or `Authorization` header, or an `X-API-Key` that isn't plain text, is never read as a key, so a request that sends its key that way is refused @@ -30,6 +31,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`ReconnectingDevice` retries** — it reconnects only after connection errors (not connected, timeouts, connection failures and Bluetooth link errors); other errors, such as a characteristic the device doesn't have, are returned at once. Operations that fail together share one reconnect; `cancel_reconnect()` and `disconnect()` stop a reconnect wait at once, and a reconnect already in progress no longer undoes `disconnect()`. A `with_device` closure can run a second time, but only after a connection error. `reconnect()`, and so `AranetDevice::connect()`, called while another reconnect is running waits for it instead of starting its own, and returns `Error::NotConnected` if that one gave up or `disconnect()` stopped it, or `Error::Cancelled` after `cancel_reconnect()`; operations waiting for a reconnect do the same. The old connection is closed when a reconnect starts, so while it runs, and after it fails, `ReconnectingDevice::name()` returns `None` and `address()` returns the identifier - **`DeviceManager`** — devices that were disconnected, evicted or removed stay that way until `connect()` is called; automatic reconnects back off per device using its `ReconnectOptions` and stop after `max_attempts` with one `DeviceEvent::Error`; `ManagerConfig::default().default_reconnect_options` is now `ReconnectOptions::unlimited()`; health checks run concurrently, a failed reconnect shortens the adaptive check interval even when other devices are healthy, and the monitor stops as soon as it is cancelled; a second `connect()` of a device waits for the first and returns its real result; a `connect()` that hasn't connected yet when `disconnect()`, `disconnect_all()`, `evict_lowest_priority()` or `remove_device()` is called for the same device returns `Error::Cancelled` and releases the sensor, instead of `Ok` or adding the device back; these four send `Disconnected`, and `remove_device()` removes the device, even when closing the connection fails or the call is cancelled, and still return a failed close's error; `max_concurrent_connections` counts connects in progress, so `connect_all` respects it; `connect()` on a device whose connection has dropped reconnects instead of returning `Ok`; `add_device`, `add_device_with_options` and `add_device_with_priority` reject invalid `ReconnectOptions`; passive readings from the hybrid monitor no longer reset a device's reconnect backoff - **`ConnectionConfig::discovery_timeout` on Linux** — while BlueZ is still discovering the services of a device it has just connected, a connect waits at least 20 s for it, even when `discovery_timeout` is shorter (`ConnectionConfig::fast()` sets 5 s) +- **`ConnectionConfig::discovery_timeout` on macOS** — by the library's source, btleplug 0.13 reports a macOS connection as made as soon as the link is up and discovers the services in a step of its own, so `discovery_timeout` (10 s by default, 8 s in the TUI) now limits that discovery, where the link and the discovery shared the connect timeout before; a connect has more time in all (25 s where it had 15 s by default, 40 s where it had 30 s in `aranet watch`, 18 s where it had 10 s in the TUI), and a discovery that alone takes longer than `discovery_timeout` fails with "Operation 'discover services' timed out" +- **Bluetooth errors on macOS** — by the library's source, an error that macOS reports for a read, a write or a subscribe is now returned as a "Bluetooth error", where the call ran into its time limit and failed as a timeout before; a read that needs pairing can still time out while macOS shows its pairing window +- **Two new failures on macOS** — by the library's source, once macOS reports that a sensor's services changed, reads on that connection fail with "Service no longer available" until the next connect; and when the characteristics of a service can't be discovered, the connect still succeeds and reads then fail with "Characteristic not found", which is not retried +- **Device names on macOS** — a sensor whose name stored by macOS differs from the name it advertises was listed as ` []`, for example `Kitchen [Aranet4 1A2B3]`. btleplug 0.13 no longer builds that form: the sensor is listed under its advertised name alone, `Aranet4 1A2B3`, and `-d Kitchen` or `-d "Kitchen [Aranet4 1A2B3]"` no longer finds it. Use the advertised name or the identifier that `aranet scan` prints. The rule for names on Linux and Windows is unchanged +- **Linux: Bluetooth adapters** — by the library's source, adapters that BlueZ reports with a `bluetooth:` modalias are now listed, where only those with a `usb:` modalias were before. aranet uses the first adapter BlueZ lists, so on a host with more than one adapter the one it uses can change +- **Breaking (library):** `aranet-core` now builds on btleplug 0.13 (0.13.5 or a later 0.13 release; 0.2.1 used 0.11) and so, on Linux, on bluez-async 0.9 (was 0.8). btleplug is a public dependency of `aranet-core` through `Error::Bluetooth`, `DiscoveredDevice::id`, `scan::get_adapter`, `scan::scan_with_adapter`, the `scan::find_device…` functions, `Device::connect_with_adapter`, `Device::from_peripheral…`, `format_peripheral_id`, `create_identifier` and the new `peripheral_name`, so a program that uses these with its own btleplug dependency must move to btleplug 0.13 too, and bumping it is a breaking change. `btleplug::Error`, which `Error::Bluetooth` carries, has a new variant, `NoAdapterAvailable`. Code that reads `PeripheralProperties::local_name` itself gets a different value on every platform: BlueZ's alias on Linux, the system's name for the device after a connect on Windows, and on macOS no longer the combined form (see "Device names on macOS"); `aranet_core::peripheral_name` returns the name aranet uses. On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level on every disconnect, under the log target `btleplug::corebluetooth::peripheral`; `aranet`, `aranet-service` and the GUI leave that target out of their default log output, and a program with its own logger must filter it out itself - **Breaking (library):** `aranet-service`'s Rust API changed for 0.3.0: - **`Collector::stop`** returns `CollectorStopResult`, and **`CollectorError`** is `#[non_exhaustive]` with a new `Timeout(Duration)` variant - **`PrometheusPusher::start`** returns `Option>` From a6be5dff71d80c08cc79e00c79669c5285c9d485 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:07:43 -0400 Subject: [PATCH 13/21] docs: correct what the Linux connect comments say about re-dials and retries A review of the branch found no defect in the connect path, but comments in link.rs and in its test double that say something false or leave a case out. Two of them are about a link that drops while bluez-async waits for the services. - The doc of the test that pins a 30 s connect timeout with the link down said the caller's own retry dials again. `aranet watch` and the service retry. `aranet read` and the other one-shot commands connect once, so for them the command fails. - The doc of `wait_for_bluez_discovery` said that at the default limits a link that drops during the wait is not reopened. That holds once BlueZ has accepted a call of the wait. While BlueZ still refuses with `In Progress`, the next call it accepts opens a new link. - The doc of `BLUEZ_DISCOVERY_TIMED_OUT` named only the first call of a connect. A call made again during the wait gets the text too, under a `discovery_timeout` above 30 s. - The two comments at the zero-services retry said a caller that retries searches for the sensor again. aranet's own callers that retry connect by identifier and do; a retry on a kept handle is refused until a scan has found the sensor. The inline comment also counted two ways in which btleplug 0.13.5 returns an empty service set on macOS. There are three: a "services changed" callback also empties the set that the handle keeps. - The doc of `LONG_CONNECT_LIMIT` said the tests of the paths that start with the library's timeout use that limit. Five do; the others set 90 s, `challenging_environment()` or no limit. The module doc now names the 90 s as well. - A test comment gave the wait's limit (100 s) as the time the wait lasts; the test asserts 60 s. - The fake's scripting rule named only a first connect under a 30 s limit. The same order that cannot happen arises for the retry's reconnect and for a call made again in a wait with exactly 30 s left. - Three test docs stated facts about bluez-async with no version or line, and two comments said bluez-async waits 30 s for the services where it waits up to 30 s. Comments only: every changed line is a `//` comment, and the functions and constants of the wait are as they were. Each statement was read against the source it names: btleplug 0.13.5 (the CoreBluetooth `internal.rs` and `peripheral.rs`), bluez-async 0.9.0 `src/lib.rs` (lines 57, 711-726, 748-751 and 759-760), BlueZ 5.82 `src/device.c`, tokio's `Timeout`, and the callers in aranet-cli and aranet-service. rustfmt (Rust 1.90), clippy on stable and on 1.90, the tests of aranet-core (410 unit tests) and the workspace docs pass. --- crates/aranet-core/src/link.rs | 75 ++++++++++++++++++----------- crates/aranet-core/src/link/fake.rs | 30 +++++++----- 2 files changed, 65 insertions(+), 40 deletions(-) diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index ec83245..890cf62 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -445,15 +445,17 @@ pub(crate) async fn connect( /// forget the peripheral, so the reconnect on the same handle fails at /// once with a retryable `Error::Bluetooth` ("Peripheral no longer /// available", `src/corebluetooth/internal.rs:1300-1304`), unless a scan -/// has found the sensor again during the pause. A caller that retries -/// then searches for the sensor again. +/// has found the sensor again during the pause. aranet's own callers that +/// retry connect by identifier, so they search for the sensor again. A +/// retry on the same handle (`Device::from_peripheral` and its variants) +/// is refused in the same way until a scan has found the sensor. /// 5. Read the properties, giving up after `read_timeout`. /// /// On BlueZ, a connect (the first one or the retry's) can end while BlueZ is /// still discovering the services on the live link. BlueZ answers /// `Device1.Connect` only once the ATT channel is up, a few seconds after the -/// link, and bluez-async then waits 30 s for the services (bluez-async 0.9.0 -/// `src/lib.rs:61`). It waited 5 s before btleplug 0.13.5 +/// link, and bluez-async then waits up to 30 s for the services +/// (bluez-async 0.9.0 `src/lib.rs:61`). It waited 5 s before btleplug 0.13.5 /// (). So under a /// `connection_timeout` of 30 s or less, the 15 s default included, a connect /// whose discovery is unfinished at that limit runs out of time first, and @@ -506,16 +508,22 @@ async fn connect_and_discover( // // On macOS, btleplug 0.11.8 never returned an empty set: its connect // didn't return when the discovery found no services. btleplug 0.13.5 - // does, in two ways. A discovery that CoreBluetooth ends with no error + // does, in three ways. A discovery that CoreBluetooth ends with no error // and no services succeeds with none - // (`src/corebluetooth/internal.rs:364-365`), and a "services changed" + // (`src/corebluetooth/internal.rs:364-365`). A "services changed" // callback during a discovery can end it with only the services that - // are left, which may be none (`:968-985`). The retry doesn't help - // there: the disconnect makes btleplug forget the peripheral (`:1175`), - // so the reconnect on this handle fails at once with "Peripheral no - // longer available" (`:1300-1304`), unless a scan has found the sensor - // again during the pause. That error is retryable, and a caller that - // retries searches for the sensor again. + // are left, which may be none (`internal.rs:968-985`). And every such + // callback, during a discovery or just after one, empties the set that + // this handle keeps (`internal.rs:986-993`, + // `src/corebluetooth/peripheral.rs:175-177`), which can happen before + // the set is read here. The retry doesn't help there: the disconnect + // makes btleplug forget the peripheral (`internal.rs:1175`), so the + // reconnect on this handle fails at once with "Peripheral no longer + // available" (`internal.rs:1300-1304`), unless a scan has found the + // sensor again during the pause. That error is retryable. aranet's own + // callers that retry connect by identifier, so they search for the + // sensor again; a retry on the same handle is refused in the same way + // until a scan has found the sensor. if services.is_empty() { warn!("Service discovery returned 0 services — retrying with fresh connection"); if let Err(e) = disconnect(link).await { @@ -558,8 +566,10 @@ async fn connect_and_discover( /// it on as `btleplug::Error::Other` (btleplug 0.13.5 /// `src/bluez/adapter.rs:182-186`). No other btleplug backend produces it. /// aranet-core can't name bluez-async's type (it isn't a dependency), so this -/// matches the message. A connect gets it only under a `connection_timeout` -/// longer than those 30 s; a shorter limit ends the call first. +/// matches the message. The first call of a connect gets it only under a +/// `connection_timeout` above those 30 s, and a call made again during the +/// wait only under a `discovery_timeout` above them +/// (`wait_for_bluez_discovery`); a limit of 30 s or less ends the call first. const BLUEZ_DISCOVERY_TIMED_OUT: &str = "Service discovery timed out"; /// The least time a connect waits for BlueZ to finish discovering the services @@ -758,8 +768,11 @@ async fn discover( /// If the link has dropped, a `Device1.Connect` made after the drop opens a /// new one, as the caller's own retry would. A call that is already waiting /// for the services does not notice a drop (bluez-async 0.9.0 -/// `src/lib.rs:711-726`), so at the default limits a link that drops during -/// the wait is not reopened. +/// `src/lib.rs:711-726`), and at the default limits its 30 s outlast the +/// wait. So there a link that drops after BlueZ has accepted a call of the +/// wait is not reopened. One that drops earlier, while BlueZ still refuses +/// with `In Progress` (below), is: the next call BlueZ accepts opens a new +/// link. /// /// After a connect timeout (`BluezWaitReason::ConnectTimedOut`), BlueZ may not /// have answered the timed-out `Device1.Connect` yet, and until it does it @@ -1760,8 +1773,8 @@ mod tests { /// connect then waits for BlueZ by asking it to connect again. bluez-async /// gives up before the connect's limit only when that limit is longer than /// its 30 s; the tests of that path set such a limit (`LONG_CONNECT_LIMIT`, -/// or `ConnectionConfig::challenging_environment()`). Either way BlueZ keeps -/// discovering on the live link. +/// 90 s, or `ConnectionConfig::challenging_environment()`). Either way BlueZ +/// keeps discovering on the live link. /// /// The fake's `fake::BLUEZ_ASYNC_WAIT` models bluez-async's wait, and its /// doc says how a first connect must be scripted. @@ -1793,8 +1806,8 @@ mod bluez_discovery_tests { /// (`BLUEZ_ASYNC_WAIT`). Only under such a limit can bluez-async's own /// "Service discovery timed out" end a first connect: under the default /// 15 s, and under `aranet watch`'s 30 s, the connect's limit ends it - /// first. The tests of the paths that start with the library's timeout - /// use this limit. + /// first. Most tests of the paths that start with the library's timeout + /// use this limit; the others set a longer one of their own. const LONG_CONNECT_LIMIT: Duration = Duration::from_secs(45); /// Connect `fake` with `config` and the test's runtime for cleanup, and @@ -1854,7 +1867,7 @@ mod bluez_discovery_tests { .await .expect("the connect should wait for BlueZ's service discovery"); - // The library gives up at 30 s. The wait then lasts until 100 s + // The library gives up at 30 s. The wait's limit is then 100 s // (30 + 70): the first re-ask gives up at 60 s (30 + 30) and the // second succeeds at once. assert_eq!(start.elapsed(), 2 * BLUEZ_ASYNC_WAIT); @@ -2144,8 +2157,9 @@ mod bluez_discovery_tests { /// before, with the "connect to device" timeout, and disconnects without /// waiting. The link may never have come up, or it came up and dropped /// while bluez-async was still waiting for the services: bluez-async - /// does not watch the link during that wait. Neither case is asked again - /// inside the connect. + /// does not watch the link during that wait (bluez-async 0.9.0 + /// `src/lib.rs:711-726`). Neither case is asked again inside the + /// connect. #[tokio::test(start_paused = true)] async fn a_connect_timeout_with_the_link_down_fails_on_bluez() { within(Duration::from_secs(600), async { @@ -2485,7 +2499,10 @@ mod bluez_discovery_tests { /// with the link down fails with its own timeout and is not asked again /// inside the connect. That covers a link that came up and dropped while /// bluez-async was waiting for the services: under a limit of 30 s or - /// less nothing re-dials it here, and the caller's own retry does. + /// less nothing re-dials it inside the connect. A caller that retries, + /// as `aranet watch` and the service do, dials again with its next + /// attempt. `aranet read` and the other one-shot commands do not retry: + /// for them the command fails with the connect's timeout. #[tokio::test(start_paused = true)] async fn a_30_s_connect_timeout_with_the_link_down_is_not_asked_again() { within(Duration::from_secs(600), async { @@ -2516,9 +2533,10 @@ mod bluez_discovery_tests { /// and a 30 s `discovery_timeout`), bluez-async gives up first, 30 s in. /// The wait asks again, and BlueZ resolves the services 6 s later. No /// connection-state query is made: bluez-async's timeout itself shows - /// that BlueZ had answered `Device1.Connect`. Under such a limit this is - /// also how a link that dropped during bluez-async's wait is dialled - /// again: the re-ask makes BlueZ open a new one. + /// that BlueZ had answered `Device1.Connect` (bluez-async 0.9.0 + /// `src/lib.rs:759-760`). Under such a limit this is also how a link + /// that dropped during bluez-async's wait is dialled again: the re-ask + /// makes BlueZ open a new one. #[tokio::test(start_paused = true)] async fn bluez_async_gives_up_first_under_a_long_connect_limit() { within(Duration::from_secs(600), async { @@ -2542,7 +2560,8 @@ mod bluez_discovery_tests { .await; } - /// bluez-async gives each D-Bus call 30 s. When BlueZ sends no reply to + /// bluez-async gives the `Device1.Connect` call 30 s (bluez-async 0.9.0 + /// `src/lib.rs:57`, `:748-751`). When BlueZ sends no reply to /// `Device1.Connect` in that time, a connect whose own limit is longer /// fails with bluez-async's error, "Timeout waiting for reply". That is /// not a timeout of the connect itself, so no connection-state query is diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index 8a2eaa6..13630dd 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -22,7 +22,7 @@ pub(super) enum Outcome { Fail, /// Never answer. It stands for two things. One is a BlueZ `connect` that /// is still waiting when aranet's own limit ends: bluez-async waits up to - /// 30 s for BlueZ's reply to `Device1.Connect` and then 30 s for the + /// 30 s for BlueZ's reply to `Device1.Connect` and then up to 30 s for the /// services (bluez-async 0.9.0 `src/lib.rs:57`, `:61`), so under the 15 s /// default limit this is how a slow first connect is scripted. The other /// is a call that the stack never answers, such as a CoreBluetooth @@ -33,8 +33,9 @@ pub(super) enum Outcome { /// `btleplug::Error::Other("Service discovery timed out")`. The wait /// starts at the call, as if BlueZ answered `Device1.Connect` at once, /// which it does when a wait asks again on a live link. The caller sees - /// this outcome only if its own limit is longer than `BLUEZ_ASYNC_WAIT`; - /// that constant's doc says how to script a first connect. + /// this outcome only if its own limit is `BLUEZ_ASYNC_WAIT` or longer; + /// that constant's doc says why a limit of exactly that length must be + /// scripted with `Hang`. DiscoveryTimedOut, /// Fail at once as BlueZ refuses a `Device1.Connect` while an earlier one /// to the same device is still pending (`org.bluez.Error.InProgress`), @@ -59,15 +60,20 @@ pub(super) enum Outcome { /// before it fails (`SERVICE_DISCOVERY_TIMEOUT`, bluez-async 0.9.0 /// `src/lib.rs:61`). It was 5 s before btleplug 0.13.5. /// -/// Never script `Outcome::DiscoveryTimedOut` for a first connect whose -/// `connection_timeout` is 30 s: script `Outcome::Hang`. bluez-async starts -/// this wait only once BlueZ has answered `Device1.Connect`, so on a real -/// host its timeout comes more than 30 s after the call, and a connect limit -/// of 30 s or less always ends first. This fake starts the wait at the call. -/// With a limit of exactly 30 s both would end at the same instant of the -/// paused clock, `tokio::time::timeout` polls the call before its own timer, -/// and the test would see the library's timeout first: an order that cannot -/// happen. Under a shorter limit the fake keeps the real order. +/// Never script `Outcome::DiscoveryTimedOut` for a call whose own limit is +/// exactly 30 s: script `Outcome::Hang`. Such a call is a first connect or +/// the zero-services retry's reconnect under a 30 s `connection_timeout` +/// (`aranet watch`'s default), or a call made again in a wait that has +/// exactly 30 s left, as the first one can have under a 30 s +/// `discovery_timeout` (`ConnectionConfig::challenging_environment()`). +/// bluez-async starts this wait only once BlueZ has answered +/// `Device1.Connect`, so on a real host its timeout comes more than 30 s +/// after the call, and a limit of 30 s or less always ends first. This fake +/// starts the wait at the call. With a limit of exactly 30 s both would end +/// at the same instant of the paused clock, tokio's `timeout` and +/// `timeout_at` poll the call before their own timer, and the test would +/// see the library's timeout first: an order that cannot happen. Under a +/// shorter limit the fake keeps the real order. pub(super) const BLUEZ_ASYNC_WAIT: std::time::Duration = std::time::Duration::from_secs(30); /// How long bluez-async waits for BlueZ's reply to a D-Bus method call, such From 629a73e0e5859ce9976c46ce1b4fe5b555fd9d49 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:07:49 -0400 Subject: [PATCH 14/21] docs: say what the name comments and the name guard's doc left out Three comments about device names were incomplete or gave a reason that does not hold. - A test comment in scan.rs said both name fields hold the name "as every backend reports a named sensor that has no BlueZ alias". By btleplug 0.13.5's source WinRT puts the system's name in `local_name` after a connect, and CoreBluetooth holds a name in `local_name` alone until one is advertised. The comment now names the three cases in which both fields hold the name, and the btleplug version. - The doc of the guard test in util.rs did not say what gets past it. A pattern that takes a field out of the struct has no dot before the name, and util.rs is skipped as a whole, so a second read in it would pass. Neither exists today. - The comment on the split search texts said the split keeps the test from finding itself. The test skips its own file. What the split does is keep a text search of the crate down to the two reads in `name_from`. Comments only: every changed line is a `//` comment. Checked against btleplug 0.13.5 (`src/winrtble/peripheral.rs:523-531`, `src/corebluetooth/internal.rs:1003-1008`, `src/bluez/peripheral.rs:155-156`) and by a search of aranet-core for the two field names: the only reads are the two in `name_from`, and no pattern takes a field out of the struct. rustfmt (Rust 1.90), clippy on stable and on 1.90, the tests of aranet-core and the workspace docs pass. --- crates/aranet-core/src/scan.rs | 6 ++++-- crates/aranet-core/src/util.rs | 11 +++++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/crates/aranet-core/src/scan.rs b/crates/aranet-core/src/scan.rs index e5b5216..77b59c6 100644 --- a/crates/aranet-core/src/scan.rs +++ b/crates/aranet-core/src/scan.rs @@ -1657,8 +1657,10 @@ mod tests { #[test] fn is_aranet_device_recognises_a_sensor_by_its_name_alone() { // No manufacturer data and no service: the name is all there is. Both - // fields hold it, as every backend reports a named sensor that has no - // BlueZ alias, so the answer is the same on every host. + // fields hold it, as btleplug 0.13.5 reports a named sensor on BlueZ + // while no alias is set, on CoreBluetooth once a name has been + // advertised, and on WinRT before a connect, so the answer is the same + // on every host. assert!(is_aranet_device(&named("Aranet4 12345", "Aranet4 12345"))); assert!(is_aranet_device(&named("ARANET2 2751B", "ARANET2 2751B"))); assert!(!is_aranet_device(&named("Standing desk", "Standing desk"))); diff --git a/crates/aranet-core/src/util.rs b/crates/aranet-core/src/util.rs index b7b73fd..f00ab70 100644 --- a/crates/aranet-core/src/util.rs +++ b/crates/aranet-core/src/util.rs @@ -277,13 +277,20 @@ mod peripheral_name_tests { /// passes: the test double of a peripheral (`link/fake.rs`) sets them /// that way. /// + /// Two kinds of read get past it. A pattern that takes a field out of + /// the struct (`PeripheralProperties { local_name, .. }`) has no dot + /// before the name. And this file is skipped as a whole, so a second read + /// in it, outside `name_from`, passes too. There is neither today, and + /// only a review keeps it so. + /// /// It searches `src` only. The `discover_services` example and the /// hardware tests' `known_peripheral` take the name from `peripheral_name` /// too, but they are outside `src`, and this test does not read them. #[test] fn only_peripheral_name_reads_the_name_fields() { - // Each in two halves, so that this test is not itself an occurrence of - // the texts it searches for. + // Each in two halves, so that a text search of the crate for them + // finds only the two reads in `name_from`. The test itself does not + // need the split: it skips this file. let field_reads = [ [".local", "_name"].concat(), [".advertisement", "_name"].concat(), From bd1999f2793f617d9daeb353f981842f79c5995c Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:07:49 -0400 Subject: [PATCH 15/21] test: check both halves of a bracketed name in the soak example The example's name test checked that a bracketed name matches as a whole and that its first half ("hall") does not. The second half was not checked, although the commit that removed the bracket matching says the name is matched by neither half in the example. One assertion adds the second half ("aranet2 2751b"). Checked: the example's 20 tests pass. With the query changed to the whole name in lower case the new assertion failed, so it can fail; that change was undone before this commit. rustfmt (Rust 1.90), clippy on stable and on 1.90 with --all-targets, the tests of aranet-core and the workspace docs pass. --- crates/aranet-core/examples/lifecycle_soak.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/aranet-core/examples/lifecycle_soak.rs b/crates/aranet-core/examples/lifecycle_soak.rs index 13b7b35..c67e897 100644 --- a/crates/aranet-core/examples/lifecycle_soak.rs +++ b/crates/aranet-core/examples/lifecycle_soak.rs @@ -1335,6 +1335,7 @@ mod tests { // A bracketed part is part of the name like any other. assert!(name_matches("Hall [Aranet2 2751B]", "hall [aranet2 2751b]")); assert!(!name_matches("Hall [Aranet2 2751B]", "hall")); + assert!(!name_matches("Hall [Aranet2 2751B]", "aranet2 2751b")); } #[test] From 6709a49bb0757ccb237ce44603d91dd5db548a6a Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:13:23 -0400 Subject: [PATCH 16/21] docs: say that --quiet uses the default log directives too The module doc of log_filter.rs said the filter is the one the commands and the GUI use "when the user has chosen none", and the doc of `default_directives` said it is for "when neither a flag nor `RUST_LOG` chooses the filter". `--quiet` is a flag that chooses the filter, and it builds it from these directives. Someone who reads the file alone would conclude that `--quiet` shows btleplug's disconnect error. Both docs now name who uses the directives: the CLI under `--quiet` and when neither `--verbose` nor `RUST_LOG` chooses a filter, and the GUI when `RUST_LOG` is unset or empty. The doc of `lines_shown_by` says the `log` bridge asks the subscriber about each record with the record's own target, and cited only the conversion that builds the metadata (tracing-log 0.2.0 `src/lib.rs:227-242`). It now cites the place that asks, `src/log_tracer.rs:170-201`, and keeps the conversion as what that call is made with. Comments only: every changed line is a `//` comment. Checked against `cli_log_filter` in main.rs (the `--quiet` branch and the default both call `default_directives`), `gui_log_filter` and `init_logging` in gui/mod.rs (an unset `RUST_LOG` is read as an empty one), and the two ranges in tracing-log 0.2.0, the version in Cargo.lock. rustfmt (Rust 1.90), clippy on stable and on 1.90, the tests of aranet-cli with default and with all features (335 and 363) and the workspace docs pass. --- crates/aranet-cli/src/log_filter.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/crates/aranet-cli/src/log_filter.rs b/crates/aranet-cli/src/log_filter.rs index 68f4939..4fd8634 100644 --- a/crates/aranet-cli/src/log_filter.rs +++ b/crates/aranet-cli/src/log_filter.rs @@ -1,5 +1,6 @@ -//! The log filter that the `aranet` commands and the GUI use when the user has chosen -//! none. +//! The default log filter of the `aranet` commands and the GUI: the CLI uses it under +//! `--quiet` and when neither `--verbose` nor `RUST_LOG` chooses a filter, the GUI when +//! `RUST_LOG` is unset or empty. //! //! This file is a module of two crates. The library compiles it for the GUI (feature //! `gui`), and the `aranet` binary compiles it again for the CLI (feature `cli`): the @@ -26,8 +27,9 @@ /// line. const BTLEPLUG_DISCONNECT_ERROR_OFF: &str = "btleplug::corebluetooth::peripheral=off"; -/// The filter directives to use when neither a flag nor `RUST_LOG` chooses the filter: -/// `level` for every target, without btleplug's disconnect error. +/// The directives of the default filter: `level` for every target, without btleplug's +/// disconnect error. The CLI builds its default and its `--quiet` filter from them, the +/// GUI the filter it uses when `RUST_LOG` is unset or empty. pub(crate) fn default_directives(level: &str) -> String { format!("{level},{BTLEPLUG_DISCONNECT_ERROR_OFF}") } @@ -80,8 +82,9 @@ pub(crate) mod testing { /// /// btleplug logs through the `log` crate. The bridge that the subscriber's `init` /// installs asks the subscriber about each record with the record's own target - /// (tracing-log 0.2.0 `src/lib.rs:227-242`), so a filter treats these events as it - /// treats btleplug's lines. + /// (tracing-log 0.2.0 `src/log_tracer.rs:170-201`, with the metadata that + /// `src/lib.rs:227-242` builds), so a filter treats these events as it treats + /// btleplug's lines. pub(crate) fn lines_shown_by(filter: EnvFilter) -> Vec { register_silent_dispatcher(); let captured = Captured::default(); From ae6c0132a554d29340471e20ca4a967b9fa6556c Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:15:51 -0400 Subject: [PATCH 17/21] test: pin what the GUI's log filter does with a RUST_LOG that holds no valid directive `gui_log_filter` adds the directive that hides btleplug's disconnect error only when `RUST_LOG` is unset or empty. A value that is not empty but holds no valid directive, such as `aranet_core=loud`, goes to `EnvFilter::new`, which drops what it cannot parse and falls back to errors only by itself (tracing-subscriber 0.3.23 `src/filter/env/builder.rs:146-159` and `334-338`). The GUI then logs errors with the line, as it did when it called `fmt::init()`. The CLI treats the same value as unset and hides the line, and has a test for it. Neither the doc nor a test said which of the two the GUI does, so a reader could not tell whether the difference is meant. The behaviour stays as it is. The doc of `gui_log_filter` now states it, and `rust_log_replaces_the_default_gui_log_filter` pins it: with such a value the filter shows the line and exactly what `error` alone shows. No line of the function's code changes. The new assertions passed on the first run, since they pin what the code already does. To see that they can fail, the test ran twice more with one temporary change each, edited back afterwards: with the value replaced by the empty string, and with a `gui_log_filter` that gives a value that does not parse the default directives. Both runs failed on the first new assertion. rustfmt (Rust 1.90), clippy on stable and on 1.90, the tests of aranet-cli with default and with all features (335 and 363, as before) and the workspace docs pass. --- crates/aranet-cli/src/gui/mod.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/crates/aranet-cli/src/gui/mod.rs b/crates/aranet-cli/src/gui/mod.rs index 906f3cf..ec6117c 100644 --- a/crates/aranet-cli/src/gui/mod.rs +++ b/crates/aranet-cli/src/gui/mod.rs @@ -103,6 +103,9 @@ impl GuiOptions { /// of the default: the error that btleplug 0.13.5 logs on macOS for every disconnect /// that CoreBluetooth confirms. `crate::log_filter` says where the line comes from. A /// `RUST_LOG` of the user's own is used as it is and still shows the line. +/// So does one that holds no valid directive: `EnvFilter::new` then falls back to errors +/// only by itself, as `fmt::init()` did, and that fallback does not carry the directive. +/// (The CLI treats a `RUST_LOG` that does not parse as unset.) /// /// When aranet moves to a btleplug release that no longer logs the line, the branch for /// an empty `RUST_LOG` goes, and this function is `EnvFilter::new(rust_log)` again. @@ -552,5 +555,9 @@ mod tests { } let shown = lines_shown_by(gui_log_filter("warn")); assert!(shows_disconnect_error(&shown), "{shown:?}"); + // No valid directive: the library's own fallback to errors only, with the line. + let shown = lines_shown_by(gui_log_filter("aranet_core=loud")); + assert!(shows_disconnect_error(&shown), "{shown:?}"); + assert_eq!(shown, lines_shown_by(EnvFilter::new("error"))); } } From c11c27eb0d0fb748f36ab5e14cded02cf20fc313 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:24:13 -0400 Subject: [PATCH 18/21] docs: correct the changelog's entries on Linux adapters and macOS errors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The whole-branch review found two false sentences and three incomplete ones in the Unreleased bullets that this branch added. Linux adapters: the bullet said that on a host with more than one adapter the one aranet uses can change. It cannot. BlueZ builds every adapter's modalias from the daemon-wide `DeviceID` setting, so all adapters of a host carry the same one. What changes is a host that sets `DeviceID = bluetooth:…`: 0.2.1 found no adapter there, and its adapters are now found. The bullet says that instead. Bluetooth errors on macOS: the bullet said that a failed subscribe ran into its time limit before. In 0.2.1 a subscribe had none, so the sentence about 0.2.1 now speaks of reads and writes only. The review's text went on to say that such a subscribe never returned. That clause is left out: btleplug 0.11.8 answers a pending subscribe with "Device disconnected" when the link ends, so "never" is too wide. Two new failures on macOS: the bullet now names the second error text ("Service invalidated; rediscovery required"), says that writes fail as reads do, and says who does not retry a missing characteristic: `ReconnectingDevice`, while `aranet watch` and the service connect again at their next poll. `discovery_timeout` on macOS: the bullet now says that no option or config key sets it, and that `--timeout` and the `timeout` key of `aranet watch` limit only the time the link takes to come up. The disconnect log line: the bullet now says that the disconnect has succeeded, that `aranet --verbose` and a `RUST_LOG` of the user's own can still show the line, and that `aranet-service` and `aranet server` keep the target off whatever `RUST_LOG` says. The four bullets that state behaviour read from code said "by the library's source". Everywhere else in that section "library" means aranet's own crates, so they now say "by btleplug's source code". Each sentence was checked before it was written: against btleplug 0.13.5 and 0.11.8 (`src/corebluetooth`), bluez-async 0.9.0 and 0.8.2 (`src/modalias.rs`, `src/lib.rs`, `src/adapter.rs`), BlueZ 5.82 (`src/adapter.c`, `src/main.c`), aranet 0.2.1 (`device.rs`, `scan.rs`, `error.rs`) and the code at this commit (`watch.rs`, `collector.rs`, `error.rs`, `reconnect.rs` and the three log filters). Five lines change, all above the first released section, and the file keeps one Unreleased heading. No Rust file changes; rustfmt (Rust 1.90) passes. --- CHANGELOG.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e985785..ee5b091 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,12 +31,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`ReconnectingDevice` retries** — it reconnects only after connection errors (not connected, timeouts, connection failures and Bluetooth link errors); other errors, such as a characteristic the device doesn't have, are returned at once. Operations that fail together share one reconnect; `cancel_reconnect()` and `disconnect()` stop a reconnect wait at once, and a reconnect already in progress no longer undoes `disconnect()`. A `with_device` closure can run a second time, but only after a connection error. `reconnect()`, and so `AranetDevice::connect()`, called while another reconnect is running waits for it instead of starting its own, and returns `Error::NotConnected` if that one gave up or `disconnect()` stopped it, or `Error::Cancelled` after `cancel_reconnect()`; operations waiting for a reconnect do the same. The old connection is closed when a reconnect starts, so while it runs, and after it fails, `ReconnectingDevice::name()` returns `None` and `address()` returns the identifier - **`DeviceManager`** — devices that were disconnected, evicted or removed stay that way until `connect()` is called; automatic reconnects back off per device using its `ReconnectOptions` and stop after `max_attempts` with one `DeviceEvent::Error`; `ManagerConfig::default().default_reconnect_options` is now `ReconnectOptions::unlimited()`; health checks run concurrently, a failed reconnect shortens the adaptive check interval even when other devices are healthy, and the monitor stops as soon as it is cancelled; a second `connect()` of a device waits for the first and returns its real result; a `connect()` that hasn't connected yet when `disconnect()`, `disconnect_all()`, `evict_lowest_priority()` or `remove_device()` is called for the same device returns `Error::Cancelled` and releases the sensor, instead of `Ok` or adding the device back; these four send `Disconnected`, and `remove_device()` removes the device, even when closing the connection fails or the call is cancelled, and still return a failed close's error; `max_concurrent_connections` counts connects in progress, so `connect_all` respects it; `connect()` on a device whose connection has dropped reconnects instead of returning `Ok`; `add_device`, `add_device_with_options` and `add_device_with_priority` reject invalid `ReconnectOptions`; passive readings from the hybrid monitor no longer reset a device's reconnect backoff - **`ConnectionConfig::discovery_timeout` on Linux** — while BlueZ is still discovering the services of a device it has just connected, a connect waits at least 20 s for it, even when `discovery_timeout` is shorter (`ConnectionConfig::fast()` sets 5 s) -- **`ConnectionConfig::discovery_timeout` on macOS** — by the library's source, btleplug 0.13 reports a macOS connection as made as soon as the link is up and discovers the services in a step of its own, so `discovery_timeout` (10 s by default, 8 s in the TUI) now limits that discovery, where the link and the discovery shared the connect timeout before; a connect has more time in all (25 s where it had 15 s by default, 40 s where it had 30 s in `aranet watch`, 18 s where it had 10 s in the TUI), and a discovery that alone takes longer than `discovery_timeout` fails with "Operation 'discover services' timed out" -- **Bluetooth errors on macOS** — by the library's source, an error that macOS reports for a read, a write or a subscribe is now returned as a "Bluetooth error", where the call ran into its time limit and failed as a timeout before; a read that needs pairing can still time out while macOS shows its pairing window -- **Two new failures on macOS** — by the library's source, once macOS reports that a sensor's services changed, reads on that connection fail with "Service no longer available" until the next connect; and when the characteristics of a service can't be discovered, the connect still succeeds and reads then fail with "Characteristic not found", which is not retried +- **`ConnectionConfig::discovery_timeout` on macOS** — by btleplug's source code, version 0.13 reports a macOS connection as made as soon as the link is up and discovers the services in a step of its own, so `discovery_timeout` (10 s by default, 8 s in the TUI) now limits that discovery, where the link and the discovery shared the connect timeout before; a connect has more time in all (25 s where it had 15 s by default, 40 s where it had 30 s in `aranet watch`, 18 s where it had 10 s in the TUI), and a discovery that alone takes longer than `discovery_timeout` fails with "Operation 'discover services' timed out". No `aranet` option or config key sets `discovery_timeout`: the `--timeout` option and the `timeout` key of `aranet watch` now limit only the time the link takes to come up +- **Bluetooth errors on macOS** — by btleplug's source code, an error that macOS reports for a read, a write or a subscribe is now returned as a "Bluetooth error". In 0.2.1 a read or a write ran into its time limit and failed as a timeout. A read that needs pairing can still time out while macOS shows its pairing window +- **Two new failures on macOS** — by btleplug's source code, once macOS reports that a sensor's services changed, reads and writes on that connection fail with "Service no longer available" until the next connect, and one that is in progress at that moment fails with "Service invalidated; rediscovery required"; and when the characteristics of a service can't be discovered, the connect still succeeds and reads then fail with "Characteristic not found", which `ReconnectingDevice` returns without reconnecting (`aranet watch` and the service connect again at their next poll) - **Device names on macOS** — a sensor whose name stored by macOS differs from the name it advertises was listed as ` []`, for example `Kitchen [Aranet4 1A2B3]`. btleplug 0.13 no longer builds that form: the sensor is listed under its advertised name alone, `Aranet4 1A2B3`, and `-d Kitchen` or `-d "Kitchen [Aranet4 1A2B3]"` no longer finds it. Use the advertised name or the identifier that `aranet scan` prints. The rule for names on Linux and Windows is unchanged -- **Linux: Bluetooth adapters** — by the library's source, adapters that BlueZ reports with a `bluetooth:` modalias are now listed, where only those with a `usb:` modalias were before. aranet uses the first adapter BlueZ lists, so on a host with more than one adapter the one it uses can change -- **Breaking (library):** `aranet-core` now builds on btleplug 0.13 (0.13.5 or a later 0.13 release; 0.2.1 used 0.11) and so, on Linux, on bluez-async 0.9 (was 0.8). btleplug is a public dependency of `aranet-core` through `Error::Bluetooth`, `DiscoveredDevice::id`, `scan::get_adapter`, `scan::scan_with_adapter`, the `scan::find_device…` functions, `Device::connect_with_adapter`, `Device::from_peripheral…`, `format_peripheral_id`, `create_identifier` and the new `peripheral_name`, so a program that uses these with its own btleplug dependency must move to btleplug 0.13 too, and bumping it is a breaking change. `btleplug::Error`, which `Error::Bluetooth` carries, has a new variant, `NoAdapterAvailable`. Code that reads `PeripheralProperties::local_name` itself gets a different value on every platform: BlueZ's alias on Linux, the system's name for the device after a connect on Windows, and on macOS no longer the combined form (see "Device names on macOS"); `aranet_core::peripheral_name` returns the name aranet uses. On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level on every disconnect, under the log target `btleplug::corebluetooth::peripheral`; `aranet`, `aranet-service` and the GUI leave that target out of their default log output, and a program with its own logger must filter it out itself +- **Linux: Bluetooth adapters** — by btleplug's source code and that of its BlueZ library, bluez-async 0.9, adapters that BlueZ reports with a `bluetooth:` modalias are now listed, where only those with a `usb:` modalias were before. BlueZ (5.82, by its source code) gives every adapter of a host the same modalias, built from `DeviceID` in `/etc/bluetooth/main.conf` (`usb:…` unless that is changed), so this matters only on a host that sets `DeviceID = bluetooth:…`: there 0.2.1 found no adapter and failed with "no Bluetooth adapter available", and its adapters are now found. On every other host the adapters listed are the same as before +- **Breaking (library):** `aranet-core` now builds on btleplug 0.13 (0.13.5 or a later 0.13 release; 0.2.1 used 0.11) and so, on Linux, on bluez-async 0.9 (was 0.8). btleplug is a public dependency of `aranet-core` through `Error::Bluetooth`, `DiscoveredDevice::id`, `scan::get_adapter`, `scan::scan_with_adapter`, the `scan::find_device…` functions, `Device::connect_with_adapter`, `Device::from_peripheral…`, `format_peripheral_id`, `create_identifier` and the new `peripheral_name`, so a program that uses these with its own btleplug dependency must move to btleplug 0.13 too, and bumping it is a breaking change. `btleplug::Error`, which `Error::Bluetooth` carries, has a new variant, `NoAdapterAvailable`. Code that reads `PeripheralProperties::local_name` itself gets a different value on every platform: BlueZ's alias on Linux, the system's name for the device after a connect on Windows, and on macOS no longer the combined form (see "Device names on macOS"); `aranet_core::peripheral_name` returns the name aranet uses. On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level after every disconnect that macOS confirms, under the log target `btleplug::corebluetooth::peripheral`; the disconnect has succeeded, and the line can be ignored. `aranet`, `aranet-service` and the GUI leave that target out of their default log output: `aranet --verbose`, and a `RUST_LOG` of your own in `aranet` and the GUI, can still show the line, while `aranet-service` and `aranet server` keep the target off whatever `RUST_LOG` says. A program with its own logger must filter it out itself - **Breaking (library):** `aranet-service`'s Rust API changed for 0.3.0: - **`Collector::stop`** returns `CollectorStopResult`, and **`CollectorError`** is `#[non_exhaustive]` with a new `Timeout(Duration)` variant - **`PrometheusPusher::start`** returns `Option>` From 3b2b4ded81c94470ba3f8cf6cdba3e4c7863fed4 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:24:47 -0400 Subject: [PATCH 19/21] docs: let the dependency rule ask for a later release that fixed something The rule said to ask for a later release only when the code needs something that release added. Its one example, btleplug 0.13.5, is a release that fixed something, so the rule did not cover its own example. It now says "added or fixed". The rule also read as if every manifest followed it. Some requirement lines name a later release without a comment, and they are older than the rule. A maintainer who compared the rule with the manifests could not tell which side is right, and might copy the form without a comment. The rule now names two such lines, `tempfile = "3.10"` in the workspace manifest and `proptest = "1.9.0"` in aranet-core and aranet-types, and says to give each its reason when it is next changed. The review proposed `indicatif = "0.18.3"` as the second example. In aranet-cli's manifest that requirement is an inline table with `version = "0.18.3"` and `optional = true`, so a search for the quoted text would find nothing. `proptest = "1.9.0"` stands in two manifests exactly so. Checked against the manifests: both example lines stand as quoted, with no comment above them, and `btleplug = "0.13.5"` has its comment. On this branch the only requirement line that changed is btleplug's, so the two examples are older than the rule. No manifest changes, and no other line of the document. --- docs/ARCHITECTURE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 620a18a..127aad2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -5,8 +5,10 @@ This project provides feature parity with [Aranet4-Python](https://github.com/An > **Dependency Policy**: Always use the **latest stable versions** of all libraries, frameworks, and tools. > Ask for the major version of a dependency, or for the minor version of a 0.x crate (`thiserror = "2"`, `tracing = "0.1"`). -> Ask for a later release only when the code needs something that release added, and say why in a comment above the -> requirement (`btleplug = "0.13.5"`). Run `cargo update` regularly. +> Ask for a later release only when the code needs something that release added or fixed, and say why in a comment +> above the requirement (`btleplug = "0.13.5"`). Requirements that name a later release without a comment +> (`tempfile = "3.10"`, `proptest = "1.9.0"`) are older than this rule; give each its reason when it is next changed. +> Run `cargo update` regularly. > Check [crates.io](https://crates.io) and [lib.rs](https://lib.rs) for current versions before adding dependencies. --- From 25d9b0e8f4fa941f23a77cfa74939c1b5ee03530 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 22:44:51 -0400 Subject: [PATCH 20/21] docs: narrow two changelog sentences to what the code does The entry on `discovery_timeout` said that `--timeout` and the `timeout` key of `aranet watch` limit only the time the link takes to come up. That holds for a connect. `watch --passive` uses the same value as the length of each scan, and `timeout` is the general key of config.toml, not a key of `watch`. The entry on the two new macOS failures said that reads and writes "on that connection" fail once macOS reports that services changed. btleplug 0.13.5 removes only the services macOS names (src/corebluetooth/internal.rs:977-981), and a read or a write fails only when its own service is gone. Both were found by the re-read of the changelog against the sources. The file keeps one Unreleased heading and four entries marked as read from btleplug's source code. --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee5b091..d5bcd59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,9 +31,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`ReconnectingDevice` retries** — it reconnects only after connection errors (not connected, timeouts, connection failures and Bluetooth link errors); other errors, such as a characteristic the device doesn't have, are returned at once. Operations that fail together share one reconnect; `cancel_reconnect()` and `disconnect()` stop a reconnect wait at once, and a reconnect already in progress no longer undoes `disconnect()`. A `with_device` closure can run a second time, but only after a connection error. `reconnect()`, and so `AranetDevice::connect()`, called while another reconnect is running waits for it instead of starting its own, and returns `Error::NotConnected` if that one gave up or `disconnect()` stopped it, or `Error::Cancelled` after `cancel_reconnect()`; operations waiting for a reconnect do the same. The old connection is closed when a reconnect starts, so while it runs, and after it fails, `ReconnectingDevice::name()` returns `None` and `address()` returns the identifier - **`DeviceManager`** — devices that were disconnected, evicted or removed stay that way until `connect()` is called; automatic reconnects back off per device using its `ReconnectOptions` and stop after `max_attempts` with one `DeviceEvent::Error`; `ManagerConfig::default().default_reconnect_options` is now `ReconnectOptions::unlimited()`; health checks run concurrently, a failed reconnect shortens the adaptive check interval even when other devices are healthy, and the monitor stops as soon as it is cancelled; a second `connect()` of a device waits for the first and returns its real result; a `connect()` that hasn't connected yet when `disconnect()`, `disconnect_all()`, `evict_lowest_priority()` or `remove_device()` is called for the same device returns `Error::Cancelled` and releases the sensor, instead of `Ok` or adding the device back; these four send `Disconnected`, and `remove_device()` removes the device, even when closing the connection fails or the call is cancelled, and still return a failed close's error; `max_concurrent_connections` counts connects in progress, so `connect_all` respects it; `connect()` on a device whose connection has dropped reconnects instead of returning `Ok`; `add_device`, `add_device_with_options` and `add_device_with_priority` reject invalid `ReconnectOptions`; passive readings from the hybrid monitor no longer reset a device's reconnect backoff - **`ConnectionConfig::discovery_timeout` on Linux** — while BlueZ is still discovering the services of a device it has just connected, a connect waits at least 20 s for it, even when `discovery_timeout` is shorter (`ConnectionConfig::fast()` sets 5 s) -- **`ConnectionConfig::discovery_timeout` on macOS** — by btleplug's source code, version 0.13 reports a macOS connection as made as soon as the link is up and discovers the services in a step of its own, so `discovery_timeout` (10 s by default, 8 s in the TUI) now limits that discovery, where the link and the discovery shared the connect timeout before; a connect has more time in all (25 s where it had 15 s by default, 40 s where it had 30 s in `aranet watch`, 18 s where it had 10 s in the TUI), and a discovery that alone takes longer than `discovery_timeout` fails with "Operation 'discover services' timed out". No `aranet` option or config key sets `discovery_timeout`: the `--timeout` option and the `timeout` key of `aranet watch` now limit only the time the link takes to come up +- **`ConnectionConfig::discovery_timeout` on macOS** — by btleplug's source code, version 0.13 reports a macOS connection as made as soon as the link is up and discovers the services in a step of its own, so `discovery_timeout` (10 s by default, 8 s in the TUI) now limits that discovery, where the link and the discovery shared the connect timeout before; a connect has more time in all (25 s where it had 15 s by default, 40 s where it had 30 s in `aranet watch`, 18 s where it had 10 s in the TUI), and a discovery that alone takes longer than `discovery_timeout` fails with "Operation 'discover services' timed out". No `aranet` option or config key sets `discovery_timeout`: in a connect made by `aranet watch`, `--timeout` (or the `timeout` config key) now limits only the time the link takes to come up - **Bluetooth errors on macOS** — by btleplug's source code, an error that macOS reports for a read, a write or a subscribe is now returned as a "Bluetooth error". In 0.2.1 a read or a write ran into its time limit and failed as a timeout. A read that needs pairing can still time out while macOS shows its pairing window -- **Two new failures on macOS** — by btleplug's source code, once macOS reports that a sensor's services changed, reads and writes on that connection fail with "Service no longer available" until the next connect, and one that is in progress at that moment fails with "Service invalidated; rediscovery required"; and when the characteristics of a service can't be discovered, the connect still succeeds and reads then fail with "Characteristic not found", which `ReconnectingDevice` returns without reconnecting (`aranet watch` and the service connect again at their next poll) +- **Two new failures on macOS** — by btleplug's source code, once macOS reports that a sensor's services changed, reads and writes of those services fail with "Service no longer available" until the next connect, and one that is in progress at that moment fails with "Service invalidated; rediscovery required"; and when the characteristics of a service can't be discovered, the connect still succeeds and reads then fail with "Characteristic not found", which `ReconnectingDevice` returns without reconnecting (`aranet watch` and the service connect again at their next poll) - **Device names on macOS** — a sensor whose name stored by macOS differs from the name it advertises was listed as ` []`, for example `Kitchen [Aranet4 1A2B3]`. btleplug 0.13 no longer builds that form: the sensor is listed under its advertised name alone, `Aranet4 1A2B3`, and `-d Kitchen` or `-d "Kitchen [Aranet4 1A2B3]"` no longer finds it. Use the advertised name or the identifier that `aranet scan` prints. The rule for names on Linux and Windows is unchanged - **Linux: Bluetooth adapters** — by btleplug's source code and that of its BlueZ library, bluez-async 0.9, adapters that BlueZ reports with a `bluetooth:` modalias are now listed, where only those with a `usb:` modalias were before. BlueZ (5.82, by its source code) gives every adapter of a host the same modalias, built from `DeviceID` in `/etc/bluetooth/main.conf` (`usb:…` unless that is changed), so this matters only on a host that sets `DeviceID = bluetooth:…`: there 0.2.1 found no adapter and failed with "no Bluetooth adapter available", and its adapters are now found. On every other host the adapters listed are the same as before - **Breaking (library):** `aranet-core` now builds on btleplug 0.13 (0.13.5 or a later 0.13 release; 0.2.1 used 0.11) and so, on Linux, on bluez-async 0.9 (was 0.8). btleplug is a public dependency of `aranet-core` through `Error::Bluetooth`, `DiscoveredDevice::id`, `scan::get_adapter`, `scan::scan_with_adapter`, the `scan::find_device…` functions, `Device::connect_with_adapter`, `Device::from_peripheral…`, `format_peripheral_id`, `create_identifier` and the new `peripheral_name`, so a program that uses these with its own btleplug dependency must move to btleplug 0.13 too, and bumping it is a breaking change. `btleplug::Error`, which `Error::Bluetooth` carries, has a new variant, `NoAdapterAvailable`. Code that reads `PeripheralProperties::local_name` itself gets a different value on every platform: BlueZ's alias on Linux, the system's name for the device after a connect on Windows, and on macOS no longer the combined form (see "Device names on macOS"); `aranet_core::peripheral_name` returns the name aranet uses. On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level after every disconnect that macOS confirms, under the log target `btleplug::corebluetooth::peripheral`; the disconnect has succeeded, and the line can be ignored. `aranet`, `aranet-service` and the GUI leave that target out of their default log output: `aranet --verbose`, and a `RUST_LOG` of your own in `aranet` and the GUI, can still show the line, while `aranet-service` and `aranet server` keep the target off whatever `RUST_LOG` says. A program with its own logger must filter it out itself From 72ae11ea1108d77997b9b7ab61d0240a9f1b8822 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Mon, 12 Oct 2026 01:52:00 -0400 Subject: [PATCH 21/21] docs: say what btleplug 0.13.5 does with a sensor reported as a scan stops, in the shared-scan hardware test The doc comment of `test_concurrent_finds_share_one_scan` explained the test's rare double `CacheHit`, and its rare failure, by CoreBluetooth reporting the sensor just after the scan had stopped. That describes btleplug 0.11.8. btleplug 0.13.5 drops a scan report that its CoreBluetooth thread takes up after the stop (`src/corebluetooth/internal.rs:1776-1784`). A report taken up just before the stop can still reach the adapter's list after `stop_scan` has returned: `stop_scan` only queues the stop (`src/corebluetooth/adapter.rs:176-182`), and a second task fills the list (`adapter.rs:59-82`). So the comment keeps the rare case and the advice to rerun the test once, and says where each fact is in the library's source. The comment was left until the hardware tests had run on the new library; the test passed when run on its own against an Aranet2. A comment only: the test and its assertion are unchanged. --- crates/aranet-core/tests/hardware_tests.rs | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/crates/aranet-core/tests/hardware_tests.rs b/crates/aranet-core/tests/hardware_tests.rs index a49b462..754e77e 100644 --- a/crates/aranet-core/tests/hardware_tests.rs +++ b/crates/aranet-core/tests/hardware_tests.rs @@ -308,12 +308,20 @@ async fn test_concurrent_scans_are_serialised() { /// either search starts, and the test skips. /// /// When a scan ends, the scanning search's post-scan check and the waiting -/// search's re-check run at the same moment. Rarely, CoreBluetooth reports the -/// sensor just after the stop, and only one of the two checks sees it. If the -/// scanning search misses it, it finds the sensor in its next attempt's -/// re-check, both searches end with `CacheHit`, and the test passes. If the -/// waiting search misses it, it scans for itself and the test fails: rerun it -/// once. Without the re-check the test fails on every run. +/// search's re-check run at the same moment, and a sensor reported in the +/// scan's last moment can reach the adapter's list between the two, so that +/// only one of them sees it. This was rare on btleplug 0.11.8, where +/// CoreBluetooth could also report the sensor just after the stop. btleplug +/// 0.13.5 drops a report that its CoreBluetooth thread takes up after the stop +/// (`src/corebluetooth/internal.rs:1776-1784`; the reason is at `:723-728`). +/// That leaves less room for the rare case but does not remove it: `stop_scan` +/// returns as soon as the stop is queued for that thread +/// (`src/corebluetooth/adapter.rs:176-182`), and a second task adds each +/// reported sensor to the list (`adapter.rs:59-82`). If the scanning search +/// misses the sensor, it finds it in its next attempt's re-check, both searches +/// end with `CacheHit`, and the test passes. If the waiting search misses it, +/// it scans for itself and the test fails: rerun it once. Without the re-check +/// the test fails on every run. #[tokio::test] #[ignore = "requires BLE hardware: Aranet devices advertising nearby"] async fn test_concurrent_finds_share_one_scan() {