Make Wi-Fi join/leave actually functional

wifi.py presented itself as a join/leave abstraction but provided no real
behavior: the default backend was a no-op, the facade never verified the
association, and the nmcli queries were wrong. This makes the module do what
it claims, verified end-to-end against the recovered protocol and nmcli 1.52.

wifi.py
  - WifiManager: join now verifies the association by polling
    backend.is_connected against a settle_timeout (fail-closed). An
    unverified join raises HotspotJoinError and leaves connected=False;
    verify=False restores fire-and-forget. Tracks last_profile and adds
    gateway_ip().
  - NmcliWifiBackend: the association check now uses the ACTIVE column
    (`device wifi list -f SSID,ACTIVE`). The old `device wifi show` was a
    prefix-match accident onto `show-password` and reported in-range APs, not
    the associated one. get_ip() queries per-Wi-Fi-interface IP4.ADDRESS
    (preferring the 10.100 aGate subnet) instead of the unfiltered all-device
    dump that would return a wired/VPN address. Signal is read from the active
    AP; the dead ipcmd param is removed; leave() is best-effort.
  - WifiBackend: documented the fail-closed contract and added get_signal()
    so the manager no longer reaches into a private _run via isinstance.
  - NoOpWifiBackend: added assume_connected() for manual/external joins.

client.py
  - AgateClient now owns a WifiManager and exposes join_hotspot(),
    leave_hotspot(), and attach_local() (join + verify + LocalDeviceClient
    aimed at the device gateway). LocalDeviceClient is imported lazily so the
    package still works without `requests`.

__init__.py
  - Export the backends, HotspotProfile, HotspotJoinError, the SN-derivation
    helper, and the module constants.

tests/test_wifi.py (new)
  - 20 stdlib-unittest cases: SN derivation, verify pass/fail, fail-closed
    behavior, the in-range-but-not-associated regression, IP preference,
    tolerant leave, and the client wiring. No radio or pytest required.

Also:
  - README: documented the local-connect (device hotspot) flow.
  - .gitignore: ignore Python build/cache artifacts.

franklinwh_agate_client/wifi.py

@@ -7,25 +7,34 @@ and ``com.alternadom.wifiiot.WifiIotPlugin`` (Java side, ``base.apk``) — see
 The app joins the **device SoftAP** so that the phone can talk to the aGate
 over its local HTTP/socket interfaces (gateway ``10.100.1.1``).
 
-Credential derivation (confirmed from the disassembly, 20-char SN rule)::
+How this module maps onto that::
 
-    ssid = "AP_" + sn[11:]          pwd = sn[8:]
-    else (invalid length)
-    ssid = "AP_" + sn               pwd = "12345678"
+    * credential derivation (``derive_hotspot_credentials``) — faithful
+      reconstruction of ``getDeviceApSsid`` / ``getDeviceApDefaultPwd`` (§10).
+    * the association itself (``WifiBackend.join`` / ``leave``) — platform
+      work.  :class:`NmcliWifiBackend` drives NetworkManager on a Linux
+      desktop/laptop; :class:`NoOpWifiBackend` records state only, for
+      hosts whose own tooling owns the radio (containers, manual joins).
+    * ``WifiManager`` — the facade that makes the join *functional*:
+      derive → join → **verify** (poll ``is_connected`` against a deadline,
+      fail-closed) → expose our IP and the device gateway.
 
-Actual joining is delegated to a :class:`WifiBackend` so this module stays
-testable without a radio.  On a Linux desktop/laptop use
-:class:`NmcliWifiBackend` (NetworkManager); in a container or when joining
-manually use :class:`NoOpWifiBackend`.
+Note on the app's *other* "wifi" operations: ``connectWifi`` (0x0f) and the
+ESP-provisioning/onboarding flow (§4, §9) provision the **device** with a
+home router — they are device-side RPCs (see ``LocalDeviceClient`` /
+``CommunicationCmd``), not host-radio actions.  The compat shims here
+(``query_connect_wifi`` / ``wifi_onboarding_add_wifi``) only perform the
+host-side join the app performs at the end of onboarding.
 """
 
 from __future__ import annotations
 
 import logging
 import subprocess
+import time
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Optional
+from typing import Callable, List, Optional
 
 log = logging.getLogger(__name__)
 
@@ -37,6 +46,11 @@ VALID_SN_LENGTH = 20
 
 FALLBACK_PASSWORD = "12345678"
 
+#: Address prefixes tried (in order) when picking the host address after a
+#: join.  The aGate gateway is 10.100.1.1 and its DHCP normally hands out
+#: 10.100.1.x; the other prefixes are generic private-range fallbacks.
+_ADDRESS_PREFIX_PREFERENCE = ("10.100.", "10.", "192.168.", "172.16.")
+
 
 @dataclass(frozen=True)
 class HotspotProfile:
@@ -47,6 +61,10 @@ class HotspotProfile:
     gateway_ip: str = DEVICE_GATEWAY_IP
 
 
+class HotspotJoinError(RuntimeError):
+    """A join was issued but the association never verified in time."""
+
+
 def derive_hotspot_credentials(sn: str) -> "HotspotProfile":
     """``getDeviceApSsid`` / ``getDeviceApDefaultPwd``.
 
