Skip to content

feat: one-click Connect / Disconnect for paired AirPods - #195

Merged
bhemsen merged 2 commits into
bhemsen:mainfrom
ttohin:feat/one-click-connect
Oct 6, 2026
Merged

bhemsen merged 2 commits into
bhemsen:mainfrom
ttohin:feat/one-click-connect

Conversation

@ttohin

@ttohin ttohin commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The tray's "Pair / Reconnect" entry only deep-linked to Windows Bluetooth settings (Phase-1 placeholder, see the old comment in TrayIcon.cs). This PR replaces it with a real one-click Connect AirPods for already-paired AirPods, plus Disconnect AirPods. Both are driver-free and need no admin (Tier 1, asInvoker unchanged). Open Bluetooth settings stays for pairing new AirPods, and is also the automatic fallback whenever a connect or disconnect fails.

This follows up on #7 (closed; it delivered the tray status and the pairing deep link that this replaces), so there is no Closes.

How it works

The adapter sends the same driver request the Windows Sound control panel → Connect uses:

  1. It enumerates the audio endpoints (render and capture, state ACTIVE | UNPLUGGED) and keeps the AirPods ones using AirPodsNameHeuristic.IsAirPodsName, which matches AirPods only, so paired Beats are excluded. An endpoint that fails during enumeration is skipped and doesn't degrade the whole result.
  2. For each endpoint it follows the device topology's connectors with IDeviceTopology → IConnector::GetDeviceIdConnectedTo. It keeps the Bluetooth audio filters ({2}.\\?\bth…): the A2DP filter (BTHENUM) and the hands-free filter (BTHHFENUM).
  3. It sends KSPROPERTY_ONESHOT_RECONNECT / KSPROPERTY_ONESHOT_DISCONNECT (KSPROPSETID_BtAudio, KSPROPERTY_TYPE_GET, no data buffer) via IKsControl::KsProperty to every filter, like Windows does.
  4. The link state is read from the endpoint state: DEVICE_STATE_ACTIVE means connected, DEVICE_STATE_UNPLUGGED means paired but disconnected.

S_OK only means the driver accepted the request, so success is always confirmed by the endpoint state.

Layering

  • Core (OS-free):
    • Bluetooth/IBluetoothAudioConnector is the new OS boundary.
    • BluetoothAudioLinkController is the policy: a pre-check (not found / already in state), then send, confirm by polling every 500 ms, re-send every 10 s, and give up after 45 s. Real-hardware testing showed that the first reconnect right after a disconnect is often silently ignored while the old link winds down, and that 15 s was too short. A single-operation guard makes it return Busy if an operation is already running.
    • BluetoothAudioLinkText holds the labels, the honest notifications, and the decision to fall back to settings.
  • Windows:
    • WindowsBluetoothAudioConnector and Interop/BluetoothAudioInterop use classic [ComImport] interop, consistent with the existing Core Audio interop, and reuse IMMDeviceEnumerator, IMMDevice and NativeMethods.
    • The adapter is stateless and never throws; COM failures degrade to not found / rejected.
  • App:
    • TrayConnectController runs the operation on the thread pool, so the UI thread is never blocked. While it runs, the item shows Connecting… / Disconnecting… and both items are disabled.
    • It shows the outcome as a notification and opens Bluetooth settings on any failure.
    • Connect is enabled unless the monitor already reports Connected; Disconnect is enabled while Connected (or when the status is still unknown).
    • A pending operation is cancelled on exit.

Honest behaviour

  • No paired AirPods → "No paired AirPods found" and Bluetooth settings open.
  • Timeout → "Your AirPods didn't connect. Take them out of the case (or open the lid) and try again." and Bluetooth settings open.
  • Disconnect says the AirPods stay paired.
  • Several paired AirPods: the request goes to every matched AirPods and whichever pair is in range connects. Beats are never targeted. Per-pair targeting by ContainerId, which needs a pair picker or a remembered pair, is left as a follow-up. This is documented in the user guide.

Clean-room / licensing

The constants are the public ones from the Windows SDK headers (ksmedia.h: KSPROPSETID_BtAudio, KSPROPERTY_ONESHOT_RECONNECT/DISCONNECT; ks.h; mmdeviceapi.h; devicetopology.h) and are cited in BluetoothAudioInterop.cs. Prior art for the technique is m2jean/ToothTray (BSD-2); no code was copied from it. No driver, no elevation, no network.

Docs

  • README.md: the quickstart now uses Open Bluetooth settings to pair and mentions one-click Connect AirPods. The image alt text is made neutral.
  • docs/user/README.md: covers setup, the tray menu (Connect / Disconnect, the wait of up to 45 s, the fallback, the several-AirPods note) and troubleshooting.
  • docs/architecture.md: component map and a new key flow 6.
  • docs/architecture-diagrams.md: layer map, interface map, and a new sequence diagram (3.3).
  • UserDocsTests pins the new labels in the docs.
  • The first-run guidance toast now points to Open Bluetooth settings.

