From e8b021afe0a9c11010d3eee9d6c147efd18e1f37 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Thu, 2 Jul 2026 10:36:26 -0400 Subject: docs(spec): bluetooth panel decisions resolved, profile switching in v1 Craig approved all four decisions (pair implies trust+connect, blueman retired outright, battery in captions, 8s scan bursts) and pulled audio-profile switching into v1: the doctor's audio step gains a one-click Switch to A2DP repair over wpctl, and a degraded profile shows in the device caption. --- docs/design/2026-07-02-bluetooth-panel-spec.org | 83 ++++++++++++++----------- 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/docs/design/2026-07-02-bluetooth-panel-spec.org b/docs/design/2026-07-02-bluetooth-panel-spec.org index 56a27f0..f010c1a 100644 --- a/docs/design/2026-07-02-bluetooth-panel-spec.org +++ b/docs/design/2026-07-02-bluetooth-panel-spec.org @@ -55,10 +55,13 @@ short list of well-known failure modes. 4. Consistency: same stack, same window shape, same interaction grammar, same palette as the net panel. A user who knows one panel knows both. -Non-goals (this iteration): OBEX file transfer, audio-codec switching UI -(diagnostics may *name* a wrong profile; switching stays with wpctl for -now), multi-adapter support (both machines have one controller), BLE -sensor/GATT browsing. +Audio-profile switching is in scope for v1 (Craig, 2026-07-02 — "bitten +by this too many times to count"): the doctor's audio-profile step +carries a one-click repair, not just a diagnosis, and connected audio +devices surface their active profile (details in the doctor chain below). + +Non-goals (this iteration): OBEX file transfer, multi-adapter support +(both machines have one controller), BLE sensor/GATT browsing. * Design sketch @@ -209,11 +212,17 @@ The doctor chain, in order, each an evidence row: corrupt" (connect error string), and only the latter suggests the re-pair repair (remove + pair + trust + connect, confirmed first — it's the destructive tier). -6. Audio profile (audio devices only) — device connected but no - wpctl sink/source, or sink stuck in HSP/HFP when A2DP is expected: - evidence names it and points at the fix; switching profiles is - deliberately out of scope for v1 (non-goal), so this row is - diagnosis-only. +6. Audio profile (audio devices only) — device connected but no wpctl + sink/source, or the card stuck in HSP/HFP when A2DP is expected: + evidence names the active profile and offers the repair inline — + "Switch to A2DP" drives =wpctl set-profile = (profile + inventory from =wpctl status=/=inspect=), verifies the sink came back + in the expected profile, and reports fixed or no-change. In v1 per + Craig (2026-07-02): this failure mode has bitten repeatedly, so it + gets the one-click fix, not just a diagnosis. Connected audio-device + row captions also show the profile when it's the degraded one + ("Connected · mic mode (HSP)") so the state is visible before the + doctor runs. Repairs confirm with the net panel's future-tense scope copy ("This will restart the Bluetooth service. Connected devices will drop and @@ -270,39 +279,39 @@ this panel adopts whatever resolution those tasks land on. * Decisions (Craig) -** TODO Pair implies trust + connect? -Recommendation: yes — one Pair verb does pair → trust → connect. Pairing -a device nearly always means "use it now, auto-reconnect later"; a -device you don't want auto-reconnecting gets untrusted from its row -caption menu later (or we add a per-device "auto-reconnect" toggle in a -later pass). The alternative (separate Pair / Trust / Connect buttons) -triples the button bar for the rare case. - -** TODO Retire blueman entirely? -The panel + bar module replace blueman-applet and blueman-manager -(Super+Shift+B rebinds to the panel). Recommendation: drop the blueman -package from archsetup and both machines once the panel's phase 2 lands; -keep bluetoothctl as the terminal fallback. The alternative keeps blueman -installed-but-unwired as a safety net during a bake-in period. - -** TODO Battery in the row caption or tooltip only? -Recommendation: caption when the device reports it ("Connected · battery -80%"), tooltip otherwise. It's the one datum that changes decisions -(charge the mouse tonight?); hiding it behind hover buries the payoff. - -** TODO Scan burst length and auto-rescan? -Recommendation: 8s bursts, no auto-repeat — Rescan is explicit, matching -the net panel's Available view. The alternative (continuous scan while -the Nearby view is open) finds slow advertisers but burns radio and -battery, and the open-ended spinner reads as "stuck". +** DONE Pair implies trust + connect? +CLOSED: [2026-07-02 Thu] +Decided (Craig, 2026-07-02): yes — one Pair verb does pair → trust → +connect. A device that shouldn't auto-reconnect gets untrusted later; a +per-device auto-reconnect toggle can ride a later pass. + +** DONE Retire blueman entirely? +CLOSED: [2026-07-02 Thu] +Decided (Craig, 2026-07-02): drop it outright, no bake-in period — the +package leaves archsetup and both machines once phase 2 lands, +bluetoothctl stays as the terminal fallback. Craig's framing: any issue +after retirement is a signal the doctor needs another check or the panel +has a real bug, and it gets fixed there rather than papered over by +keeping blueman around. + +** DONE Battery in the row caption or tooltip only? +CLOSED: [2026-07-02 Thu] +Approved (Craig, 2026-07-02): caption when the device reports it +("Connected · battery 80%"), tooltip otherwise. + +** DONE Scan burst length and auto-rescan? +CLOSED: [2026-07-02 Thu] +Approved (Craig, 2026-07-02): 8s bursts, no auto-repeat — Rescan stays +explicit, matching the net panel's Available view. * Implementation phases 1. Engine =bt= package: adapter/device/scan probes over fake-bluetoothctl, status + doctor chain (rfkill, service, powered, reachability, audio - profile) — pure TDD, no GTK. =bt status= and =bt doctor= work from a - terminal. Shared dupre css factored to the common asset if the - settings panel hasn't already done it. + profile probe + A2DP switch repair over fake-wpctl) — pure TDD, no + GTK. =bt status= and =bt doctor= work from a terminal. Shared dupre + css factored to the common asset if the settings panel hasn't already + done it. 2. Panel: PanelModel presenter + Blueprint pages (Devices with Paired/Nearby, Diagnostics), worker-thread wiring, pairing-dialog state machine, bt-panel toggle wrapper, AT-SPI smoke. Super+Shift+B -- cgit v1.2.3