wifi-controller 0.1.0__py3-none-any.whl

wifi_controller/__init__.py

@@ -0,0 +1,357 @@
+"""Cross-platform Wi-Fi controller with pluggable providers.
+
+Detects the current OS and registers known-good providers automatically.
+External code can register additional providers (e.g., a Swift-based scanner
+for macOS SSID redaction workarounds).
+
+Usage::
+
+    from wifi_controller import WiFiController
+
+    wifi = WiFiController()
+    ssid = wifi.get_current_ssid()
+    networks = wifi.scan()
+    wifi.connect("MyNetwork", "hunter2")
+    wifi.disconnect()
+
+    # Poll for a specific SSID
+    found = wifi.scan_for_ssid("TestAP 5678", timeout_sec=30)
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from bear_tools.lumberjack import Logger
+
+from wifi_controller._abc import (
+    CurrentSSIDProvider,
+    SSIDConnectProvider,
+    SSIDDisconnectProvider,
+    SSIDScanProvider,
+)
+from wifi_controller._linux import (
+    IwgetidCurrentSSID,
+    NmcliConnect,
+    NmcliCurrentSSID,
+    NmcliDisconnect,
+    NmcliScan,
+)
+from wifi_controller._macos import (
+    IpconfigCurrentSSID,
+    NetworkSetupConnect,
+    NetworkSetupCurrentSSID,
+    NetworkSetupDisconnect,
+    SystemProfilerScan,
+)
+from wifi_controller._types import SSIDInfo, WiFiConnectionError
+
+logger = Logger()
+
+__all__ = [
+    "WiFiController",
+    "SSIDInfo",
+    "WiFiConnectionError",
+    "CurrentSSIDProvider",
+    "SSIDScanProvider",
+    "SSIDConnectProvider",
+    "SSIDDisconnectProvider",
+]
+
+
+@dataclass
+class _RegisteredProvider:
+    provider: CurrentSSIDProvider | SSIDScanProvider | SSIDConnectProvider | SSIDDisconnectProvider
+    priority: int
+
+
+class WiFiController:
+    """Orchestrates Wi-Fi operations across pluggable, per-operation providers.
+
+    On construction, detects the OS and registers built-in providers that are
+    known to work on that platform/version.  If no provider is available for a
+    given operation, a warning is logged so the caller knows to register their
+    own.
+
+    :param interface: Network interface name.  Auto-detected if ``None``.
+    :param cache_path: Optional JSON file to persist provider selections across runs.
+    """
+
+    def __init__(
+        self,
+        interface: str | None = None,
+        cache_path: Path | None = None,
+    ) -> None:
+        self._current_providers: list[_RegisteredProvider] = []
+        self._scan_providers: list[_RegisteredProvider] = []
+        self._connect_providers: list[_RegisteredProvider] = []
+        self._disconnect_providers: list[_RegisteredProvider] = []
+
+        self._resolved_current: CurrentSSIDProvider | None = None
+        self._resolved_scan: SSIDScanProvider | None = None
+        self._resolved_connect: SSIDConnectProvider | None = None
+        self._resolved_disconnect: SSIDDisconnectProvider | None = None
+
+        self._cache_path = cache_path.expanduser() if cache_path else None
+        self._cache: dict[str, str] = {}
+        if self._cache_path and self._cache_path.exists():
+            try:
+                self._cache = json.loads(self._cache_path.read_text())
+            except (json.JSONDecodeError, OSError):
+                self._cache = {}
+
+        os_name = platform.system()
+        self._interface = interface or self._detect_interface(os_name)
+        self._os_name = os_name
+
+        self._setup_builtin_providers(os_name)
+
+    # -- Public properties --------------------------------------------------
+
+    @property
+    def platform_info(self) -> str:
+        """Human-readable OS + version string."""
+        ver = platform.mac_ver()[0]
+        if ver:
+            return f"macOS {ver} (Darwin)"
+        return f"{platform.system()} {platform.release()}"
+
+    @property
+    def interface_name(self) -> str:
+        """The network interface being used (e.g., ``en0``, ``wlan0``)."""
+        return self._interface
+
+    # -- Registration -------------------------------------------------------
+
+    def register_current_ssid_provider(self, provider: CurrentSSIDProvider, priority: int = 0) -> None:
+        self._current_providers.append(_RegisteredProvider(provider, priority))
+        self._resolved_current = None
+
+    def register_scan_provider(self, provider: SSIDScanProvider, priority: int = 0) -> None:
+        self._scan_providers.append(_RegisteredProvider(provider, priority))
+        self._resolved_scan = None
+
+    def register_connect_provider(self, provider: SSIDConnectProvider, priority: int = 0) -> None:
+        self._connect_providers.append(_RegisteredProvider(provider, priority))
+        self._resolved_connect = None
+
+    def register_disconnect_provider(self, provider: SSIDDisconnectProvider, priority: int = 0) -> None:
+        self._disconnect_providers.append(_RegisteredProvider(provider, priority))
+        self._resolved_disconnect = None
+
+    # -- Core operations ----------------------------------------------------
+
+    def get_current_ssid(self) -> str | None:
+        """Return the SSID of the currently-connected network, or ``None``."""
+        provider = self._resolve("current", self._current_providers, self._resolved_current)
+        self._resolved_current = provider  # type: ignore[assignment]
+        if provider is None:
+            logger.warning("No current-SSID provider registered. Call register_current_ssid_provider() first.")
+            return None
+        return provider.get_current_ssid(self._interface)  # type: ignore[union-attr]
+
+    def scan(self, timeout: int = 15) -> list[SSIDInfo]:
+        """Scan for nearby Wi-Fi networks."""
+        provider = self._resolve("scan", self._scan_providers, self._resolved_scan)
+        self._resolved_scan = provider  # type: ignore[assignment]
+        if provider is None:
+            logger.warning("No scan provider registered. Call register_scan_provider() first.")
+            return []
+        return provider.scan_ssids(self._interface, timeout)  # type: ignore[union-attr]
+
+    def connect(self, ssid: str, password: str, timeout: int = 15) -> None:
+        """Connect to a Wi-Fi network.
+
+        :raises WiFiConnectionError: on failure
+        """
+        # ── Already-connected guard ──────────────────────────────────────
+        # On macOS, calling CoreWLAN's CWInterface.associate(to:password:)
+        # when the adapter is *already* associated with the target SSID
+        # results in Apple80211 error -3925 ("tmpErr").  The error itself
+        # is harmless, but the failed associate causes macOS to briefly
+        # drop the WiFi link.  When a second network interface is active
+        # (e.g. Ethernet on en7, VPN on utun1), macOS re-evaluates its
+        # routing table during the dropout and may permanently re-route
+        # the camera's subnet (10.5.5.0/24) through the other interface.
+        # After that, Python's `requests` library (which uses BSD sockets
+        # and relies on the kernel routing table) gets [Errno 65] EHOSTUNREACH,
+        # while Apple's `curl` (which uses Network.framework with scoped
+        # routing and per-interface DNS) continues to work — leading to
+        # a confusing state where `is_reachable()` passes but every HTTP
+        # call from `requests` fails.
+        #
+        # The same issue applies to `networksetup -setairportnetwork`:
+        # re-running it on an already-connected SSID forces a full
+        # reassociation with the access point (~9 seconds), during which
+        # routing can shift to another interface.
+        #
+        # Fix: skip the connect entirely if we're already on the target.
+        # ────────────────────────────────────────────────────────────────
+        current = self.get_current_ssid()
+        if current == ssid:
+            logger.info(f"Already connected to '{ssid}', skipping connect")
+            return
+
+        provider = self._resolve("connect", self._connect_providers, self._resolved_connect)
+        self._resolved_connect = provider  # type: ignore[assignment]
+        if provider is None:
+            raise WiFiConnectionError("No connect provider registered")
+        provider.connect(ssid, password, self._interface, timeout)  # type: ignore[union-attr]
+
+    def disconnect(self) -> None:
+        """Disconnect from the current Wi-Fi network."""
+        provider = self._resolve("disconnect", self._disconnect_providers, self._resolved_disconnect)
+        self._resolved_disconnect = provider  # type: ignore[assignment]
+        if provider is None:
+            logger.warning("No disconnect provider registered.")
+            return
+        provider.disconnect(self._interface)  # type: ignore[union-attr]
+
+    # -- Convenience methods ------------------------------------------------
+
+    def scan_for_ssid(self, ssid: str, timeout_sec: float = 20.0, invert: bool = False) -> bool:
+        """Poll ``scan()`` until *ssid* is found (or confirmed absent if *invert* is True).
+
+        :param ssid: The SSID to look for.
+        :param timeout_sec: Total time to keep trying (seconds).
+        :param invert: If True, return True only if the SSID is **not** found after the timeout.
+        :return: True if the SSID was found (or not found when *invert* is True).
+        """
+        logger.info(f'Scanning for SSID: "{ssid}" (timeout: {timeout_sec:.2f} seconds)')
+        start = time.perf_counter()
+        while time.perf_counter() - start <= timeout_sec:
+            networks = self.scan(timeout=5)
+            found = any(n.ssid == ssid for n in networks)
+            if found and not invert:
+                return True
+            if not found and invert:
+                return True
+            time.sleep(1.0)
+        return invert
+
+    def is_connected(self) -> bool:
+        """Return True if connected to any Wi-Fi network."""
+        return self.get_current_ssid() is not None
+
+    def is_wifi_enabled(self) -> bool:
+        """Check whether the system's Wi-Fi adapter is powered on."""
+        if self._os_name == "Darwin":
+            try:
+                out = subprocess.check_output(
+                    ["networksetup", "-getairportpower", self._interface],
+                    text=True,
+                    timeout=5,
+                )
+                return "On" in out
+            except (OSError, subprocess.SubprocessError):
+                return True  # assume on if we can't check
+        if self._os_name == "Linux":
+            try:
+                out = subprocess.check_output(["nmcli", "radio", "wifi"], text=True, timeout=5)
+                return "enabled" in out.lower()
+            except (OSError, subprocess.SubprocessError):
+                return True
+        return True  # unknown platform -- assume on
+
+    # -- Internal -----------------------------------------------------------
+
+    @staticmethod
+    def _detect_interface(os_name: str) -> str:
+        if os_name == "Darwin":
+            return "en0"
+        if os_name == "Linux":
+            try:
+                for p in sorted(Path("/sys/class/net").iterdir()):
+                    if (p / "wireless").exists():
+                        return p.name
+            except OSError:
+                pass
+            return "wlan0"
+        return "Wi-Fi"  # Windows default
+
+    def _setup_builtin_providers(self, os_name: str) -> None:
+        if os_name == "Darwin":
+            self._setup_macos()
+        elif os_name == "Linux":
+            self._setup_linux()
+        else:
+            logger.warning(f"Unsupported platform: {os_name}. No Wi-Fi providers registered.")
+
+    def _setup_macos(self) -> None:
+        major = _macos_major()
+
+        if major <= 14:
+            self.register_current_ssid_provider(NetworkSetupCurrentSSID(), priority=0)
+            self.register_scan_provider(SystemProfilerScan(), priority=0)
+        else:
+            self.register_current_ssid_provider(IpconfigCurrentSSID(), priority=0)
+            logger.warning(
+                f"No built-in SSID scan provider for macOS {platform.mac_ver()[0]}. "
+                "SSIDs are redacted by the OS. Register a scan provider "
+                "(e.g., SwiftSsidScanner from extras/) to enable scanning."
+            )
+
+        self.register_connect_provider(NetworkSetupConnect(), priority=0)
+        self.register_disconnect_provider(NetworkSetupDisconnect(), priority=0)
+
+    def _setup_linux(self) -> None:
+        has_nmcli = NmcliCurrentSSID().is_available()
+        has_iwgetid = IwgetidCurrentSSID().is_available()
+
+        if has_nmcli:
+            self.register_current_ssid_provider(NmcliCurrentSSID(), priority=10)
+            self.register_scan_provider(NmcliScan(), priority=0)
+            self.register_connect_provider(NmcliConnect(), priority=0)
+            self.register_disconnect_provider(NmcliDisconnect(), priority=0)
+        if has_iwgetid:
+            self.register_current_ssid_provider(IwgetidCurrentSSID(), priority=0)
+
+        if not has_nmcli and not has_iwgetid:
+            logger.warning(
+                "No supported WiFi manager found on Linux. "
+                "Install NetworkManager (nmcli) or wireless-tools (iwgetid)."
+            )
+
+    def _resolve(
+        self,
+        operation: str,
+        registry: list[_RegisteredProvider],
+        cached_instance: CurrentSSIDProvider | SSIDScanProvider | SSIDConnectProvider | SSIDDisconnectProvider | None,
+    ) -> CurrentSSIDProvider | SSIDScanProvider | SSIDConnectProvider | SSIDDisconnectProvider | None:
+        if cached_instance is not None:
+            return cached_instance
+
+        # Try to restore from disk cache
+        cached_name = self._cache.get(operation)
+        if cached_name:
+            for entry in registry:
+                if entry.provider.name == cached_name:
+                    return entry.provider
+
+        # Discovery: try providers in descending priority order
+        for entry in sorted(registry, key=lambda e: e.priority, reverse=True):
+            if entry.provider.is_available():
+                self._cache[operation] = entry.provider.name
+                self._write_cache()
+                return entry.provider
+
+        return None
+
+    def _write_cache(self) -> None:
+        if self._cache_path is None:
+            return
+        try:
+            self._cache_path.parent.mkdir(parents=True, exist_ok=True)
+            self._cache_path.write_text(json.dumps(self._cache, indent=2) + "\n")
+        except OSError:
+            pass
+
+
+def _macos_major() -> int:
+    ver = platform.mac_ver()[0]
+    return int(ver.split(".")[0]) if ver else 0