@@ -69,7 +87,18 @@ def derive_hotspot_credentials(sn: str) -> "HotspotProfile":
 
 
 class WifiBackend(ABC):
-    """Platform abstraction for joining/leaving a Wi-Fi network."""
+    """Platform abstraction for joining/leaving a Wi-Fi network.
+
+    Contract:
+
+    * ``join`` must raise on hard failure (missing tool, rejected SSID…).
+    * ``leave`` is best-effort: do not raise when there is simply nothing
+      to disconnect.
+    * ``is_connected`` must be **fail-closed** (return ``False`` when
+      uncertain, e.g. the underlying tooling is absent).  The manager polls
+      it to decide whether a join actually stuck, so a wrong ``True`` is
+      far worse than a late ``False``.
+    """
 
     @abstractmethod
     def join(self, profile: HotspotProfile) -> None:
@@ -77,22 +106,29 @@ class WifiBackend(ABC):
 
     @abstractmethod
     def leave(self) -> None:
-        """Disconnect from the device hotspot."""
+        """Disconnect from the current Wi-Fi network (best-effort)."""
 
     @abstractmethod
     def get_ip(self) -> Optional[str]:
-        """Our own IP on the current Wi-Fi network (device-side gateway view)."""
+        """Our own IPv4 address on the currently associated network."""
 
     def is_connected(self, profile: HotspotProfile) -> bool:
-        """Best-effort: did the join stick?"""
+        """Fail-closed: is ``profile`` the network we are associated to?"""
         return False
 
+    def get_signal(self) -> Optional[int]:
+        """Signal strength (0-100) of the associated AP, or ``None``."""
+        return None
+
 
 class NoOpWifiBackend(WifiBackend):
-    """Assumes the user has already connected (manually or via another tool).
+    """Records join/leave state without touching a radio.
 
-    Useful in sandboxes/containers without a radio, and when the host's own
-    tooling handles the association.
+    For sandboxes/containers and for hosts where the operator joins the
+    device hotspot manually (or via the host's own tooling).  Verification
+    then trivially passes: the backend records the profile ``join`` was
+    given.  Use :meth:`assume_connected` when the association was made
+    outside of this process.
     """
 
     def __init__(self, local_ip: Optional[str] = None) -> None:
@@ -100,10 +136,17 @@ class NoOpWifiBackend(WifiBackend):
         self._profile: Optional[HotspotProfile] = None
         self.joined: bool = False
 
-    def join(self, profile: HotspotProfile) -> None:
+    def assume_connected(self, profile: HotspotProfile,
+                         local_ip: Optional[str] = None) -> None:
+        """Declare that the host is already associated with ``profile``."""
+        if local_ip is not None:
+            self._local_ip = local_ip
         self._profile = profile
         self.joined = True
 
+    def join(self, profile: HotspotProfile) -> None:
+        self.assume_connected(profile)
+
     def leave(self) -> None:
         self._profile = None
         self.joined = False
@@ -116,18 +159,33 @@ class NoOpWifiBackend(WifiBackend):
 
 
 class NmcliWifiBackend(WifiBackend):
-    """Join via ``nmcli`` (NetworkManager) — for Linux desktops/laptops."""
+    """Join via ``nmcli`` (NetworkManager) — for Linux desktops/laptops.
 
-    def __init__(self, nmcli: str = "nmcli", ipcmd: str = "ip") -> None:
+    Verified against nmcli/NetworkManager 1.52 source (``devices.c``):
+
+    * association state: ``nmcli -t -f SSID,ACTIVE device wifi list`` —
+      the ``ACTIVE`` column is ``yes`` *only* for the AP we are associated
+      to.  (There is no ``device wifi show`` subcommand; the command table
+      is ``list / connect / hotspot / rescan / show-password`` and a bare
+      ``show`` is accepted only by prefix-matching ``show-password``.  Using
+      a scan list or that accident to mean "associated" is wrong, and
+      version-dependent — hence ``-f SSID,ACTIVE``.)
+    * our IP: ``nmcli -g IP4.ADDRESS device show <wifi-iface>`` per Wi-Fi
+      interface (never the unfiltered all-device dump, which would happily
+      report a wired/VPN address).
+    * signal: the ``SIGNAL`` column of the active AP from the same list.
+    """
+
+    def __init__(self, nmcli: str = "nmcli", timeout: float = 30.0) -> None:
         self._nmcli = nmcli
-        self._ipcmd = ipcmd
+        self._timeout = timeout
 
     def _run(self, *args: str) -> str:
         proc = subprocess.run(
             [self._nmcli, *args],
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
-            timeout=30,
+            timeout=self._timeout,
         )
         if proc.returncode != 0:
             raise RuntimeError(
@@ -136,80 +194,170 @@ class NmcliWifiBackend(WifiBackend):
             )
         return proc.stdout.decode("utf-8", "replace").strip()
 
+    def _wifi_ifaces(self) -> List[str]:
+        """Wi-Fi interface names in an associated/active state."""
+        try:
+            out = self._run("-t", "-f", "DEVICE,TYPE,STATE", "device", "show")
+        except (RuntimeError, subprocess.TimeoutExpired, OSError):
+            return []
+        ifaces: List[str] = []
+        for line in out.splitlines():
+            parts = line.split(":")
+            if len(parts) >= 3 and parts[1] == "wifi" and parts[2] in ("activated", "connected"):
+                ifaces.append(parts[0])
+        return ifaces
+
     def join(self, profile: HotspotProfile) -> None:
         self._run("device", "wifi", "connect", profile.ssid,
                   "password", profile.password)
 
     def leave(self) -> None:
-        self._run("device", "wifi", "disconnect")
+        # Best-effort: there may be nothing to disconnect (radio off, no
+        # association).  Tolerate it — teardown must not fail the flow.
+        try:
+            self._run("device", "wifi", "disconnect")
+        except (RuntimeError, subprocess.TimeoutExpired, OSError) as exc:
+            log.warning("wifi disconnect did not complete cleanly: %s", exc)
 
     def get_ip(self) -> Optional[str]:
-        try:
-            out = self._run("-g", "IP4.ADDRESS", "device", "show")
-        except (RuntimeError, subprocess.TimeoutExpired, OSError):
-            return None
-        for line in out.splitlines():
-            addr = line.strip()
-            if addr.startswith("10.") or addr.startswith("192.168."):
-                return addr
-        return None
+        candidates: List[str] = []
+        for dev in self._wifi_ifaces():
+            try:
+                out = self._run("-g", "IP4.ADDRESS", "device", "show", dev)
+            except (RuntimeError, subprocess.TimeoutExpired, OSError):
+                continue
+            candidates.extend(a.strip() for a in out.splitlines() if a.strip())
+        for prefix in _ADDRESS_PREFIX_PREFERENCE:
+            for addr in candidates:
+                if addr.startswith(prefix):
+                    return addr
+        return candidates[0] if candidates else None
 
     def is_connected(self, profile: HotspotProfile) -> bool:
         try:
-            out = self._run("-g", "SSID", "device", "wifi", "show")
+            out = self._run("-t", "-f", "SSID,ACTIVE", "device", "wifi", "list")
         except (RuntimeError, subprocess.TimeoutExpired, OSError):
-            return False
-        return profile.ssid in out.splitlines()
+            return False  # fail-closed: cannot confirm association
+        return f"{profile.ssid}:yes" in out.splitlines()
+
+    def get_signal(self) -> Optional[int]:
+        try:
+            out = self._run("-t", "-f", "SSID,SIGNAL,ACTIVE", "device", "wifi", "list")
+        except (RuntimeError, subprocess.TimeoutExpired, OSError):
+            return None
+        for line in out.splitlines():
+            # SSIDs may contain ':'; the trailing field is the ACTIVE flag.
+            parts = line.rsplit(":", 2)
+            if len(parts) == 3 and parts[2] == "yes":
+                try:
+                    return int(parts[1])
+                except ValueError:
+                    return None
+        return None
 
 
 class WifiManager:
-    """Facade over a :class:`WifiBackend` (keeps the original stub API)."""
+    """Facade over a :class:`WifiBackend` — derive, join, **verify**.
+
+    ``join_*`` do not take the backend's exit code on faith: after
+    ``join`` they poll ``backend.is_connected(profile)`` against
+    ``settle_timeout`` (NetworkManager can report success before the
+    association actually settles, and it can fail a few seconds later).
+    An unverified join raises :class:`HotspotJoinError` and leaves
+    ``connected`` ``False``.  ``verify=False`` restores fire-and-forget.
+    """
 
     def __init__(self, backend: Optional[WifiBackend] = None) -> None:
         self.backend = backend or NoOpWifiBackend()
         self.connected = False
+        self.last_profile: Optional[HotspotProfile] = None
 
-    # -- new, clean API ----------------------------------------------------
-    def join_device_hotspot(self, sn: str) -> HotspotProfile:
-        """Derive the profile from the SN and join.  Returns the profile."""
-        profile = derive_hotspot_credentials(sn)
-        self.backend.join(profile)
-        self.connected = True
+    # -- internal ----------------------------------------------------------
+    def _join(self, profile: HotspotProfile, *, verify: bool,
+              settle_timeout: float, poll_interval: float) -> HotspotProfile:
+        self.last_profile = profile
+        self.connected = False
+        self.backend.join(profile)  # raises on hard failure
+        ok = self._verify(
+            lambda: self.backend.is_connected(profile),
+            settle_timeout, poll_interval,
+        ) if verify else True
+        self.connected = ok
+        if not ok:
+            raise HotspotJoinError(
+                f"join to '{profile.ssid}' was issued but association was "
+                f"not confirmed within {settle_timeout:g}s"
+            )
         return profile
 
+    @staticmethod
+    def _verify(check: Callable[[], bool], timeout: float,
+                poll_interval: float) -> bool:
+        """Poll ``check()`` until it is true or ``timeout`` elapses."""
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                if check():
+                    return True
+            except Exception as exc:  # a broken backend must fail closed
+                log.debug("is_connected check raised: %s", exc)
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(max(poll_interval, 0.0))
+
+    # -- device hotspot ------------------------------------------------------
+    def join_device_hotspot(self, sn: str, *, verify: bool = True,
+                            settle_timeout: float = 30.0,
+                            poll_interval: float = 1.0) -> HotspotProfile:
+        """Derive the profile from the SN, join, and verify the association."""
+        profile = derive_hotspot_credentials(sn)
+        return self._join(profile, verify=verify,
+                          settle_timeout=settle_timeout,
+                          poll_interval=poll_interval)
+
+    def join_network(self, ssid: str, password: str, *, verify: bool = True,
+                     settle_timeout: float = 30.0,
+                     poll_interval: float = 1.0) -> HotspotProfile:
+        """Join an arbitrary network (host side)."""
+        return self._join(HotspotProfile(ssid=ssid, password=password),
+                          verify=verify, settle_timeout=settle_timeout,
+                          poll_interval=poll_interval)
+
     def leave_device_hotspot(self) -> None:
         self.backend.leave()
         self.connected = False
+        self.last_profile = None
 
+    # -- status --------------------------------------------------------------
     def local_ip(self) -> Optional[str]:
+        """Our own IP on the associated network (``None`` if unknown)."""
         return self.backend.get_ip()
 
+    def gateway_ip(self) -> str:
+        """The aGate's IP on the hotspot (where the local API lives)."""
+        return self.last_profile.gateway_ip if self.last_profile else DEVICE_GATEWAY_IP
+
+    def get_wifi_signal_strength(self) -> Optional[int]:
+        return self.backend.get_signal()
+
     # -- original stub names (kept for API compatibility) -------------------
     def query_connect_wifi(self, ssid: str, password: Optional[str] = None,
-                           sn: Optional[str] = None):
-        """``queryConnectWifi`` — join (or rejoin) a network."""
+                           sn: Optional[str] = None, **join_kwargs: object):
+        """Join an arbitrary network (host side); with ``sn`` only, join the
+        device hotspot — same as :meth:`join_device_hotspot`.
+
+        NB: in the app, ``queryConnectWifi`` is the *device* RPC
+        (``CommunicationCmd.CONNECT_WIFI``, 0x0f) that tells the aGate to
+        join a router — a provisioning operation, not a host-radio action.
+        """
         if sn is not None and password is None:
-            profile = derive_hotspot_credentials(sn)
-        else:
-            profile = HotspotProfile(ssid=ssid, password=password or "")
-        self.backend.join(profile)
-        self.connected = True
-        return profile
+            return self.join_device_hotspot(sn, **join_kwargs)
+        return self.join_network(ssid, password or "", **join_kwargs)
 
-    def wifi_onboarding_add_wifi(self, ssid: str, password: str):
-        """``wifiOnboardingAddWifi`` — register a known network."""
-        self.backend.join(HotspotProfile(ssid=ssid, password=password))
-        return True
-
-    def get_wifi_signal_strength(self) -> Optional[int]:
-        if not isinstance(self.backend, NmcliWifiBackend):
-            return None
-        try:
-            out = self.backend._run("-g", "SIGNAL", "device", "wifi", "show")
-        except (RuntimeError, subprocess.TimeoutExpired, OSError):
-            return None
-        for line in out.splitlines():
-            digits = "".join(ch for ch in line if ch.isdigit())
-            if digits:
-                return int(digits)
-        return None
+    def wifi_onboarding_add_wifi(self, ssid: str, password: str, **join_kwargs: object):
+        """Host-side step of the app's Wi-Fi onboarding: after the aGate has
+        been provisioned with the home router (device-side — see
+        ``CommunicationCmd.SCAN_WIFI_LIST`` / ``CONNECT_WIFI``), the phone
+        rejoins the home network.  This performs that host-side rejoin.
+        """
+        return self.join_network(ssid, password, **join_kwargs)