python-izone 1.3.7__tar.gz → 1.3.9__tar.gz

{python_izone-1.3.7 → python_izone-1.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-izone
-Version: 1.3.7
+Version: 1.3.9
 Summary: A python interface to the iZone airconditioner controller
 Project-URL: Homepage, https://github.com/Swamp-Ig/pizone
 Author-email: Penny Wood <pypl@ninjateaparty.com>
@@ -58,6 +58,26 @@ needed for iZone controllers that read the request in a single operation.
 The iZone Ethernet interface is documented in
 [AC-DOC-1401-11_iZoneEthernetInterface.pdf](./AC-DOC-1401-11_iZoneEthernetInterface.pdf).
 
+## Troubleshooting / issue reports
+
+If Home Assistant can load the iZone integration, prefer **Download diagnostics**
+from the integration page.
+
+When that is not possible (or you need a live HTTP/UDP survey of the bridge),
+run the stdlib probe from a machine on the same LAN:
+
+```bash
+curl -fsSL -o izone_v1_probe.py \
+  https://raw.githubusercontent.com/Swamp-Ig/pizone/main/scripts/izone_v1_probe.py
+python3 izone_v1_probe.py <bridge-ip> --with-content-type > izone-v1-probe.log
+```
+
+Attach `izone-v1-probe.log` to the GitHub issue. The CLI host (IP or hostname)
+and IPv4/IPv6 literals in the log are redacted to `**REDACTED**` by default
+(including UDP `IP_…` payloads); use `--show-ips` only for local debugging.
+Stop Home Assistant (or other listeners on UDP 7005) first if the UDP listen
+step fails to bind.
+
 ## Development
 
 1. Install [uv](https://docs.astral.sh/uv/).

{python_izone-1.3.7 → python_izone-1.3.9}/README.md

@@ -32,6 +32,26 @@ needed for iZone controllers that read the request in a single operation.
 The iZone Ethernet interface is documented in
 [AC-DOC-1401-11_iZoneEthernetInterface.pdf](./AC-DOC-1401-11_iZoneEthernetInterface.pdf).
 
+## Troubleshooting / issue reports
+
+If Home Assistant can load the iZone integration, prefer **Download diagnostics**
+from the integration page.
+
+When that is not possible (or you need a live HTTP/UDP survey of the bridge),
+run the stdlib probe from a machine on the same LAN:
+
+```bash
+curl -fsSL -o izone_v1_probe.py \
+  https://raw.githubusercontent.com/Swamp-Ig/pizone/main/scripts/izone_v1_probe.py
+python3 izone_v1_probe.py <bridge-ip> --with-content-type > izone-v1-probe.log
+```
+
+Attach `izone-v1-probe.log` to the GitHub issue. The CLI host (IP or hostname)
+and IPv4/IPv6 literals in the log are redacted to `**REDACTED**` by default
+(including UDP `IP_…` payloads); use `--show-ips` only for local debugging.
+Stop Home Assistant (or other listeners on UDP 7005) first if the UDP listen
+step fails to bind.
+
 ## Development
 
 1. Install [uv](https://docs.astral.sh/uv/).

python_izone-1.3.9/docs/release-notes/v1.3.8.md

@@ -0,0 +1,9 @@
+# Release notes — v1.3.8
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.7...v1.3.8
+
+## Since v1.3.7
+
+- `discover_all` skips controllers that become claimed mid-scan (`ControllerAlreadyClaimedError`) instead of failing the scan
+- Expected UDP `sendto` failures (blocked broadcast / interface down) log at debug instead of warning with a traceback
+- Drop dead `RuntimeError` suppress around UDP `_cache_endpoint` (claimed endpoints already return earlier; that path raises `ControllerAlreadyClaimedError`)

python_izone-1.3.9/docs/release-notes/v1.3.9.md

@@ -0,0 +1,17 @@
+# Release notes — v1.3.9
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.8...v1.3.9
+
+## Since v1.3.8
+
+### Diagnostics (new)
+
+- `DiscoveryService.dump_state()` / `Controller.dump_state()` / `Zone.dump_state()` — JSON-friendly snapshots for Home Assistant config-entry diagnostics (includes a recent UDP datagram ring buffer on the discovery service)
+- Stdlib bridge probe for issue triage when HA diagnostics are not available: [`scripts/izone_v1_probe.py`](../../scripts/izone_v1_probe.py)  
+  See **Troubleshooting / issue reports** in the [README](../../README.md) for the one-liner download + run instructions. Probe logs redact CLI host and IP literals by default.
+
+### Fixes / hardening
+
+- Harden `DiscoveryService._probe` for manual-host / non-iZone HTTP bodies: require a JSON object, catch broken `{OK}` `json.loads`, and treat `UnicodeDecodeError` as a miss (return `None` instead of raising)
+- `Controller.fan` / `Controller.mode` raise `ValueError` on unknown non-fault `SysFan` / `SysMode` strings instead of silently mapping to `AUTO` / `COOL` (fault `"error"` still uses `_get_system_state` defaults)
+- Unknown `FanAuto` values fall back to the `"unknown"` fan-mode list instead of crashing `_initialize`

{python_izone-1.3.7 → python_izone-1.3.9}/pizone/controller.py

@@ -282,9 +282,10 @@ class Controller:
                 raise ConnectionError("SystemSettings device ID mismatch")
 
             if self._system_settings:
-                self.fan_modes = Controller._VALID_FAN_MODES[
-                    str(self._system_settings.get("FanAuto", "disabled"))
-                ]
+                fan_auto = str(self._system_settings.get("FanAuto", "disabled"))
+                self.fan_modes = Controller._VALID_FAN_MODES.get(
+                    fan_auto, Controller._VALID_FAN_MODES["unknown"]
+                )
             else:
                 self.fan_modes = Controller._VALID_FAN_MODES["disabled"]
 
@@ -414,6 +415,25 @@ class Controller:
         """True while the bridge is up and the iZone AC subsystem is available."""
         return self._bridge_ok and self._izone_ok
 
+    def dump_state(self) -> dict[str, Any]:
+        """Return a JSON-friendly snapshot of cached controller state.
+
+        Includes connection/capability fields that are not mirrored in
+        ``SystemSettings``, plus the raw settings and zone payloads.
+        """
+        return {
+            "device_uid": self.device_uid,
+            "device_ip": self.device_ip,
+            "connected": self.connected,
+            "bridge_connected": self.bridge_connected,
+            "is_v2": self.is_v2,
+            "is_ipower": self.is_ipower,
+            "fan_modes": [fan.value for fan in self.fan_modes],
+            "system_settings": dict(self._system_settings),
+            "zones": [zone.dump_state() for zone in self.zones],
+            "power": self._power.dump_state() if self._power is not None else None,
+        }
+
     @property
     def power(self) -> Power | None:
         """Power monitor data, or ``None`` if not configured."""
@@ -460,13 +480,16 @@ class Controller:
 
     @property
     def mode(self) -> Mode:
-        """System mode (cooling, heating, etc.)."""
+        """System mode (cooling, heating, etc.).
+
+        Raises:
+            ValueError: If the cached SysMode is not a known :class:`Mode` member
+                (fault ``error`` is remapped by :meth:`_get_system_state`).
+
+        """
         if self.free_air:
             return self.Mode.FREE_AIR
-        try:
-            return self.Mode(self._get_system_state("SysMode"))
-        except ValueError:
-            return self.Mode.COOL
+        return self.Mode(self._get_system_state("SysMode"))
 
     async def set_mode(self, value: Mode) -> None:
         """Set the system mode (cooling, heating, etc.).
@@ -489,11 +512,14 @@ class Controller:
 
     @property
     def fan(self) -> Fan:
-        """The current fan level."""
-        try:
-            return self.Fan(self._get_system_state("SysFan"))
-        except ValueError:
-            return self.Fan.AUTO
+        """The current fan level.
+
+        Raises:
+            ValueError: If the cached SysFan is not a known :class:`Fan` member
+                (fault ``error`` is remapped by :meth:`_get_system_state`).
+
+        """
+        return self.Fan(self._get_system_state("SysFan"))
 
     async def set_fan(self, value: Fan) -> None:
         """Set the fan level.

{python_izone-1.3.7 → python_izone-1.3.9}/pizone/discovery.py

@@ -10,11 +10,14 @@ from asyncio import (
     Lock,
     Task,
 )
+from collections import deque
 from collections.abc import Callable, Coroutine, Iterator
 from contextlib import suppress
+from datetime import UTC, datetime
 from ipaddress import IPv4Interface
 import json
 import logging
+import time
 from types import TracebackType
 from typing import Any, Self, cast
 
@@ -52,6 +55,9 @@ RESCAN_COOLDOWN = 5.0
 # disposition: 1.4 — active discover_by_uid / discover_all wait
 SCAN_TIMEOUT = 5.0
 
+# Inbound UDP datagrams retained for diagnostics (ASPort, CHANGED_*, garbage).
+UDP_REPLY_BUFFER_SIZE = 20
+
 _LOG = logging.getLogger("pizone.discovery")
 
 # disposition: 1.4 — create_discovery() singleton guard
@@ -159,6 +165,8 @@ class DiscoveryService:
         self._on_endpoint_discovered = on_endpoint_discovered
         self._known_endpoints: dict[str, ControllerEndpoint] = {}
         self._claimed_endpoints: dict[str, ControllerEndpoint] = {}
+        # Ring buffer of recent inbound UDP datagrams (diagnostics).
+        self._recent_udp: deque[dict[str, Any]] = deque(maxlen=UDP_REPLY_BUFFER_SIZE)
         self._scan_collector: dict[str, str] | None = None
         self._discover_lock = Lock()
         # Set during discover_all wait so passive notifies dedupe with verify fan-out.
@@ -549,7 +557,7 @@ class DiscoveryService:
                     continue
                 try:
                     self._cache_endpoint(endpoint)
-                except RuntimeError:
+                except ControllerAlreadyClaimedError:
                     continue
                 verified.append(endpoint)
                 if endpoint.uid not in notified:
@@ -665,6 +673,7 @@ class DiscoveryService:
     async def _probe(
         self, host: str
     ) -> tuple[ControllerEndpoint, dict[str, Any]] | None:
+        """HTTP GET /SystemSettings; None on transport or content-shaped failure."""
         session = self._session
         if session is None:
             return None
@@ -680,13 +689,17 @@ class DiscoveryService:
                     data = await response.json(content_type=None)
                 except json.JSONDecodeError:
                     text = await response.text()
-                    if len(text) >= 4 and text[-4:] == "{OK}":
+                    if len(text) < 4 or text[-4:] != "{OK}":
+                        return None
+                    try:
                         data = json.loads(text[:-4])
-                    else:
+                    except json.JSONDecodeError:
                         return None
-        except TimeoutError, aiohttp.ClientError, OSError:
+        except TimeoutError, aiohttp.ClientError, OSError, UnicodeDecodeError:
             return None
 
+        if not isinstance(data, dict):
+            return None
         uid = data.get("AirStreamDeviceUId")
         if not isinstance(uid, str) or not uid:
             return None
@@ -794,13 +807,51 @@ class DiscoveryService:
             return self._transport.is_closing()
         return self._close_task is not None
 
+    def dump_state(self) -> dict[str, Any]:
+        """Return a JSON-friendly snapshot of discovery registry state.
+
+        Does not send an IASD broadcast. Includes a ring buffer of the most
+        recent inbound UDP datagrams (excluding our own IASD echo).
+        """
+
+        def _endpoints(
+            endpoints: dict[str, ControllerEndpoint],
+        ) -> list[dict[str, str]]:
+            return [
+                {"uid": endpoint.uid, "host": endpoint.host}
+                for endpoint in endpoints.values()
+            ]
+
+        recent_udp = [
+            {
+                **reply,
+                "received_at": datetime.fromtimestamp(
+                    reply["received_at"], tz=UTC
+                ).isoformat(),
+            }
+            for reply in self._recent_udp
+        ]
+
+        return {
+            "closed": self.is_closed,
+            "udp_bound": self._transport is not None and not self.is_closed,
+            "claimed": _endpoints(self._claimed_endpoints),
+            "known": _endpoints(self._known_endpoints),
+            "recent_udp": recent_udp,
+        }
+
     @property
     def session(self) -> ClientSession | None:
         """Return the aiohttp session used for HTTP requests."""
         return self._session
 
-    def _on_error_received(self, _: Exception) -> None:
-        _LOG.warning("Error passed and ignored to error_received", exc_info=True)
+    def _on_error_received(self, exc: Exception) -> None:
+        # Expected when broadcast is blocked (firewall / no permission) or the
+        # interface is down; scan just finds nothing. Keep unexpected errors loud.
+        if isinstance(exc, OSError):
+            _LOG.debug("UDP error ignored: %s", exc)
+            return
+        _LOG.warning("Error passed and ignored to error_received: %s", exc)
 
     def _find_by_addr(self, addr: tuple[str, int]) -> Controller | None:
         for ctrl in self._controllers.values():
@@ -817,6 +868,7 @@ class DiscoveryService:
     def _process_datagram(self, data: bytes, addr: tuple[str, int]) -> None:
         if data == DISCOVERY_MSG:
             return
+        self._record_udp_datagram(data, addr)
         if data in (CHANGED_SYSTEM, CHANGED_ZONES, CHANGED_SCHEDULES):
             _LOG.debug("Ignoring push notification %s from %s", data, addr)
             return
@@ -825,6 +877,26 @@ class DiscoveryService:
         else:
             self._discovery_received(data)
 
+    def _record_udp_datagram(self, data: bytes, addr: tuple[str, int]) -> None:
+        """Append an inbound UDP datagram to the diagnostics ring buffer."""
+        try:
+            message = data.decode()
+        except UnicodeDecodeError:
+            message = data.decode(errors="replace")
+        entry: dict[str, Any] = {
+            "source_ip": addr[0],
+            "source_port": addr[1],
+            "received_at": time.time(),
+            "message": message,
+        }
+        endpoint = self._parse_datagram(data)
+        if endpoint is not None:
+            entry["uid"] = endpoint.uid
+            entry["host"] = endpoint.host
+            parts = message.split(",")
+            entry["tags"] = parts[3:] if len(parts) > 3 else []
+        self._recent_udp.append(entry)
+
     # disposition: deprecate
     def _parse_datagram_deprecated(
         self, data: bytes
@@ -923,8 +995,7 @@ class DiscoveryService:
         previous = self._known_endpoints.get(endpoint.uid)
         newly_seen = previous is None
         host_changed = previous is not None and previous.host != endpoint.host
-        with suppress(RuntimeError):
-            self._cache_endpoint(endpoint)
+        self._cache_endpoint(endpoint)
         if newly_seen or host_changed:
             self._emit_endpoint_discovered(endpoint)
 

{python_izone-1.3.7 → python_izone-1.3.9}/pizone/power.py

@@ -282,6 +282,13 @@ class Power:
         self._power_ok = ok
         self._controller._event_coordinator.power_update(self._controller)  # noqa: SLF001
 
+    def dump_state(self) -> dict[str, Any]:
+        """Return a JSON-friendly snapshot of cached power monitor state."""
+        return {
+            "config": dict(self._config),
+            "status": dict(self._status),
+        }
+
     @property
     def connected(self) -> bool:
         """True while the bridge is up and power monitor I/O is healthy."""

{python_izone-1.3.7 → python_izone-1.3.9}/pizone/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.7'
-__version_tuple__ = version_tuple = (1, 3, 7)
+__version__ = version = '1.3.9'
+__version_tuple__ = version_tuple = (1, 3, 9)
 
 __commit_id__ = commit_id = None

{python_izone-1.3.7 → python_izone-1.3.9}/pizone/zone.py

@@ -4,7 +4,7 @@ Properties for reading and setting zone data.
 """
 
 from enum import Enum
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
     from .controller import Controller
@@ -68,6 +68,10 @@ class Zone:
         """The index of the zone."""
         return self._index
 
+    def dump_state(self) -> dict[str, Any]:
+        """Return a JSON-friendly snapshot of cached zone state."""
+        return dict(self._zone_data)
+
     @property
     def name(self) -> str:
         """Zone name."""

python_izone-1.3.9/scripts/izone_v1_probe.py

@@ -0,0 +1,502 @@
+#!/usr/bin/env python3
+"""Probe iZone bridge: V1 vs V2 HTTP + UDP discovery inventory.
+
+Stdlib only. Safe by default: write probes re-send the *current* SystemON /
+zone command (no-op). Pass --mutate only if you intentionally want a toggle.
+
+Network identifiers in stdout are redacted to **REDACTED** (same idea as
+Home Assistant iZone diagnostics): the CLI host argument (IP or hostname),
+IPv4/IPv6 literals (including UDP ``IP_…`` payloads), and socket peer
+addresses. Pass ``--show-ips`` only for local debugging — do not attach that
+log to a public issue.
+
+Usage:
+  python3 izone_v1_probe.py <bridge-ip> --with-content-type > izone-v1-probe.log
+  python3 izone_v1_probe.py 10.0.0.90 --zone 1
+  python3 izone_v1_probe.py 10.0.0.90 --udp-seconds 5
+
+Canonical copy: scripts/izone_v1_probe.py on the pizone main branch.
+Attach the log on the GitHub issue.
+Stop Home Assistant / other iZone listeners first if UDP bind on :7005 fails.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ipaddress
+import json
+import re
+import socket
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+TIMEOUT = 10.0
+DISCOVERY_PORT = 12107
+LISTEN_PORT = 7005
+IASD = b"IASD"
+REDACTED = "**REDACTED**"
+_IPV4 = re.compile(r"(?<!\d)(?:\d{1,3}\.){3}\d{1,3}(?!\d)")
+# Candidates only; confirmed with ipaddress.IPv6Address (handles ``::``, zone ids).
+_IPV6_CANDIDATE = re.compile(
+    r"\[?(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\]?"
+    r"|\[?[0-9a-fA-F:]*::[0-9a-fA-F:]*(?:%[0-9A-Za-z._-]+)?\]?"
+)
+
+# Set from ``main``; when False, ``_print`` strips network ids from every line.
+_SHOW_IPS = False
+# Exact CLI host (IP or hostname), redacted as a substring wherever it appears.
+_HOST_TOKEN: str | None = None
+
+
+def _redact_ipv6_match(match: re.Match[str]) -> str:
+    raw = match.group(0)
+    core = raw.strip("[]").split("%", 1)[0]
+    try:
+        ipaddress.IPv6Address(core)
+    except ValueError:
+        return raw
+    if raw.startswith("[") and raw.endswith("]"):
+        return f"[{REDACTED}]"
+    return REDACTED
+
+
+def _redact_network(text: str) -> str:
+    """Redact CLI host, IPv4/IPv6 literals (e.g. UDP ``IP_…`` payloads)."""
+    if _HOST_TOKEN:
+        text = re.sub(re.escape(_HOST_TOKEN), REDACTED, text, flags=re.IGNORECASE)
+        # urllib IPv6 URL form http://[fe80::1]/...
+        text = re.sub(
+            re.escape(f"[{_HOST_TOKEN}]"),
+            f"[{REDACTED}]",
+            text,
+            flags=re.IGNORECASE,
+        )
+    text = _IPV4.sub(REDACTED, text)
+    return _IPV6_CANDIDATE.sub(_redact_ipv6_match, text)
+
+
+def _fmt_addr(addr: str) -> str:
+    """Format a socket address for logs (always redacted unless ``--show-ips``)."""
+    return addr if _SHOW_IPS else REDACTED
+
+
+def _print(*args: object, **kwargs: Any) -> None:
+    """Print to stdout, redacting network ids unless ``--show-ips``."""
+    if _SHOW_IPS:
+        print(*args, **kwargs)
+        return
+    print(
+        *(_redact_network(a) if isinstance(a, str) else a for a in args),
+        **kwargs,
+    )
+
+
+def _req(
+    method: str,
+    url: str,
+    body: dict[str, Any] | None = None,
+    *,
+    content_type: bool,
+) -> tuple[int | None, str, float, str | None]:
+    data = None
+    headers: dict[str, str] = {"Connection": "close"}
+    if body is not None:
+        data = json.dumps(body).encode("latin_1")
+        headers["Content-Length"] = str(len(data))
+        if content_type:
+            headers["Content-Type"] = "application/json"
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    t0 = time.monotonic()
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT) as resp:
+            raw = resp.read()
+            text = raw.decode("latin_1", errors="replace")
+            return resp.status, text, time.monotonic() - t0, None
+    except urllib.error.HTTPError as ex:
+        text = ex.read().decode("latin_1", errors="replace")
+        return ex.code, text, time.monotonic() - t0, f"HTTPError: {ex.reason}"
+    except Exception as ex:  # noqa: BLE001 — probe script; report anything
+        return None, "", time.monotonic() - t0, f"{type(ex).__name__}: {ex}"
+
+
+def _show(
+    label: str,
+    status: int | None,
+    body: str,
+    dt: float,
+    err: str | None,
+    *,
+    full: bool = False,
+) -> None:
+    _print(f"\n=== {label} ===")
+    _print(f"status={status}  time={dt:.3f}s" + (f"  error={err}" if err else ""))
+    if full:
+        parsed = _parse_jsonish(body)
+        if parsed is not None:
+            _print(json.dumps(parsed, indent=2, ensure_ascii=False))
+            return
+    snippet = body if len(body) <= 1200 else body[:1200] + f"… ({len(body)} chars)"
+    _print(snippet if snippet else "(empty body)")
+
+
+def _parse_jsonish(body: str) -> Any:
+    text = body
+    if text.endswith("{OK}"):
+        text = text[:-4]
+    if not text.strip():
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return None
+
+
+def _zones_as_list(parsed: Any) -> list[dict[str, Any]]:
+    if isinstance(parsed, list):
+        return [z for z in parsed if isinstance(z, dict)]
+    if isinstance(parsed, dict):
+        inner = parsed.get("Zones")
+        if isinstance(inner, list):
+            return [z for z in inner if isinstance(z, dict)]
+    return []
+
+
+def _v1_zone_groups(zone_count: int) -> list[str]:
+    """V1 grouped GET paths covering zone_count zones (incl. Zones13_14)."""
+    n = max(zone_count, 1)
+    paths = ["Zones1_4"]
+    if n > 4:
+        paths.append("Zones5_8")
+    if n > 8:
+        paths.append("Zones9_12")
+    if n > 12:
+        paths.append("Zones13_14")
+    return paths
+
+
+def _udp_listen(
+    host: str,
+    listen_seconds: float,
+    *,
+    send_iasd: bool,
+    label: str,
+) -> None:
+    _print(
+        f"\n=== {label} (bind :{LISTEN_PORT}, "
+        f"{'IASD → :' + str(DISCOVERY_PORT) + ', ' if send_iasd else ''}"
+        f"{listen_seconds:.1f}s) ==="
+    )
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    except OSError as ex:
+        _print(f"SO_BROADCAST failed: {ex}")
+    try:
+        sock.bind(("0.0.0.0", LISTEN_PORT))
+    except OSError as ex:
+        _print(
+            f"bind :{LISTEN_PORT} failed: {ex}\n"
+            "  (Stop HA / izone-v2 / another probe using that port, then retry.)"
+        )
+        return
+
+    sock.settimeout(0.5)
+    if send_iasd:
+        for addr in (("255.255.255.255", DISCOVERY_PORT), (host, DISCOVERY_PORT)):
+            try:
+                sock.sendto(IASD, addr)
+                _print(f"sent IASD → {_fmt_addr(addr[0])}:{addr[1]}")
+            except OSError as ex:
+                _print(f"send IASD → {_fmt_addr(addr[0])}:{addr[1]} failed: {ex}")
+
+    deadline = time.monotonic() + listen_seconds
+    count = 0
+    while time.monotonic() < deadline:
+        try:
+            data, addr = sock.recvfrom(4096)
+        except socket.timeout:
+            continue
+        except OSError as ex:
+            _print(f"recv failed: {ex}")
+            break
+        text = data.decode("latin_1", errors="replace")
+        count += 1
+        kind = (
+            "ASPort"
+            if text.startswith("ASPort_")
+            else "iZoneChanged"
+            if text.startswith("iZoneChanged")
+            else "other"
+        )
+        _print(f"  [{kind}] from {_fmt_addr(addr[0])}:{addr[1]}  {text!r}")
+
+    _print(f"UDP packets received: {count}")
+    sock.close()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("host", help="Bridge IP address")
+    parser.add_argument(
+        "--zone",
+        type=int,
+        default=1,
+        help="1-based zone number for ZoneCommand no-op (default: 1)",
+    )
+    parser.add_argument(
+        "--with-content-type",
+        action="store_true",
+        help="Also retry POSTs with Content-Type: application/json",
+    )
+    parser.add_argument(
+        "--mutate",
+        action="store_true",
+        help="Allow a SystemON off→on or on→off toggle (default: no-op only)",
+    )
+    parser.add_argument(
+        "--udp-seconds",
+        type=float,
+        default=3.0,
+        help="How long to listen after IASD (default: 3)",
+    )
+    parser.add_argument(
+        "--skip-udp",
+        action="store_true",
+        help="Skip UDP discovery / listen",
+    )
+    parser.add_argument(
+        "--skip-writes",
+        action="store_true",
+        help="Inventory + UDP only (no SystemON/ZoneCommand/FAN probes)",
+    )
+    parser.add_argument(
+        "--show-ips",
+        action="store_true",
+        help="Leave host/IP addresses in stdout (local debug only; do not attach)",
+    )
+    args = parser.parse_args()
+    global _SHOW_IPS, _HOST_TOKEN
+    _SHOW_IPS = args.show_ips
+    host = args.host.strip().strip("[]")
+    _HOST_TOKEN = host or None
+    base = f"http://{host}" if ":" not in host else f"http://[{host}]"
+    ct_modes = [False]
+    if args.with_content_type:
+        ct_modes.append(True)
+
+    _print(f"iZone V1/V2 probe against {host}")
+    _print(f"python={sys.version.split()[0]}  timeout={TIMEOUT}s")
+
+    if not args.skip_udp:
+        _udp_listen(
+            host,
+            args.udp_seconds,
+            send_iasd=True,
+            label="UDP discovery ping",
+        )
+
+    # --- V1 system inventory ---
+    status, body, dt, err = _req("GET", f"{base}/SystemSettings", content_type=False)
+    _show("GET /SystemSettings (V1 inventory)", status, body, dt, err, full=True)
+    settings = _parse_jsonish(body) if status == 200 else None
+    zone_count = 0
+    if isinstance(settings, dict):
+        try:
+            zone_count = int(settings.get("NoOfZones") or 0)
+        except (TypeError, ValueError):
+            zone_count = 0
+        _print(
+            f"\nsummary: UID={settings.get('AirStreamDeviceUId')!r} "
+            f"SysType={settings.get('SysType')!r} "
+            f"NoOfZones={zone_count} SysOn={settings.get('SysOn')!r} "
+            f"SysMode={settings.get('SysMode')!r} SysFan={settings.get('SysFan')!r}"
+        )
+
+    # --- V1 zone inventory ---
+    all_v1_zones: list[dict[str, Any]] = []
+    for path in _v1_zone_groups(zone_count or 8):
+        status, body, dt, err = _req("GET", f"{base}/{path}", content_type=False)
+        _show(f"GET /{path} (V1 inventory)", status, body, dt, err, full=True)
+        if status == 200:
+            all_v1_zones.extend(_zones_as_list(_parse_jsonish(body)))
+
+    if all_v1_zones:
+        _print("\n=== V1 zone summary ===")
+        for z in all_v1_zones:
+            _print(
+                f"  idx={z.get('Index')} name={z.get('Name')!r} "
+                f"type={z.get('Type')!r} mode={z.get('Mode')!r} "
+                f"setpoint={z.get('SetPoint')!r} temp={z.get('Temp')!r}"
+            )
+
+    # --- V2 system + zones inventory ---
+    status, body, dt, err = _req(
+        "POST",
+        f"{base}/iZoneRequestV2",
+        {"iZoneV2Request": {"Type": 1, "No": 0, "No1": 0}},
+        content_type=False,
+    )
+    _show(
+        "POST /iZoneRequestV2 Type=1 SystemV2 (inventory)",
+        status,
+        body,
+        dt,
+        err,
+        full=True,
+    )
+    parsed = _parse_jsonish(body) if status == 200 else None
+    if isinstance(parsed, dict):
+        sys_v2 = parsed.get("SystemV2")
+        if isinstance(sys_v2, dict):
+            _print(
+                f"\nV2 summary: UID={parsed.get('AirStreamDeviceUId')!r} "
+                f"SysOn={sys_v2.get('SysOn')!r} SysMode={sys_v2.get('SysMode')!r} "
+                f"SysFan={sys_v2.get('SysFan')!r} NoOfZones={sys_v2.get('NoOfZones')!r}"
+            )
+            try:
+                zone_count = max(zone_count, int(sys_v2.get("NoOfZones") or 0))
+            except (TypeError, ValueError):
+                pass
+
+    # Prefer V2 zone count when present; fall back to V1 / 8
+    v2_zones = zone_count or 8
+    for idx in range(v2_zones):
+        status, body, dt, err = _req(
+            "POST",
+            f"{base}/iZoneRequestV2",
+            {"iZoneV2Request": {"Type": 2, "No": idx, "No1": 0}},
+            content_type=False,
+        )
+        _show(
+            f"POST /iZoneRequestV2 Type=2 ZonesV2 No={idx} (inventory)",
+            status,
+            body,
+            dt,
+            err,
+            full=True,
+        )
+
+    if args.skip_writes:
+        _print("\n(--skip-writes) Done. Please attach the log on the issue. Thanks!")
+        return 0
+
+    # --- Content-Type comparison on V2 request (shape probe) ---
+    if args.with_content_type:
+        status, body, dt, err = _req(
+            "POST",
+            f"{base}/iZoneRequestV2",
+            {"iZoneV2Request": {"Type": 1, "No": 0, "No1": 0}},
+            content_type=True,
+        )
+        _show(
+            "POST /iZoneRequestV2 Type=1 + Content-Type (shape probe)",
+            status,
+            body,
+            dt,
+            err,
+        )
+
+    # --- safe writes ---
+    if not isinstance(settings, dict):
+        _print("\nSkipping V1 write probes — SystemSettings missing/unparsed.")
+        _print("\nDone. Please attach the log on the issue. Thanks!")
+        return 0
+
+    sys_on = settings.get("SysOn")
+    if sys_on in ("on", "off"):
+        target = sys_on
+        if args.mutate:
+            target = "off" if sys_on == "on" else "on"
+            _print(f"\n--mutate: toggling SystemON {sys_on!r} → {target!r}")
+        payload = {"SystemON": target}
+        for use_ct in ct_modes:
+            label = (
+                f"POST /SystemON {{{target!r}}} (no-op)"
+                if target == sys_on
+                else f"POST /SystemON {{{target!r}}} (mutate)"
+            )
+            if use_ct:
+                label += " + Content-Type"
+            status, body, dt, err = _req(
+                "POST", f"{base}/SystemON", payload, content_type=use_ct
+            )
+            _show(label, status, body, dt, err)
+            if args.mutate and target != sys_on and status == 200:
+                status, body, dt, err = _req(
+                    "POST",
+                    f"{base}/SystemON",
+                    {"SystemON": sys_on},
+                    content_type=use_ct,
+                )
+                _show(
+                    f"POST /SystemON restore {{{sys_on!r}}}"
+                    + (" + Content-Type" if use_ct else ""),
+                    status,
+                    body,
+                    dt,
+                    err,
+                )
+    else:
+        _print(f"\nSkipping SystemON write — unexpected SysOn={sys_on!r}")
+
+    # Zone no-op from inventoried V1 zones
+    z_match = next(
+        (z for z in all_v1_zones if z.get("Index") == args.zone - 1),
+        all_v1_zones[args.zone - 1] if len(all_v1_zones) >= args.zone else None,
+    )
+    if z_match is not None:
+        mode = z_match.get("Mode")
+        setpoint = z_match.get("SetPoint")
+        if mode == "auto" and setpoint is not None:
+            command: Any = setpoint
+        elif mode in ("open", "close"):
+            command = mode
+        else:
+            command = mode if mode is not None else setpoint
+        payload = {
+            "ZoneCommand": {"ZoneNo": str(args.zone), "Command": str(command)}
+        }
+        for use_ct in ct_modes:
+            label = f"POST /ZoneCommand zone={args.zone} Command={command!r} (no-op)"
+            if use_ct:
+                label += " + Content-Type"
+            status, body, dt, err = _req(
+                "POST", f"{base}/ZoneCommand", payload, content_type=use_ct
+            )
+            _show(label, status, body, dt, err)
+    else:
+        _print(f"\nSkipping ZoneCommand — no V1 zone data for zone {args.zone}")
+
+    for use_ct in ct_modes:
+        label = 'POST /SystemFAN {"SystemFAN":"top"} (V1 out-of-spec probe)'
+        if use_ct:
+            label += " + Content-Type"
+        status, body, dt, err = _req(
+            "POST",
+            f"{base}/SystemFAN",
+            {"SystemFAN": "top"},
+            content_type=use_ct,
+        )
+        _show(label, status, body, dt, err)
+
+    # Brief post-write listen for iZoneChanged_* (no second IASD)
+    if not args.skip_udp:
+        _udp_listen(
+            host,
+            min(args.udp_seconds, 3.0),
+            send_iasd=False,
+            label="UDP post-write listen (iZoneChanged_*?)",
+        )
+
+    _print("\nDone. Please attach the log on the issue. Thanks!")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

{python_izone-1.3.7 → python_izone-1.3.9}/tests/http_fakes.py

@@ -4,6 +4,8 @@ import json
 from types import TracebackType
 from typing import Self
 
+_UNSET: object = object()
+
 
 class FakeHttpResponse:
     """Minimal async HTTP response double."""
@@ -13,8 +15,9 @@ class FakeHttpResponse:
         status: int,
         body: str = "",
         *,
-        json_data: dict[str, object] | None = None,
+        json_data: object = _UNSET,
         json_error: bool = False,
+        unicode_error: bool = False,
     ) -> None:
         self.status = status
         self.reason = (
@@ -27,17 +30,22 @@ class FakeHttpResponse:
         self._body = body
         self._json_data = json_data
         self._json_error = json_error
+        self._unicode_error = unicode_error
 
-    async def json(self, content_type: str | None = None) -> dict[str, object]:
+    async def json(self, content_type: str | None = None) -> object:
         del content_type
+        if self._unicode_error:
+            raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte")
         if self._json_error:
             raise json.JSONDecodeError("invalid", self._body, 0)
-        if self._json_data is not None:
+        if self._json_data is not _UNSET:
             return self._json_data
         return json.loads(self._body)
 
     async def text(self, encoding: str | None = None) -> str:
         del encoding
+        if self._unicode_error:
+            raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte")
         return self._body
 
     async def __aenter__(self) -> Self:

{python_izone-1.3.7 → python_izone-1.3.9}/tests/test_controller.py

@@ -561,6 +561,54 @@ async def test_fault_placeholder_values_in_cache_use_defaults(
     assert controller.mode == Controller.Mode.COOL
 
 
+# disposition: deprecate
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("field", "value", "prop"),
+    [
+        ("SysFan", "quiet", "fan"),
+        ("SysFan", "weird", "fan"),
+        ("SysMode", "quiet", "mode"),
+        ("SysMode", "turbo", "mode"),
+    ],
+)
+async def test_unknown_sys_enum_raises(
+    service: MockDiscoveryService,
+    field: str,
+    value: str,
+    prop: str,
+) -> None:
+    """Unknown non-fault SysFan/SysMode must not silently map to AUTO/COOL."""
+    controller = cast(MockController, service._controllers["000000001"])
+    controller._system_settings[field] = value
+
+    with pytest.raises(ValueError):
+        getattr(controller, prop)
+
+
+# disposition: deprecate
+@pytest.mark.asyncio
+async def test_unknown_fan_auto_falls_back_to_unknown_list() -> None:
+    service = MockDiscoveryService()
+    controller = MockController(
+        service,
+        service._event_coordinator,
+        device_uid="000000099",
+        device_ip="10.0.0.99",
+        is_v2=False,
+        is_ipower=False,
+    )
+    settings = deepcopy(controller.resources["SystemSettings"])
+    settings["FanAuto"] = "brand-new-speed-table"
+    controller.resources["SystemSettings"] = settings
+    service._controllers["000000099"] = controller
+
+    await controller._initialize(system_settings=settings)
+
+    assert controller.fan_modes == Controller._VALID_FAN_MODES["unknown"]
+    await service.close()
+
+
 # disposition: deprecate
 @pytest.mark.asyncio
 async def test_both_false_on_transport_failure(service: MockDiscoveryService) -> None:

{python_izone-1.3.7 → python_izone-1.3.9}/tests/test_discovery_api.py

@@ -252,6 +252,69 @@ async def test_discover_by_host_unreachable() -> None:
     await service.close()
 
 
+# disposition: 1.4
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "response",
+    [
+        pytest.param(
+            FakeHttpResponse(200, "<html>not a bridge</html>", json_error=True),
+            id="html",
+        ),
+        pytest.param(
+            FakeHttpResponse(200, json_data={"SysOn": "on"}),
+            id="json-missing-uid",
+        ),
+        pytest.param(
+            FakeHttpResponse(200, json_data=None),
+            id="empty-null-body",
+        ),
+        pytest.param(
+            FakeHttpResponse(200, json_data=["not", "an", "object"]),
+            id="json-array",
+        ),
+        pytest.param(
+            FakeHttpResponse(200, json_data="not-an-object"),
+            id="json-string",
+        ),
+        pytest.param(
+            FakeHttpResponse(200, "garbage{OK}", json_error=True),
+            id="ok-suffix-non-json",
+        ),
+        pytest.param(
+            FakeHttpResponse(200, unicode_error=True),
+            id="non-utf8",
+        ),
+    ],
+)
+async def test_discover_by_host_malformed_body_returns_none(
+    response: FakeHttpResponse,
+) -> None:
+    """Manual host widens _probe input; content failures must not raise."""
+    service = MockDiscoveryService(legacy_pathway=False)
+    service._session = cast(ClientSession, FakeHttpSession(get_response=response))
+    endpoint = await service.discover_by_host("10.0.0.90")
+    assert endpoint is None
+    await service.close()
+
+
+# disposition: 1.4
+@pytest.mark.asyncio
+async def test_discover_by_host_ok_suffix_json() -> None:
+    """Bridge quirk: JSON body with a trailing {OK} still probes successfully."""
+    body = '{"AirStreamDeviceUId":"000025841","SysOn":"on"}{OK}'
+    service = MockDiscoveryService(legacy_pathway=False)
+    service._session = cast(
+        ClientSession,
+        FakeHttpSession(
+            get_response=FakeHttpResponse(200, body, json_error=True),
+        ),
+    )
+    endpoint = await service.discover_by_host("10.0.0.90")
+    assert endpoint == ControllerEndpoint(uid="000025841", host="10.0.0.90")
+    await service.close()
+
+
 # disposition: 1.4
 @pytest.mark.asyncio
 async def test_discover_by_host_uses_known_cache() -> None:
@@ -588,9 +651,14 @@ async def test_discover_all_excludes_created_controllers() -> None:
         FakeHttpSession(get_response=_system_settings_response("000025841")),
     )
     await service.create_controller("000025841", "10.0.0.90")
+
+    async def _scan_reports_claimed() -> None:
+        assert service._scan_collector is not None
+        service._scan_collector["000025841"] = "10.0.0.90"
+
     with (
         patch("pizone.discovery.asyncio.sleep", AsyncMock()),
-        patch.object(service, "scan", AsyncMock()),
+        patch.object(service, "scan", side_effect=_scan_reports_claimed),
     ):
         endpoints = await service.discover_all()
     assert endpoints == []

python_izone-1.3.9/tests/test_dump_state.py

@@ -0,0 +1,94 @@
+"""Tests for dump_state snapshots on discovery, controller, and zone."""
+
+from typing import cast
+
+import pytest
+
+from pizone import ControllerEndpoint
+from pizone.discovery import UDP_REPLY_BUFFER_SIZE
+
+from .conftest import MockController, MockDiscoveryService
+
+
+@pytest.mark.asyncio
+async def test_zone_dump_state(service: MockDiscoveryService) -> None:
+    controller = cast(MockController, service._controllers["000000001"])
+    zone = controller.zones[1]
+
+    dumped = zone.dump_state()
+
+    assert dumped["Name"] == "LOUNGE"
+    assert dumped["Index"] == 1
+
+
+@pytest.mark.asyncio
+async def test_controller_dump_state(service: MockDiscoveryService) -> None:
+    controller = cast(MockController, service._controllers["000000001"])
+
+    dumped = controller.dump_state()
+
+    assert dumped["device_uid"] == "000000001"
+    assert dumped["device_ip"] == "192.0.2.1" or isinstance(dumped["device_ip"], str)
+    assert dumped["connected"] is True
+    assert dumped["bridge_connected"] is True
+    assert "system_settings" in dumped
+    assert dumped["system_settings"]["AirStreamDeviceUId"] == "000000001"
+    assert isinstance(dumped["fan_modes"], list)
+    assert len(dumped["zones"]) == len(controller.zones)
+    assert dumped["zones"][1]["Index"] == 1
+    assert dumped["power"] is None or isinstance(dumped["power"], dict)
+
+
+@pytest.mark.asyncio
+async def test_discovery_dump_state(service: MockDiscoveryService) -> None:
+    service._recent_udp.clear()
+    service._claimed_endpoints["000000001"] = ControllerEndpoint(
+        uid="000000001", host="192.0.2.1"
+    )
+    service._known_endpoints["000000002"] = ControllerEndpoint(
+        uid="000000002", host="192.0.2.2"
+    )
+
+    dumped = service.dump_state()
+
+    assert dumped["closed"] is False or isinstance(dumped["closed"], bool)
+    assert "udp_bound" in dumped
+    assert {"uid": "000000001", "host": "192.0.2.1"} in dumped["claimed"]
+    assert {"uid": "000000002", "host": "192.0.2.2"} in dumped["known"]
+    assert dumped["recent_udp"] == []
+
+
+@pytest.mark.asyncio
+async def test_discovery_udp_ring_buffer() -> None:
+    service = MockDiscoveryService(legacy_pathway=False)
+    service._recent_udp.clear()
+
+    service._process_datagram(
+        b"ASPort_12107,Mac_000025841,IP_10.0.0.90,iZone,iPower",
+        ("10.0.0.90", 12107),
+    )
+    service._process_datagram(
+        b"ASPort_12107,Mac_000025841,IP_10.0.0.91,iZone",
+        ("10.0.0.91", 12107),
+    )
+    service._process_datagram(b"iZoneChanged_System", ("10.0.0.91", 12107))
+    service._process_datagram(b"not-a-discovery-message", ("10.0.0.5", 12107))
+
+    dumped = service.dump_state()
+    assert len(dumped["recent_udp"]) == 4
+    assert dumped["recent_udp"][0]["host"] == "10.0.0.90"
+    assert dumped["recent_udp"][0]["tags"] == ["iZone", "iPower"]
+    assert dumped["recent_udp"][1]["host"] == "10.0.0.91"
+    assert dumped["recent_udp"][2]["message"] == "iZoneChanged_System"
+    assert "uid" not in dumped["recent_udp"][2]
+    assert dumped["recent_udp"][3]["message"] == "not-a-discovery-message"
+    assert "T" in dumped["recent_udp"][0]["received_at"]
+
+    for i in range(UDP_REPLY_BUFFER_SIZE + 5):
+        service._process_datagram(
+            f"ASPort_12107,Mac_000025841,IP_10.0.0.{i % 250},iZone".encode(),
+            ("10.0.0.1", 12107),
+        )
+    assert len(service.dump_state()["recent_udp"]) == UDP_REPLY_BUFFER_SIZE
+
+    await service.close()