Not changed:

  • docs/example.png still shows the old Pair / Reconnect label; the screenshot needs re-capturing.
  • The historical QA reports under docs/qa/ and the archived specs are unchanged.

Testing

Automated: build/verify.ps1 is green (build, analyzers as errors, dotnet format --verify-no-changes, tests: 388 Core + 46 Windows passing). The new tests are:

  • BluetoothAudioLinkControllerTests (11 tests: already connected, not found, confirmed on poll, first request ignored then re-sent at 10 s, timeout after 45 s with 5 sends, result mapping, disconnect, busy guard, cancellation, …).
  • BluetoothAudioLinkTextTests.
  • AirPodsNameHeuristicTests for the AirPods-only IsAirPodsName (Beats excluded).
  • A user-docs label pin.

The timing tests are deterministic: a lock-step FakeTimeProvider wrapper, with no real delays. I re-ran them 5× with no flakes.

Real hardware (AirPods Pro "AirPods Pro (Anton)", Windows 11, this PR's code):

  • A read-only probe calling this PR's WindowsBluetoothAudioConnector reported GetLinkState() = Connected while the AirPods were connected.
  • The probe matched 2 AirPods endpoints (render + capture) and found both Bluetooth filters: the A2DP BTHENUM#{0000110b-…} source and the hands-free BTHHFENUM#bthhfpaudio wave filter.
  • After the review fixes, another read-only probe ran while the AirPods were disconnected. GetLinkState() reported Disconnected (both endpoints UNPLUGGED), and the new GetDeviceIdConnectedTo lookup returned exactly the same two filter ids as the previous IPart walk.
  • The same mechanism was validated end to end on the same AirPods with a standalone prototype before this PR: the reconnect/disconnect property sent to both filters, connect in about 3 s, and the ignored-first-reconnect behaviour right after a disconnect that motivated the 10 s re-send and 45 s timeout.
  • Live, through the PodBridge app: I ran this PR's build (self-contained single-file publish) on the same machine and used the tray's Connect AirPods / Disconnect AirPods items on the AirPods Pro. Both work, and I have been using it daily since.

Replace the tray "Pair / Reconnect" deep link with real "Connect AirPods" /
"Disconnect AirPods" actions for already-paired AirPods (follow-up to bhemsen#7).

- Core: IBluetoothAudioConnector boundary plus BluetoothAudioLinkController
  (send, confirm via endpoint state every 500 ms, re-send every 10 s, give
  up after 45 s) and BluetoothAudioLinkText (labels, honest notices, and the
  Bluetooth-settings fallback decision), covered by fake-based tests.
- Windows: WindowsBluetoothAudioConnector walks the AirPods' render and
  capture endpoint topology to the Bluetooth A2DP and hands-free filters and
  sends the public one-shot reconnect/disconnect KS property
  (KSPROPSETID_BtAudio, ksmedia.h) via IKsControl, the same request the
  Sound control panel's Connect uses. It is driver-free, needs no admin, and
  never throws.
- App: TrayConnectController runs the operation off the UI thread, shows
  Connecting... / Disconnecting..., notifies the outcome and opens Windows
  Bluetooth settings on any failure. "Open Bluetooth settings" stays for
  pairing.
- Docs: README, the user guide and the architecture docs (component map,
  flow 6, diagrams) are updated; the user guide labels are pinned by tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@ttohin

ttohin commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Hi @bhemsen 👋 friendly ping on this one.

I've tested it on my own AirPods Pro (Windows 11): one-click Connect and Disconnect from the tray work, and I've been using this build every day since. It's become my favourite PodBridge feature.

The CI / CodeQL / Dependency Review workflows are waiting for maintainer approval since this PR comes from a fork ("Approve and run" on the Checks tab). Locally build/verify.ps1 is green.

Happy to adjust anything — naming, menu layout, retry timings, or splitting the PR if that makes it easier to review. Thanks!

@bhemsen bhemsen left a comment •

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI green; build/verify.ps1 green on merge with current main (379 Core + 46 Windows tests). Two required changes, see inline comments.

- Skip an endpoint that fails mid-enumeration instead of degrading the
  whole result to NotFound/Rejected (and a confirmation poll to a false
  timeout).
- Match AirPods only (new AirPodsNameHeuristic.IsAirPodsName) so the
  "AirPods" items never connect or disconnect a paired Beats device.
- Read the filter id with IConnector::GetDeviceIdConnectedTo instead of
  the IPart/GetTopologyObject walk (same ids, verified read-only on
  hardware); drop the now-unused IPart declaration.
- Rename the KSPROPERTY struct to KsPropertyHeader and make the
  IMMDeviceWithState slot comments 0-based.
- Docs: user guide and architecture flow 6.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@bhemsen
bhemsen merged commit 982c5d3 into bhemsen:main Oct 6, 2026
5 checks passed
bhemsen added a commit that referenced this pull request Oct 6, 2026
Release notes fragment for v1.3.0: one-click Connect / Disconnect (#195)
plus CI and dependency maintenance since v1.2.1.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants