Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ clearly-labelled add-on.
> no Apple logo.

<p align="center">
<img src="docs/example.png" alt="PodBridge tray menu on Windows: Status Connected, Battery L and R 100%, microphone-mode and noise-control submenus, Pair / Reconnect, Export diagnostics, and About PodBridge" width="360">
<img src="docs/example.png" alt="PodBridge tray menu on Windows: Status Connected, Battery L and R 100%, microphone-mode and noise-control submenus, Bluetooth connection entries, Export diagnostics, and About PodBridge" width="360">
<br>
<em>PodBridge lives in the system tray — battery, audio status, microphone &amp; noise-control modes, pairing, and diagnostics, one right-click away.</em>
</p>
Expand All @@ -33,10 +33,12 @@ single-file `.exe`** — no installer, no admin rights, nothing else to set up.
not a sign of a problem. Click **More info → Run anyway**.

**Set up in under 2 minutes:** launch PodBridge (a tray icon appears — no window,
no UAC prompt) → right-click the icon and choose **`Pair / Reconnect`** to add
your AirPods in Windows Bluetooth settings → once they connect, the tray
no UAC prompt) → right-click the icon and choose **`Open Bluetooth settings`** to
pair your AirPods in Windows → once they connect, the tray
**`Status:`** line reads **`Connected`** and the **`Battery:`** line shows
left/right/case charge. That's it: **paired, playing, battery visible.**
left/right/case charge. That's it: **paired, playing, battery visible.** Later,
reconnect already-paired AirPods in one click with **`Connect AirPods`** (no
driver, no admin).

Settings and logs live under `%LOCALAPPDATA%\PodBridge`. To uninstall: quit
PodBridge (tray → `Exit`) and delete the exe and the `%LOCALAPPDATA%\PodBridge`
Expand Down
34 changes: 31 additions & 3 deletions docs/architecture-diagrams.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ flowchart TB
end

subgraph Core["PodBridge.Core — platform-neutral domain (no OS, no P/Invoke)"]
Domain["Domain logic: AapProtocol · ContinuityParser · DeviceStateTracker · AutoPlayPauseEngine · MicPolicyEngine · AudioGuidanceEngine · ModelRegistry · CapabilityProvider · Diagnostics · NoiseControlController · GestureSettingsController / GestureRepushController"]
Domain["Domain logic: AapProtocol · ContinuityParser · DeviceStateTracker · AutoPlayPauseEngine · MicPolicyEngine · AudioGuidanceEngine · BluetoothAudioLinkController · ModelRegistry · CapabilityProvider · Diagnostics · NoiseControlController · GestureSettingsController / GestureRepushController"]
Ifaces["OS-boundary interfaces (abstractions)"]
end

subgraph Win["PodBridge.Windows — OS adapters (WinRT + P/Invoke, no UI)"]
Adapters["WinRtBleScanner · WinRtConnectionMonitor · WinRtBluetoothRadioSource · WindowsMediaController · WindowsAudioStateReader · WindowsAudioPolicy · WindowsAudioSessionMonitor · RunKeyStartupToggle · DiagnosticsExporter · RollingFileLoggerProvider"]
Adapters["WinRtBleScanner · WinRtConnectionMonitor · WindowsBluetoothAudioConnector · WinRtBluetoothRadioSource · WindowsMediaController · WindowsAudioStateReader · WindowsAudioPolicy · WindowsAudioSessionMonitor · RunKeyStartupToggle · DiagnosticsExporter · RollingFileLoggerProvider"]
T2Adapters["Tier 2: DriverAapTransport · AdvancedTierInstaller"]
end

Expand Down Expand Up @@ -65,6 +65,7 @@ flowchart LR
I9["IDiagnosticsExporter"]
I10["IAapTransport — Tier 2"]
I11["IAdvancedTierInstaller — Tier 2"]
I12["IBluetoothAudioConnector"]
end
subgraph WinImpl["PodBridge.Windows — implementation"]
A1["WinRtBleScanner"]
Expand All @@ -78,6 +79,7 @@ flowchart LR
A9["DiagnosticsExporter"]
A10["DriverAapTransport"]
A11["AdvancedTierInstaller"]
A12["WindowsBluetoothAudioConnector"]
end
I1 --- A1
I2 --- A2
Expand All @@ -90,6 +92,7 @@ flowchart LR
I9 --- A9
I10 --- A10
I11 --- A11
I12 --- A12
```

## 3. Key flows
Expand Down Expand Up @@ -136,7 +139,32 @@ sequenceDiagram
Eng->>Pol: restore prior routing
```

