python-izone 1.3.7__py3-none-any.whl → 1.3.9__py3-none-any.whl

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.

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)
 

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."""

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

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.7.dist-info → python_izone-1.3.9.dist-info}/METADATA

@@ -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.9.dist-info/RECORD

@@ -0,0 +1,14 @@
+pizone/__init__.py,sha256=9EbQzqD1XfS5fSE-zgFieuzxAfZcQb9a3wNXsMp0JKc,2644
+pizone/const.py,sha256=0skTh6zBe61AJ_57fqdBrxz3aVBM3T4Ak_cPSkOx2Bo,153
+pizone/controller.py,sha256=l0qLAhSEF71kMLc9pG7EuQ3jaAfo0kdSBr0QgbJvfKo,42225
+pizone/discovery.py,sha256=aiXZ6c57Z66usjwFMcQZ9ioNkw3_S2i1KQTpIEjquEQ,40199
+pizone/exceptions.py,sha256=qzYNHzQBMDcuvLfxlvOsk6J2Lp0gtzlHqJWpzyEunvU,1603
+pizone/power.py,sha256=ZWj_RLxvcQT3WxdAyUHzPAl7DtQGtT4FPIIdGVxatO0,10576
+pizone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pizone/types.py,sha256=fZrnec0Q815HyG2sFciLqNX0QDbTq1_0wTF92GXQh78,200
+pizone/version.py,sha256=g62BHujLgGdP6cB1oucUZ89PYnKUKXkd5IR17viSOVM,520
+pizone/zone.py,sha256=LoiUFHcHLAmsVEkS1YcA6lKAOzu7A6RGnV_5mC1vV-I,7601
+python_izone-1.3.9.dist-info/METADATA,sha256=3uBQnmINRhPCzENIcDiNGjTPoCfycDO7gUZhb_cy2yM,3521
+python_izone-1.3.9.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+python_izone-1.3.9.dist-info/licenses/licence.txt,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_izone-1.3.9.dist-info/RECORD,,

python_izone-1.3.7.dist-info/RECORD

@@ -1,14 +0,0 @@
-pizone/__init__.py,sha256=9EbQzqD1XfS5fSE-zgFieuzxAfZcQb9a3wNXsMp0JKc,2644
-pizone/const.py,sha256=0skTh6zBe61AJ_57fqdBrxz3aVBM3T4Ak_cPSkOx2Bo,153
-pizone/controller.py,sha256=nctzAF8Y75T0_Ue9Hxxv9OfEex4zoNseOMjGfI6wHFE,41109
-pizone/discovery.py,sha256=9akqPwsB8gcsmqnT5GQ3CCilo4m3jYL7cA3MWFOU1Uc,37442
-pizone/exceptions.py,sha256=qzYNHzQBMDcuvLfxlvOsk6J2Lp0gtzlHqJWpzyEunvU,1603
-pizone/power.py,sha256=bXoDRVD6gCfq0kJv132sjfy13DHGd6p2uBg9HcxRSxA,10343
-pizone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pizone/types.py,sha256=fZrnec0Q815HyG2sFciLqNX0QDbTq1_0wTF92GXQh78,200
-pizone/version.py,sha256=qggYsfTliS2fgO5WngEhVPgiQ-AREJyDah_xDSuzcIM,520
-pizone/zone.py,sha256=tqiLJAJCmp1cehCtVPjawUNY9qyYypC4x3igI5jtDNo,7446
-python_izone-1.3.7.dist-info/METADATA,sha256=t1FnN14YONJRs8bYY-sNsbADvzt6VaQbQLfOGlzCzDQ,2703
-python_izone-1.3.7.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-python_izone-1.3.7.dist-info/licenses/licence.txt,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-python_izone-1.3.7.dist-info/RECORD,,