ADR-025: macOS CoreWLAN WiFi Sensing via Swift Helper Bridge

1. Context

1.1 The Gap: macOS Is a Silent Fallback

The --source auto path in sensing-server probes for ESP32 UDP, then Windows netsh, then falls back to simulated mode. macOS users hit the simulation path silently — there is no macOS WiFi adapter. This is the only major desktop platform without real WiFi sensing support.

1.2 Platform Constraints (macOS 26.3+)

1.3 The Opportunity: Multi-AP RSSI Diversity

Same principle as ADR-022 (Windows): visible APs serve as pseudo-subcarriers. A typical indoor environment exposes 10-30+ SSIDs across 2.4 GHz and 5 GHz bands. Each AP's RSSI responds differently to human movement based on geometry, creating spatial diversity.

The lower scan rate vs Windows is offset by higher signal quality — CoreWLAN returns calibrated dBm (not percentage) plus noise floor, enabling proper SNR computation.

1.4 Why Swift Subprocess (Not FFI)

The Command::new() + parse JSON pattern is proven — it's exactly what NetshBssidScanner does for Windows. The subprocess boundary also isolates Apple framework dependencies from the Rust build graph.

1.5 SOTA: Platform-Adaptive WiFi Sensing

Recent work validates multi-platform RSSI-based sensing:

• WiFind (2024): Cross-platform WiFi fingerprinting using RSSI vectors from heterogeneous hardware. Demonstrates that normalization across scan APIs (dBm, percentage, raw) is critical for model portability.
• WiGesture (2025): RSSI variance-based gesture recognition achieving 89% accuracy on commodity hardware with 15+ APs. Shows that temporal RSSI variance alone carries significant motion information.
• CrossSense (2024): Transfer learning from CSI-rich hardware to RSSI-only devices. Pre-trained signal features transfer with 78% effectiveness, validating multi-tier hardware strategy.

2. Decision

Implement a macOS CoreWLAN sensing adapter as a Swift helper binary + Rust adapter pair, following the established NetshBssidScanner subprocess pattern from ADR-022. Real RSSI data flows through the existing 8-stage WindowsWifiPipeline (which operates on BssidObservation structs regardless of platform origin).

2.1 Design Principles

1. Subprocess isolation — Swift binary is a standalone tool, built and versioned independently of the Rust workspace.
2. Same domain types — macOS adapter produces Vec<BssidObservation>, identical to the Windows path. All downstream processing reuses as-is.
3. SSID:channel as synthetic BSSID — When real BSSIDs are redacted (no Location Services), sha256(ssid + channel)[:12] generates a stable pseudo-BSSID. Documented limitation: same-SSID same-channel APs collapse to one observation.
4. #[cfg(target_os = "macos")] gating — macOS-specific code compiles only on macOS. Windows and Linux builds are unaffected.
5. Graceful degradation — If the Swift helper is not found or fails, --source auto skips macOS WiFi and falls back to simulated mode with a clear warning.

3. Architecture

3.1 Component Overview

┌─────────────────────────────────────────────────────────────────────┐
│                     macOS WiFi Sensing Path                         │
│                                                                     │
│  ┌──────────────────────┐     ┌───────────────────────────────────┐│
│  │  Swift Helper Binary  │     │  Rust Adapter + Existing Pipeline ││
│  │  (tools/macos-wifi-   │     │                                   ││
│  │   scan/main.swift)    │     │  MacosCoreWlanScanner             ││
│  │                       │     │       │                           ││
│  │  CWWiFiClient         │JSON │       ▼                           ││
│  │  scanForNetworks()  ──┼────►│  Vec<BssidObservation>            ││
│  │  interface()          │     │       │                           ││
│  │                       │     │       ▼                           ││
│  │  Outputs:             │     │  BssidRegistry                   ││
│  │  - ssid               │     │       │                           ││
│  │  - rssi (dBm)         │     │       ▼                           ││
│  │  - noise (dBm)        │     │  WindowsWifiPipeline (reused)    ││
│  │  - channel            │     │  [8-stage signal intelligence]   ││
│  │  - band (2.4/5/6)     │     │       │                           ││
│  │  - phy_mode           │     │       ▼                           ││
│  │  - bssid (if avail)   │     │  SensingUpdate → REST/WS         ││
│  └──────────────────────┘     └───────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘

3.2 Swift Helper Binary

File: rust-port/wifi-densepose-rs/tools/macos-wifi-scan/main.swift

// Modes:
//   (no args)    → Full scan, output JSON array to stdout
//   --probe      → Quick availability check, output {"available": true/false}
//   --connected  → Connected network info only
//
// Output schema (scan mode):
// [
//   {
//     "ssid": "MyNetwork",
//     "rssi": -52,
//     "noise": -90,
//     "channel": 36,
//     "band": "5GHz",
//     "phy_mode": "802.11ax",
//     "bssid": "aa:bb:cc:dd:ee:ff" | null,
//     "security": "wpa2_personal"
//   }
// ]

Build:

# Requires Xcode Command Line Tools (xcode-select --install)
cd tools/macos-wifi-scan
swiftc -framework CoreWLAN -framework Foundation -O -o macos-wifi-scan main.swift

Build script: tools/macos-wifi-scan/build.sh

3.3 Rust Adapter

File: crates/wifi-densepose-wifiscan/src/adapter/macos_scanner.rs

// #[cfg(target_os = "macos")]

pub struct MacosCoreWlanScanner {
    helper_path: PathBuf,  // Resolved at construction: $PATH or sibling of server binary
}

impl MacosCoreWlanScanner {
    pub fn new() -> Result<Self, WifiScanError>  // Finds helper or errors
    pub fn probe() -> bool                        // Runs --probe, returns availability
    pub fn scan_sync(&self) -> Result<Vec<BssidObservation>, WifiScanError>
    pub fn connected_sync(&self) -> Result<Option<BssidObservation>, WifiScanError>
}

Key mappings:

3.4 Sensing Server Integration

File: crates/wifi-densepose-sensing-server/src/main.rs

Auto-detection order (updated):

1. ESP32 UDP probe (port 5005)     → --source esp32
2. Windows netsh probe             → --source wifi (Windows)
3. macOS CoreWLAN probe  [NEW]     → --source wifi (macOS)
4. Simulated fallback              → --source simulated

3.5 Pipeline Reuse

The existing 8-stage WindowsWifiPipeline (ADR-022) operates entirely on BssidObservation / MultiApFrame types:

Limitation: CoreWLAN scan rate (~0.3-0.5 Hz) is significantly slower than netsh (~2 Hz). Breathing extraction (stage 5) will have reduced accuracy. Motion and presence detection remain effective since they depend on variance over longer windows.

4. Files

4.1 New Files

4.2 Modified Files

4.3 No New Rust Dependencies

• std::process::Command — subprocess spawning (stdlib)
• serde_json — JSON parsing (already in workspace)
• No changes to Cargo.toml

5. Verification Plan

All verification on Mac Mini (M2 Pro, macOS 26.3).

5.1 Swift Helper

5.2 Rust Adapter

5.3 End-to-End

5.4 Cross-Platform Regression

6. Limitations

7. Future Work

8. References

• Apple CoreWLAN Documentation
• CWWiFiClient — Primary WiFi interface API
• CWNetwork — Scan result type (SSID, RSSI, channel, noise)
• macOS 15 airport removal — Apple Developer Forums
• ADR-022: Windows WiFi Enhanced Fidelity (analogous platform adapter)
• ADR-013: Feature-Level Sensing from Commodity Gear
• Issue #56: macOS support request