### 3.3 Noise-control switching (Tier 2, opt-in driver)
### 3.3 One-click connect / disconnect (Tier 1, driver-free, no admin)

```mermaid
sequenceDiagram
autonumber
participant UI as TrayConnectController (App)
participant Link as BluetoothAudioLinkController (Core)
participant Con as WindowsBluetoothAudioConnector (Windows)
participant Drv as Windows Bluetooth audio filters (A2DP + hands-free)

UI->>Link: Connect AirPods (off the UI thread)
Link->>Con: GetLinkState()
alt no paired AirPods / already connected
Con-->>Link: NotFound / Connected
else paired, disconnected
Link->>Con: SendRequest(Connect)
Con->>Drv: one-shot reconnect (KSPROPSETID_BtAudio) to every filter
loop poll every 500 ms, re-send every 10 s, up to 45 s
Link->>Con: GetLinkState()
end
end
Link-->>UI: outcome
UI->>UI: honest notification; on failure open Bluetooth settings
```

### 3.4 Noise-control switching (Tier 2, opt-in driver)

```mermaid
sequenceDiagram
Expand Down
23 changes: 20 additions & 3 deletions docs/architecture.md

Large diffs are not rendered by default.

31 changes: 25 additions & 6 deletions docs/user/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,11 +123,12 @@ PodBridge's control.
(system tray). There is no main window and **no UAC prompt** — PodBridge lives
in the tray. Hover for a tooltip like `PodBridge — … · …`.
2. **Pair your AirPods** if they are not paired yet. Right-click the tray icon and
choose **`Pair / Reconnect`** (this opens Windows **Bluetooth & devices**
choose **`Open Bluetooth settings`** (this opens Windows **Bluetooth & devices**
settings). Put the AirPods in pairing mode — lid open, then press and hold the
case button until the light blinks white — and add them from **Add device →
Bluetooth**. On first run PodBridge also shows a one-time **"Pair your AirPods"**
notification if none are paired.
notification if none are paired. Once paired, later reconnects are one click:
**`Connect AirPods`** (see [the tray menu](#the-tray-menu)).
3. **Confirm battery is visible.** Once the AirPods connect, right-click the tray
icon: the **`Status:`** line reads **`Connected`** and the **`Battery:`** line
shows the left bud, right bud, and case charge, for example
Expand Down Expand Up @@ -156,8 +157,24 @@ Right-click the tray icon. The menu (top to bottom):
its driver is installed the modes are disabled with an honest explanation and an
**`Enable advanced tier…`** entry.
- **`Refresh audio status`** — re-reads the codec and mic lines on demand.
- **`Pair / Reconnect`** — opens Windows Bluetooth settings to add or reconnect AirPods.
- **`Open Bluetooth settings`** — opens Windows Bluetooth settings.
- **`Connect AirPods`** — connects your **already-paired** AirPods in one click,
the same request Windows' Sound control panel sends for **Connect** (no driver,
no admin). Take the AirPods out of the case (or open the lid) near the PC first.
The item shows **`Connecting…`** while PodBridge waits for the link to come up —
usually a few seconds; right after a disconnect it can take longer, so PodBridge
repeats the request and waits up to about 45 seconds. If no paired AirPods are
found, Windows declines, or they don't connect in time, PodBridge says so and
opens Windows Bluetooth settings instead. Disabled while the AirPods are
`Connected`. PodBridge recognises AirPods by name (the name must contain
"AirPods"), so a paired **Beats** device is never connected or disconnected by
these items. If several AirPods are paired to this PC, the request goes to all of
them and whichever pair is nearby connects.
- **`Disconnect AirPods`** — disconnects the AirPods from this PC (shown as
**`Disconnecting…`** while it waits). They **stay paired**: use `Connect AirPods`
to bring them back. Enabled while they are `Connected`. With several AirPods paired,
every connected pair is disconnected.
- **`Open Bluetooth settings`** — opens Windows Bluetooth settings (to pair new
AirPods, or to connect manually).
- **`About PodBridge`** — opens the About window (disclaimer, license, version, docs link).
- **`Exit`** — quits PodBridge.

Expand Down Expand Up @@ -325,9 +342,11 @@ local-only.
## Troubleshooting

- **`Status: No AirPods paired`** — no AirPods are paired to this PC yet. Use
`Pair / Reconnect` and add them in Windows Bluetooth settings.
`Open Bluetooth settings` and add them in Windows Bluetooth settings.
- **`Status: Disconnected`** — the AirPods are paired but not connected. Take them
out of the case / near the PC, or use `Pair / Reconnect`.
out of the case / near the PC and use `Connect AirPods`. If they still don't
connect (for example they are connected to your phone right now, or out of
range), PodBridge opens Windows Bluetooth settings so you can connect manually.
- **`Status: Bluetooth unavailable`** — the PC's Bluetooth radio is off or missing.
Turn Bluetooth on in Windows settings.
- **`Battery: unknown / out of range`** — no live reading (disconnected or the
Expand Down
23 changes: 23 additions & 0 deletions src/PodBridge.App/App.xaml.cs
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ public partial class App : Application
private GestureSettingsWindow? _gestureSettingsWindow;
private AudioRecoveryWindow? _audioRecoveryWindow;
private TrayStatusController? _trayStatusController;
private TrayConnectController? _trayConnectController;
private TrayBatteryController? _trayBatteryController;
private TrayAudioController? _trayAudioController;
private TrayMicController? _trayMicController;
Expand Down Expand Up @@ -78,6 +79,10 @@ protected override void OnStartup(StartupEventArgs e)
_trayIcon, audioReader, monitor, Dispatcher);
_trayAudioController.Start();

// Started before the status controller (which starts the monitor) so its
// StatusChanged subscription sees the initial status.
StartConnectController(monitor);

// Drive the tray from live connection status and show first-run pairing
// guidance. StatusChanged is marshalled to this (UI) dispatcher inside
// the controller.
Expand All @@ -91,6 +96,19 @@ protected override void OnStartup(StartupEventArgs e)
StartDiagnostics();
}

// Wires the one-click "Connect AirPods" / "Disconnect AirPods" items for the
// already-paired AirPods (driver-free, no admin; the Core link controller falls back to
// Windows Bluetooth settings on failure via the tray controller).
private void StartConnectController(IConnectionMonitor monitor)
{
_trayConnectController = TrayConnectController.Create(
_trayIcon!,
_host!.Services.GetRequiredService<BluetoothAudioLinkController>(),
monitor,
Dispatcher);
_trayConnectController.Start();
}

// Wires the tray "Export diagnostics" action and the "Debug logging" toggle (issue #54).
// The snapshot factory reads the live Core state on demand; the exporter writes a local,
// address-masked, secret-free file (constitution: local-only); the same
Expand Down Expand Up @@ -350,6 +368,11 @@ protected override void OnExit(ExitEventArgs e)
_trayStatusController?.Dispose();
_trayStatusController = null;

// Unsubscribe the connect controller and cancel any in-flight connect/disconnect
// wait so no late outcome touches a disposed tray.
_trayConnectController?.Dispose();
_trayConnectController = null;

// The diagnostics controller owns no subscription (it only wired tray handlers), so
// dropping the reference is enough; the container disposes its resolved services.
_trayDiagnosticsController = null;
Expand Down
10 changes: 10 additions & 0 deletions src/PodBridge.App/CompositionRoot.cs
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,16 @@ private static void ConfigureServices(IServiceCollection services)
// container disposes it (IDisposable) on shutdown, unsubscribing it.
services.AddSingleton<BleScannerSupervisor>();

// One-click connect / disconnect of already-paired AirPods (follow-up to issue #7).
// Core policy driving the driver-free IBluetoothAudioConnector: it confirms an
// accepted request via the link state, re-sends a request the driver silently
// dropped (common right after a disconnect) and gives up after a generous timeout.
// A singleton so its single-operation guard spans the whole app; the tray
// (TrayConnectController) is its only consumer. Built via a factory so the connector
// is bound explicitly and the poll / re-send / timeout / clock defaults apply.
services.AddSingleton(sp => new BluetoothAudioLinkController(
sp.GetRequiredService<IBluetoothAudioConnector>()));

// Phase 4 mic-profile policy engine (issue #30). A singleton holding live event
// subscriptions to IAudioSessionMonitor for the app's lifetime (disposed by the
// container on shutdown). Constructed at startup so it runs on the background
Expand Down
Loading
Loading