python-izone 1.3.8__tar.gz → 1.3.10__tar.gz

{python_izone-1.3.8 → python_izone-1.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-izone
-Version: 1.3.8
+Version: 1.3.10
 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>
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.14
-Requires-Dist: aiohttp>=3.14.1
+Requires-Dist: aiohttp>=3.14.3
 Requires-Dist: ifaddr>=0.2.0
 Provides-Extra: test
 Requires-Dist: pytest-aio; extra == 'test'
@@ -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.8 → python_izone-1.3.10}/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.10/docs/release-notes/v1.3.10.md

@@ -0,0 +1,15 @@
+# Release notes — v1.3.10
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.9...v1.3.10
+
+## Since v1.3.9
+
+### Control setpoint (new)
+
+- `Controller.control_setpoint_owner` — the controller, the matching zone, or `None` for who owns the unit target. RAS mode, master with CtrlZone past the configured zone count, or a missing AUTO CTS selects the controller. CONST/OPCL `Temp:0` does not.
+- `Controller.control_setpoint` — that owner's setpoint (°C)
+
+### Fixes / hardening
+
+- Drop the `Connection: close` / `force_close` HTTP keepalive workaround (core#176536)
+- Require `aiohttp>=3.14.3` for CVE-2026-69244

python_izone-1.3.10/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.8 → python_izone-1.3.10}/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.
@@ -633,9 +659,11 @@ class Controller:
 
     @property
     def zone_ctrl(self) -> int:
-        """Zone that currently controls the AC unit.
+        """Zone index that currently controls the AC unit.
 
         Value is interpreted in combination with :attr:`ras_mode`.
+        See :attr:`control_setpoint_owner` for the controller or zone that
+        owns the unit target.
 
         Raises:
             TypeError: If the cached value is missing or not numeric.
@@ -643,6 +671,50 @@ class Controller:
         """
         return int(self._get_system_state("CtrlZone"))
 
+    @property
+    def control_setpoint_owner(self) -> Self | Zone | None:
+        """Controller or zone that currently owns the unit setpoint.
+
+        Returns this controller when RAS mode is ``RAS``, when RAS mode is
+        ``master`` and :attr:`zone_ctrl` is past :attr:`zones_total` (the
+        indoor unit itself), or when any AUTO zone has no room sensor.
+        Otherwise the zone matching :attr:`zone_ctrl`, or ``None`` if that
+        index does not match a zone.
+
+        CONST/OPCL zones never have a room sensor; only a missing AUTO CTS
+        forces unit control.
+        """
+        if (
+            self.ras_mode == "RAS"
+            or (self.ras_mode == "master" and self.zone_ctrl > self.zones_total)
+            or any(
+                zone.type is Zone.Type.AUTO and zone.temp_current is None
+                for zone in self.zones
+            )
+        ):
+            return self
+        return next(
+            (zone for zone in self.zones if zone.index == self.zone_ctrl),
+            None,
+        )
+
+    @property
+    def control_setpoint(self) -> float | None:
+        """Setpoint of whoever currently owns the unit target.
+
+        :attr:`temp_setpoint` when the controller owns the unit target,
+        otherwise the controlling AUTO zone's setpoint. ``None`` when there
+        is no matching zone or that zone is not AUTO.
+        """
+        owner = self.control_setpoint_owner
+        if owner is None:
+            return None
+        if not isinstance(owner, Zone):
+            return self.temp_setpoint
+        if owner.type is not Zone.Type.AUTO:
+            return None
+        return owner.temp_setpoint
+
     @property
     def zones_total(self) -> int:
         """Number of zones the system is configured for.
@@ -998,7 +1070,6 @@ class Controller:
                 lock,
                 session.get(
                     f"http://{self.device_ip}/{resource}",
-                    headers={"Connection": "close"},
                     timeout=aiohttp.ClientTimeout(total=Controller.REQUEST_TIMEOUT),
                 ) as response,
             ):

{python_izone-1.3.8 → python_izone-1.3.10}/pizone/discovery.py

@@ -10,16 +10,19 @@ 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
 
 import aiohttp
-from aiohttp import ClientSession, TCPConnector
+from aiohttp import ClientSession
 import ifaddr
 
 from .const import PLACEHOLDER_DEVICE_UID
@@ -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.
@@ -293,8 +301,7 @@ class DiscoveryService:
 
         """
         if self._own_session:
-            # Mitigation for hubs that stall under HTTP reuse (core#176536).
-            self._session = ClientSession(connector=TCPConnector(force_close=True))
+            self._session = ClientSession()
 
         _svc = self
 
@@ -665,13 +672,13 @@ 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
         try:
             async with session.get(
                 f"http://{host}/SystemSettings",
-                headers={"Connection": "close"},
                 timeout=aiohttp.ClientTimeout(total=Controller.REQUEST_TIMEOUT),
             ) as response:
                 if response.status >= 400:
@@ -680,13 +687,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,6 +805,39 @@ 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."""
@@ -822,6 +866,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
@@ -830,6 +875,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

{python_izone-1.3.8 → python_izone-1.3.10}/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.8 → python_izone-1.3.10}/pizone/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.8'
-__version_tuple__ = version_tuple = (1, 3, 8)
+__version__ = version = '1.3.10'
+__version_tuple__ = version_tuple = (1, 3, 10)
 
 __commit_id__ = commit_id = None

{python_izone-1.3.8 → python_izone-1.3.10}/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.8 → python_izone-1.3.10}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
   "Topic :: System :: Hardware",
 ]
 dependencies = [
-  "aiohttp>=3.14.1",
+  "aiohttp>=3.14.3",
   "ifaddr>=0.2.0",
 ]
 dynamic = ["version"]