wifi_controller/_abc.py

@@ -0,0 +1,66 @@
+"""Abstract base classes for Wi-Fi provider plugins."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from wifi_controller._types import SSIDInfo
+
+
+class CurrentSSIDProvider(ABC):
+    """Can retrieve the SSID of the currently-connected network."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def is_available(self) -> bool: ...
+
+    @abstractmethod
+    def get_current_ssid(self, interface: str) -> str | None: ...
+
+
+class SSIDScanProvider(ABC):
+    """Can scan for nearby Wi-Fi networks and return real (non-redacted) SSIDs."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def is_available(self) -> bool: ...
+
+    @abstractmethod
+    def scan_ssids(self, interface: str, timeout: int = 15) -> list[SSIDInfo]: ...
+
+
+class SSIDConnectProvider(ABC):
+    """Can connect to a Wi-Fi network given SSID and password.
+
+    :raises WiFiConnectionError: on failure
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def is_available(self) -> bool: ...
+
+    @abstractmethod
+    def connect(self, ssid: str, password: str, interface: str, timeout: int = 15) -> None: ...
+
+
+class SSIDDisconnectProvider(ABC):
+    """Can disconnect from the current Wi-Fi network."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def is_available(self) -> bool: ...
+
+    @abstractmethod
+    def disconnect(self, interface: str) -> None: ...

wifi_controller/_linux.py

@@ -0,0 +1,170 @@
+"""Built-in Linux Wi-Fi providers (nmcli, iwgetid)."""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+import subprocess
+
+from wifi_controller._abc import (
+    CurrentSSIDProvider,
+    SSIDConnectProvider,
+    SSIDDisconnectProvider,
+    SSIDScanProvider,
+)
+from wifi_controller._types import SSIDInfo, WiFiConnectionError
+
+
+def _has_nmcli() -> bool:
+    return shutil.which("nmcli") is not None
+
+
+def _has_iwgetid() -> bool:
+    return shutil.which("iwgetid") is not None
+
+
+class NmcliCurrentSSID(CurrentSSIDProvider):
+    """``nmcli`` -- active SSID on Linux with NetworkManager."""
+
+    @property
+    def name(self) -> str:
+        return "nmcli"
+
+    def is_available(self) -> bool:
+        return _has_nmcli()
+
+    def get_current_ssid(self, interface: str) -> str | None:
+        try:
+            output = subprocess.check_output(
+                ["nmcli", "-t", "-f", "active,ssid", "dev", "wifi"],
+                text=True,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+        for line in output.splitlines():
+            if line.startswith("yes:"):
+                ssid = line.split(":", 1)[1]
+                return ssid if ssid else None
+        return None
+
+
+class NmcliScan(SSIDScanProvider):
+    """``nmcli dev wifi list`` -- scan nearby networks on Linux."""
+
+    @property
+    def name(self) -> str:
+        return "nmcli"
+
+    def is_available(self) -> bool:
+        return _has_nmcli()
+
+    def scan_ssids(self, interface: str, timeout: int = 15) -> list[SSIDInfo]:
+        try:
+            # Trigger a fresh scan
+            subprocess.run(
+                ["nmcli", "dev", "wifi", "rescan", "ifname", interface],
+                capture_output=True,
+                timeout=timeout,
+            )
+            output = subprocess.check_output(
+                ["nmcli", "-t", "-f", "ssid,bssid,signal,freq", "dev", "wifi", "list", "ifname", interface],
+                text=True,
+                timeout=timeout,
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+            return []
+
+        results: list[SSIDInfo] = []
+        seen: set[str] = set()
+        for line in output.splitlines():
+            parts = line.split(":")
+            if len(parts) < 4:
+                continue
+            ssid = parts[0]
+            if not ssid or ssid in seen:
+                continue
+            seen.add(ssid)
+            bssid = ":".join(parts[1:7]) if len(parts) >= 7 else parts[1]
+            try:
+                signal = int(parts[-2]) if len(parts) >= 4 else 0
+                freq = int(parts[-1]) if len(parts) >= 4 else 0
+            except ValueError:
+                signal, freq = 0, 0
+            # nmcli reports signal as 0-100%; approximate dBm
+            rssi = signal - 100 if signal else 0
+            channel = _freq_to_channel(freq)
+            results.append(SSIDInfo(ssid=ssid, bssid=bssid, rssi=rssi, channel=channel))
+        return results
+
+
+class NmcliConnect(SSIDConnectProvider):
+    """``nmcli dev wifi connect`` -- connect on Linux with NetworkManager."""
+
+    @property
+    def name(self) -> str:
+        return "nmcli"
+
+    def is_available(self) -> bool:
+        return _has_nmcli()
+
+    def connect(self, ssid: str, password: str, interface: str, timeout: int = 15) -> None:
+        try:
+            result = subprocess.run(
+                ["nmcli", "dev", "wifi", "connect", ssid, "password", password, "ifname", interface],
+                capture_output=True,
+                text=True,
+                timeout=timeout + 15,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError) as exc:
+            raise WiFiConnectionError(f"nmcli failed for '{ssid}': {exc}") from exc
+        if result.returncode != 0:
+            stderr = result.stderr.strip() or result.stdout.strip()
+            raise WiFiConnectionError(f"nmcli failed for '{ssid}': {stderr}")
+
+
+class NmcliDisconnect(SSIDDisconnectProvider):
+    """``nmcli dev disconnect`` -- disconnect on Linux."""
+
+    @property
+    def name(self) -> str:
+        return "nmcli"
+
+    def is_available(self) -> bool:
+        return _has_nmcli()
+
+    def disconnect(self, interface: str) -> None:
+        with contextlib.suppress(subprocess.TimeoutExpired, FileNotFoundError):
+            subprocess.run(
+                ["nmcli", "dev", "disconnect", interface],
+                capture_output=True,
+                timeout=10,
+            )
+
+
+class IwgetidCurrentSSID(CurrentSSIDProvider):
+    """``iwgetid -r`` -- get current SSID on Linux without NetworkManager."""
+
+    @property
+    def name(self) -> str:
+        return "iwgetid"
+
+    def is_available(self) -> bool:
+        return _has_iwgetid()
+
+    def get_current_ssid(self, interface: str) -> str | None:
+        try:
+            output = subprocess.check_output(["iwgetid", "-r", interface], text=True).strip()
+            return output if output else None
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+
+
+def _freq_to_channel(freq_mhz: int) -> int:
+    """Convert Wi-Fi frequency in MHz to channel number."""
+    if 2412 <= freq_mhz <= 2484:
+        if freq_mhz == 2484:
+            return 14
+        return (freq_mhz - 2412) // 5 + 1
+    if 5170 <= freq_mhz <= 5825:
+        return (freq_mhz - 5170) // 5 + 34
+    return 0

wifi_controller/_macos.py

@@ -0,0 +1,164 @@
+"""Built-in macOS Wi-Fi providers."""
+
+from __future__ import annotations
+
+import platform
+import re
+import subprocess
+
+from bear_tools.lumberjack import Logger
+
+from wifi_controller._abc import (
+    CurrentSSIDProvider,
+    SSIDConnectProvider,
+    SSIDDisconnectProvider,
+    SSIDScanProvider,
+)
+from wifi_controller._types import SSIDInfo, WiFiConnectionError
+
+logger = Logger()
+
+
+def _macos_major_version() -> int:
+    ver = platform.mac_ver()[0]
+    return int(ver.split(".")[0]) if ver else 0
+
+
+class NetworkSetupCurrentSSID(CurrentSSIDProvider):
+    """``networksetup -getairportnetwork`` -- works on macOS <= 14."""
+
+    @property
+    def name(self) -> str:
+        return "networksetup"
+
+    def is_available(self) -> bool:
+        return _macos_major_version() <= 14
+
+    def get_current_ssid(self, interface: str) -> str | None:
+        try:
+            output = subprocess.check_output(
+                ["networksetup", "-getairportnetwork", interface],
+            ).decode()
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+        prefix = "Current Wi-Fi Network: "
+        if prefix in output:
+            return output.replace(prefix, "").strip()
+        return None
+
+
+class IpconfigCurrentSSID(CurrentSSIDProvider):
+    """``ipconfig getsummary`` -- works on macOS 15+ (requires ``sudo ipconfig setverbose 1`` once)."""
+
+    @property
+    def name(self) -> str:
+        return "ipconfig"
+
+    def is_available(self) -> bool:
+        return _macos_major_version() >= 15
+
+    def get_current_ssid(self, interface: str) -> str | None:
+        try:
+            output = subprocess.check_output(["ipconfig", "getsummary", interface]).decode()
+            regex = r"\n\s+SSID : ([\x20-\x7E]{1,32})(?=\n)"
+            match = re.search(regex, output)
+            return match.group(1) if match else None
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+
+
+class SystemProfilerScan(SSIDScanProvider):
+    """``system_profiler SPAirPortDataType`` -- works on macOS <= 14 (SSIDs redacted on 15+)."""
+
+    @property
+    def name(self) -> str:
+        return "system_profiler"
+
+    def is_available(self) -> bool:
+        return _macos_major_version() <= 14
+
+    def scan_ssids(self, interface: str, timeout: int = 15) -> list[SSIDInfo]:
+        try:
+            output = subprocess.check_output(["/usr/sbin/system_profiler", "SPAirPortDataType"]).decode()
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return []
+        regex = re.compile(r"\n\s+([\x20-\x7E]{1,32}):\n\s+PHY Mode:")
+        return [
+            SSIDInfo(ssid=ssid, bssid="", rssi=0, channel=0)
+            for ssid in sorted(set(regex.findall(output)))
+        ]
+
+
+class NetworkSetupConnect(SSIDConnectProvider):
+    """``networksetup -setairportnetwork`` -- works on all macOS versions with explicit password."""
+
+    @property
+    def name(self) -> str:
+        return "networksetup"
+
+    def is_available(self) -> bool:
+        return platform.system() == "Darwin"
+
+    def connect(self, ssid: str, password: str, interface: str, timeout: int = 15) -> None:
+        # ── Already-connected guard ──────────────────────────────────
+        # `networksetup -setairportnetwork` forces a full 802.11
+        # reassociation even when already on the target SSID (~9 sec).
+        # During reassociation, macOS may re-route the camera's
+        # 10.5.5.0/24 subnet through Ethernet/VPN if a second
+        # interface is active, breaking Python BSD-socket traffic.
+        # See WiFiController.connect() for the full explanation.
+        # ─────────────────────────────────────────────────────────────
+        current = self._get_current_ssid(interface)
+        if current == ssid:
+            logger.info(f"Already connected to '{ssid}', skipping networksetup")
+            return
+
+        try:
+            result = subprocess.run(
+                ["networksetup", "-setairportnetwork", interface, ssid, password],
+                capture_output=True,
+                text=True,
+                timeout=timeout + 15,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError) as exc:
+            raise WiFiConnectionError(f"networksetup failed for '{ssid}': {exc}") from exc
+        if result.stdout.strip():
+            raise WiFiConnectionError(f"networksetup failed for '{ssid}': {result.stdout.strip()}")
+
+    @staticmethod
+    def _get_current_ssid(interface: str) -> str | None:
+        """Quick SSID check via ipconfig (works on macOS 15+)."""
+        try:
+            output = subprocess.check_output(
+                ["ipconfig", "getsummary", interface], text=True, timeout=5,
+            )
+            match = re.search(r"\n\s+SSID : ([\x20-\x7E]{1,32})(?=\n)", output)
+            return match.group(1) if match else None
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+            return None
+
+
+class NetworkSetupDisconnect(SSIDDisconnectProvider):
+    """``networksetup -setairportpower`` off/on to disconnect."""
+
+    @property
+    def name(self) -> str:
+        return "networksetup"
+
+    def is_available(self) -> bool:
+        return platform.system() == "Darwin"
+
+    def disconnect(self, interface: str) -> None:
+        try:
+            subprocess.run(
+                ["networksetup", "-setairportpower", interface, "off"],
+                capture_output=True,
+                timeout=10,
+            )
+            subprocess.run(
+                ["networksetup", "-setairportpower", interface, "on"],
+                capture_output=True,
+                timeout=10,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            pass

wifi_controller/_swift.py

@@ -0,0 +1,197 @@
+"""Wi-Fi providers backed by the Swift ``ssid_scanner`` binary.
+
+These providers shell out to the signed macOS app bundle that uses
+CoreWLAN + CoreLocation to bypass macOS SSID redaction (macOS 15+).
+
+The Swift source lives in ``extras/ssid_scanner/`` and must be built
+separately (``make -C extras/ssid_scanner``). The Python wrappers here
+ship on PyPI and gracefully report ``is_available() -> False`` when the
+binary is not present.
+
+Usage::
+
+    from wifi_controller import WiFiController
+    from wifi_controller._swift import (
+        SwiftSsidScannerCurrentSSID,
+        SwiftSsidScannerScan,
+        SwiftSsidScannerConnect,
+        SwiftSsidScannerDisconnect,
+    )
+
+    ctrl = WiFiController()
+    binary = "/path/to/ssid_scanner"
+    ctrl.register_current_ssid_provider(SwiftSsidScannerCurrentSSID(binary), priority=10)
+    ctrl.register_scan_provider(SwiftSsidScannerScan(binary), priority=10)
+    ctrl.register_connect_provider(SwiftSsidScannerConnect(binary), priority=10)
+    ctrl.register_disconnect_provider(SwiftSsidScannerDisconnect(binary), priority=10)
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from bear_tools.lumberjack import Logger
+
+from wifi_controller._abc import (
+    CurrentSSIDProvider,
+    SSIDConnectProvider,
+    SSIDDisconnectProvider,
+    SSIDScanProvider,
+)
+from wifi_controller._types import SSIDInfo, WiFiConnectionError
+
+logger = Logger()
+
+
+class SwiftSsidScannerCurrentSSID(CurrentSSIDProvider):
+    """Retrieve the current SSID via ``ssid_scanner --current``."""
+
+    def __init__(self, binary: str | Path) -> None:
+        self._binary = str(binary)
+
+    @property
+    def name(self) -> str:
+        return "swift_ssid_scanner"
+
+    def is_available(self) -> bool:
+        return Path(self._binary).is_file()
+
+    def get_current_ssid(self, interface: str = "en0") -> str | None:
+        try:
+            result = subprocess.run(
+                [self._binary, "--current"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            return None
+        if result.returncode != 0:
+            return None
+        ssid = result.stdout.strip()
+        return ssid if ssid else None
+
+
+class SwiftSsidScannerScan(SSIDScanProvider):
+    """Scan nearby networks via ``ssid_scanner --scan --json``."""
+
+    def __init__(self, binary: str | Path) -> None:
+        self._binary = str(binary)
+
+    @property
+    def name(self) -> str:
+        return "swift_ssid_scanner"
+
+    def is_available(self) -> bool:
+        return Path(self._binary).is_file()
+
+    def scan_ssids(self, interface: str = "en0", timeout: int = 15) -> list[SSIDInfo]:
+        try:
+            result = subprocess.run(
+                [self._binary, "--scan", "--json", "--timeout", str(timeout)],
+                capture_output=True,
+                text=True,
+                timeout=timeout + 30,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            return []
+        if result.returncode != 0:
+            return []
+        try:
+            raw: list[dict[str, str | int]] = json.loads(result.stdout)
+        except (json.JSONDecodeError, ValueError):
+            return []
+        return [
+            SSIDInfo(
+                ssid=str(entry.get("ssid", "")),
+                bssid=str(entry.get("bssid", "")),
+                rssi=int(entry.get("rssi", 0)),
+                channel=int(entry.get("channel", 0)),
+            )
+            for entry in raw
+        ]
+
+
+class SwiftSsidScannerConnect(SSIDConnectProvider):
+    """Connect to a network via ``ssid_scanner --connect``."""
+
+    def __init__(self, binary: str | Path) -> None:
+        self._binary = str(binary)
+
+    @property
+    def name(self) -> str:
+        return "swift_ssid_scanner"
+
+    def is_available(self) -> bool:
+        return Path(self._binary).is_file()
+
+    def connect(self, ssid: str, password: str, interface: str = "en0", timeout: int = 15) -> None:
+        # ── Already-connected guard ──────────────────────────────────
+        # CoreWLAN's CWInterface.associate(to:password:) fails with
+        # Apple80211 error -3925 when already on the target SSID.
+        # The failed associate drops the WiFi link momentarily, which
+        # causes macOS to re-route the camera's 10.5.5.0/24 subnet
+        # through another interface (Ethernet, VPN) if one exists.
+        # Python `requests` then gets EHOSTUNREACH while `curl` still
+        # works (Network.framework vs BSD sockets).  See the detailed
+        # comment in WiFiController.connect() for the full explanation.
+        # ─────────────────────────────────────────────────────────────
+        current = self._get_current_ssid()
+        if current == ssid:
+            logger.info(f"Already connected to '{ssid}', skipping ssid_scanner --connect")
+            return
+
+        try:
+            result = subprocess.run(
+                [self._binary, "--connect", ssid, password, "--timeout", str(timeout)],
+                capture_output=True,
+                text=True,
+                timeout=timeout + 30,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise WiFiConnectionError(f"ssid_scanner timed out connecting to '{ssid}'") from exc
+        except (FileNotFoundError, OSError) as exc:
+            raise WiFiConnectionError(f"ssid_scanner binary not found: {self._binary}") from exc
+        if result.returncode != 0:
+            stderr = result.stderr.strip()
+            raise WiFiConnectionError(f"ssid_scanner failed to connect to '{ssid}': {stderr}")
+
+    def _get_current_ssid(self) -> str | None:
+        """Quick check via ``ssid_scanner --current``."""
+        try:
+            result = subprocess.run(
+                [self._binary, "--current"],
+                capture_output=True, text=True, timeout=10,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            return None
+        return result.stdout.strip() or None if result.returncode == 0 else None
+
+
+class SwiftSsidScannerDisconnect(SSIDDisconnectProvider):
+    """Disconnect from the current network via ``ssid_scanner --disconnect``."""
+
+    def __init__(self, binary: str | Path) -> None:
+        self._binary = str(binary)
+
+    @property
+    def name(self) -> str:
+        return "swift_ssid_scanner"
+
+    def is_available(self) -> bool:
+        return Path(self._binary).is_file()
+
+    def disconnect(self, interface: str = "en0") -> None:
+        try:
+            result = subprocess.run(
+                [self._binary, "--disconnect"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            return  # best-effort
+        if result.returncode != 0:
+            logger.warning(f"ssid_scanner --disconnect failed: {result.stderr.strip()}")

wifi_controller/_types.py

@@ -0,0 +1,19 @@
+"""Data types for the wifi_controller package."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SSIDInfo:
+    """Information about a discovered Wi-Fi network."""
+
+    ssid: str
+    bssid: str
+    rssi: int
+    channel: int
+
+
+class WiFiConnectionError(Exception):
+    """Raised when a Wi-Fi connect operation fails."""

wifi_controller-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jugglingbear
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wifi_controller-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.3
+Name: wifi-controller
+Version: 0.1.0
+Summary: Cross-platform Wi-Fi controller with pluggable providers for macOS, Linux, and Windows.
+License: MIT
+Keywords: wifi,wireless,macos,linux,network
+Author: jugglingbear
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Requires-Dist: bear-tools (>=0.1.37,<0.2.0)
+Project-URL: Homepage, https://github.com/jugglingbear/wifi_controller
+Project-URL: Repository, https://github.com/jugglingbear/wifi_controller
+Description-Content-Type: text/markdown
+
+# wifi-controller
+
+A cross-platform Wi-Fi controller for Python with pluggable provider architecture.
+Supports macOS and Linux out of the box, with an optional Swift-based scanner for
+macOS 15+ where Apple redacts SSIDs without Location Services authorization.
+
+## Features
+
+- **Cross-platform** -- built-in providers for macOS (`networksetup`, `ipconfig`,
+  `system_profiler`) and Linux (`nmcli`, `iwgetid`)
+- **Pluggable providers** -- register your own scan/connect/disconnect implementations
+  with priority-based resolution
+- **macOS SSID redaction workaround** -- optional Swift scanner (`extras/ssid_scanner/`)
+  uses CoreWLAN + CoreLocation to return real SSIDs on macOS 15+
+- **Zero dependencies** -- pure Python, stdlib only
+
+## Installation
+
+```bash
+pip install wifi-controller
+```
+
+Or with Poetry:
+
+```bash
+poetry add wifi-controller
+```
+
+## Quick Start
+
+```python
+from wifi_controller import WiFiController
+
+wifi = WiFiController()
+
+# Get current network
+ssid = wifi.get_current_ssid()
+print(f"Connected to: {ssid}")
+
+# Scan nearby networks
+networks = wifi.scan()
+for net in networks:
+    print(f"  {net.ssid} (RSSI={net.rssi}, CH={net.channel})")
+
+# Connect to a network
+wifi.connect("MyNetwork", "hunter2")
+
+# Poll for a specific SSID
+found = wifi.scan_for_ssid("MyNetwork", timeout_sec=30)
+
+# Disconnect
+wifi.disconnect()
+```
+
+## macOS 15+ SSID Redaction
+
+Starting with macOS 15 (Sequoia), Apple redacts SSID information from
+`system_profiler`, `CoreWLAN`, and other system APIs unless the calling process
+has Location Services authorization via a signed app bundle.
+
+The built-in Python providers **cannot** work around this limitation. To get
+real SSIDs on macOS 15+, build the Swift scanner from `extras/ssid_scanner/`:
+
+```bash
+# Prerequisites: Xcode Command Line Tools + Apple Development certificate
+make -C extras/ssid_scanner check   # verify prerequisites
+make -C extras/ssid_scanner all     # build and sign
+```
+
+Then register the Swift providers:
+
+```python
+from wifi_controller import WiFiController
+from wifi_controller._swift import (
+    SwiftSsidScannerCurrentSSID,
+    SwiftSsidScannerScan,
+    SwiftSsidScannerConnect,
+    SwiftSsidScannerDisconnect,
+)
+
+wifi = WiFiController()
+binary = "extras/ssid_scanner/ssid_scanner"  # path to built binary
+
+wifi.register_scan_provider(SwiftSsidScannerScan(binary), priority=10)
+wifi.register_current_ssid_provider(SwiftSsidScannerCurrentSSID(binary), priority=10)
+wifi.register_connect_provider(SwiftSsidScannerConnect(binary), priority=10)
+wifi.register_disconnect_provider(SwiftSsidScannerDisconnect(binary), priority=10)
+
+# Now scan() returns real SSIDs on macOS 15+
+networks = wifi.scan()
+```
+
+## Custom Providers
+
+Implement any of the four provider ABCs to add support for additional tools:
+
+```python
+from wifi_controller import WiFiController, SSIDScanProvider, SSIDInfo
+
+class MyCustomScanner(SSIDScanProvider):
+    @property
+    def name(self) -> str:
+        return "my_scanner"
+
+    def is_available(self) -> bool:
+        return True  # check if your tool is installed
+
+    def scan_ssids(self, interface: str, timeout: int = 15) -> list[SSIDInfo]:
+        # ... your implementation ...
+        return [SSIDInfo(ssid="Example", bssid="00:11:22:33:44:55", rssi=-42, channel=6)]
+
+wifi = WiFiController()
+wifi.register_scan_provider(MyCustomScanner(), priority=20)
+```
+
+Provider ABCs:
+
+| ABC | Operation |
+|-----|-----------|
+| `CurrentSSIDProvider` | Get the currently-connected SSID |
+| `SSIDScanProvider` | Scan for nearby networks |
+| `SSIDConnectProvider` | Connect to a network (SSID + password) |
+| `SSIDDisconnectProvider` | Disconnect from the current network |
+
+Higher priority providers are tried first. The first provider whose
+`is_available()` returns `True` is used and cached for subsequent calls.
+
+## Project Layout
+
+```
+wifi_controller/
+├── src/wifi_controller/       # Python package (ships on PyPI)
+│   ├── __init__.py            # WiFiController orchestrator
+│   ├── _types.py              # SSIDInfo, WiFiConnectionError
+│   ├── _abc.py                # Four provider ABCs
+│   ├── _macos.py              # Built-in macOS providers
+│   ├── _linux.py              # Built-in Linux providers
+│   └── _swift.py              # Python wrappers for Swift binary
+├── extras/ssid_scanner/       # Swift source (not on PyPI, clone to use)
+│   ├── scan.swift             # CoreWLAN + CoreLocation scanner
+│   ├── Makefile               # Build, sign, test
+│   └── *.plist                # App bundle configuration
+├── docs/                      # Architecture diagrams (PlantUML)
+└── tests/                     # Unit tests
+```
+
+## Architecture
+
+See [docs/](docs/) for PlantUML diagrams covering:
+
+- **Class diagram** -- provider ABCs, WiFiController, built-in implementations
+- **Sequence diagram** -- provider resolution and operation flow
+- **Component diagram** -- package structure and platform boundaries
+
+## Development
+
+```bash
+# Install dev dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Lint
+poetry run ruff check src/ tests/
+
+# Format
+poetry run ruff format src/ tests/
+```
+
+## License
+
+MIT -- see [LICENSE](LICENSE).
+
+

wifi_controller-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+wifi_controller/__init__.py,sha256=-RqcD_bk2jF2uvSn5lO79V-ujCxJbY86uaB75JPgq7M,14605
+wifi_controller/_abc.py,sha256=CNLxWdVGTISu_te0N1IOKQUvvb83SbZSPBPbeLgSALA,1525
+wifi_controller/_linux.py,sha256=4zr--scPVbS5GehOGq8eg6z1n1qabEPIcmpHr_WDwXo,5395
+wifi_controller/_macos.py,sha256=JQOYvM98Qzwx0shBRjAXP3w5m6km1PyCs_PHfHf9orc,5929
+wifi_controller/_swift.py,sha256=HW3MFIvFh1D8IguffYnHPoqev-bnBrNKswyPboPNBWY,7198
+wifi_controller/_types.py,sha256=P2b0dhKtNIQoObY1mPzDqMKvDp1Md3kIKEUj3bHeFaQ,375
+wifi_controller/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wifi_controller-0.1.0.dist-info/LICENSE,sha256=aMnS8mxT3JGjIuC2HpDrjqM4RTPPx5PKdp4DML5r9cM,1069
+wifi_controller-0.1.0.dist-info/METADATA,sha256=jO9ow3U4iCJlDObLA4W3Wxb6BvBavGwsUS9_hlqF-2A,6245
+wifi_controller-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+wifi_controller-0.1.0.dist-info/RECORD,,

wifi_controller-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any