localtrv 0.2.0__py3-none-any.whl

localtrv/__init__.py

@@ -0,0 +1,10 @@
+"""localtrv: local Zigbee Direct (BLE) client for Viessmann ZK03840 valves."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("localtrv")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

localtrv/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m localtrv``."""
+
+import sys
+
+from localtrv.cli import main
+
+sys.exit(main())

localtrv/bridge.py

@@ -0,0 +1,292 @@
+"""ViCareBridge: discovery, polling, setpoints and reports on top of a ZdConnection.
+
+Orchestration only: every cluster, attribute, scale, sentinel, model id and read plan comes from
+``localtrv.valves``; no Zigbee literals here.
+
+Lifecycle and ownership
+    ``attach()`` registers a ready listener on the connection. On READY(gen) (sync):
+    persist ``gen.join.own_short`` (``on_cache_changed``), register report / Device_annce /
+    address-conflict listeners on ``gen.node`` (address conflict: forget the cached own short;
+    the connection itself rejoins), then ``connection.spawn(gen, self._discover(gen))``.
+    Every background coroutine (discovery, retries, identification, the initial poll,
+    confirm reads, topology re-walks) is spawned on its generation, so the connection cancels
+    and awaits it at teardown. Each completion checks that its generation is still current
+    before mutating state; stale completions are dropped.
+
+Polling
+    ``poll()`` is driven by the HA coordinator schedule (never by pushes). Valves run in
+    parallel; each first ``try``-acquires its transaction lock (busy -> skipped, neither miss
+    nor success). Plans: ``valves.FAST`` every poll, ``valves.SLOW`` every
+    ``SLOW_EVERY_N_POLLS``-th, ``valves.STATIC`` at discovery and every ``STATIC_REFRESH_S``.
+    Any response resets ``misses``; all attempts failing -> ``misses += 1``; at
+    ``MISSES_UNAVAILABLE`` the valve is unavailable and a topology walk is spawned. Not READY ->
+    the cycle is skipped and every known valve counts a miss. Rejoin rule: >= 1 known valve,
+    every known valve missed ``SILENT_POLLS_REJOIN`` consecutive polls, READY throughout ->
+    ``connection.request_rejoin(gen, "all_valves_silent")``. Without any valve answering
+    since the last such rejoin, the next one also waits ``SILENT_REJOIN_BACKOFF`` doubling
+    per rejoin (1 h, 2 h, 4 h, cap ``SILENT_REJOIN_BACKOFF_MAX`` 6 h; see ``bridge_poll``).
+
+Setpoints (``set_setpoint``), per valve, in this order
+    1. Validate (``KeyError`` unknown valve, ``ValueError`` non-finite) and clamp with
+       ``valves.clamp_setpoint``.
+    2. BEFORE waiting for the lock: ``version += 1``, ``requested_c`` = clamped value,
+       ``pending = True``, ``on_update`` (the UI updates optimistically at once).
+    3. Preempt: if an older version's background confirm task holds the lock, cancel it (its
+       exit path releases the lock; it no longer touches ``pending``, it is not the latest).
+    4. Acquire the per-valve transaction lock, verify the valve's short (IEEE_addr_req: the
+       device there must name the valve, else ``ValveAddressUnknownError`` and nothing is
+       written) and write ``valves.setpoint_record`` with ``node.zcl_write``, all inside
+       ``clock.timeout`` bounded by ``SETPOINT_ACK_DEADLINE`` from step 2. If a newer version
+       arrived meanwhile, this call still writes its own value (the newer write follows it
+       under the lock; last writer wins on the valve).
+    5. Success: ``acknowledged_c`` = clamped value, ``on_update``; spawn the confirm task on the
+       generation and return the ``SetpointStatus``. The HA call ends here. Lock ownership
+       passes to the confirm task.
+    6. Confirm task: ``zcl_read(valves.CONFIRM_SETPOINT)`` bounded so it ends before
+       ``SETPOINT_TOTAL_DEADLINE`` from step 2. Success -> ``confirmed_c``/``confirmed_at`` and
+       ``state.setpoint_c``. Timeout or error -> acknowledged but unconfirmed (``confirmed_c``
+       unchanged, never reported as confirmed).
+
+    Every exit path runs one ``finally``: release the lock, and if this version is still the
+    latest, set ``pending = False`` (and on failure before the ack also clear ``requested_c``)
+    and call ``on_update``. Exit paths covered: write failure or ack deadline (then raise),
+    the HA caller cancelled while waiting for the lock or the write (``CancelledError``
+    propagates), ``connection.spawn`` raising ``ConnectionLostError`` between ack and confirm
+    (the ack is still returned; pending cleared, no confirm), the confirm task cancelled at
+    generation teardown or by preemption, and confirm success or timeout. An older version
+    never overwrites a newer version's fields; only the latest version clears ``pending``.
+
+    Raised to HA: ``ZclStatusError``, ``RequestTimeoutError`` or a bare ``TimeoutError`` (the
+    ack deadline; ``RequestTimeoutError`` subclasses ``TimeoutError``, so HA catches
+    ``TimeoutError``), ``ConnectionLostError``, ``ValveAddressUnknownError`` (a ``RouteError``:
+    the valve's cached short now belongs to another valve and its own is not re-learned yet;
+    nothing was written, or the ack came from that other valve).
+
+Short ownership (``bridge_owner``, ``bridge_verify``): one EUI per short. Only authoritative
+evidence moves or evicts it: a Device_annce, a frame whose NWK header names its source IEEE
+(``node.on_sender``), an IEEE_addr response from the short asked. Walk results are hints: a known
+valve listed at another short, or an unaddressed one, is verified with IEEE_addr_req (once per
+valve per walk) and adopted only if the device names itself; a walk never evicts. Restored
+(cached) shorts are trusted for reads. Every ZCL request for a valve runs under a lease, checked
+before queueing and at transmission of every attempt (the node's ``guard``) and on the answer,
+which must not name another source IEEE (``expect_ieee``). An unaddressed valve gets no ZCL
+request (a poll counts a miss; the usual re-walk follows). An identification holds an epoch
+lease on its short; if evidence changes meanwhile, its result is discarded (not added, not
+ignored).
+
+HA wiring: ``on_update`` and ``connection.add_state_listener`` both push
+``bridge.snapshot()`` to the coordinator (``async_update_listeners``, no schedule reset), so the
+bridge connectivity entity flips at once on a state change, not at the next poll.
+
+Callbacks: ``on_update(snapshot)`` after every state change (sync, must not await; cheap
+``snapshot()``), ``on_new_valve(valve)`` once per newly identified valve,
+``on_cache_changed(cache)`` whenever ``export_cache()`` would differ. Callback exceptions are
+logged and swallowed.
+
+Logging (``localtrv.bridge``): INFO discovery results; WARNING valve unavailable,
+heating demand above the observed scale (once per valve); DEBUG ``valves.read_issues`` once per
+valve and attribute. EUIs only in DEBUG.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from localtrv import bridge_discovery, bridge_poll, bridge_setpoint
+from localtrv.bridge_cache import CACHE_VERSION, BridgeCache, CachedValve, JsonValue
+from localtrv.bridge_state import BridgeCore
+from localtrv.bridge_types import (
+    ANNCE_IDENTIFY_DEBOUNCE,
+    ANNCE_IDENTIFY_RETRY,
+    DISCOVERY_RETRY_DELAYS,
+    IDENTIFY_CONCURRENCY,
+    IDENTIFY_DIAGNOSTIC_AFTER,
+    MISSES_UNAVAILABLE,
+    SETPOINT_ACK_DEADLINE,
+    SETPOINT_TOTAL_DEADLINE,
+    SILENT_POLLS_REJOIN,
+    SILENT_REJOIN_BACKOFF,
+    SILENT_REJOIN_BACKOFF_MAX,
+    TOPOLOGY_REFRESH,
+    BridgeSnapshot,
+    DiscoveryStatus,
+    SetpointStatus,
+    TopologySummary,
+    ValveAddressUnknownError,
+    ValveAddressUnverifiedError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from localtrv.valves import Valve
+    from localtrv.zigbee_direct.clock import Clock
+    from localtrv.zigbee_direct.codec.zdo import DeviceAnnce
+    from localtrv.zigbee_direct.connection import Generation, ZdConnection
+    from localtrv.zigbee_direct.node import ReportEvent
+    from localtrv.zigbee_direct.types import Eui64
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ViCareBridge:
+    """Valve orchestration over one ``ZdConnection`` (see module docstring).
+
+    ``cache`` seeds the known valves (shown at once, unavailable until polled), the ignore list
+    and the preferred own short. The constructor does not touch the connection; call
+    ``attach()``. Loop thread only.
+    """
+
+    def __init__(
+        self,
+        connection: ZdConnection,
+        *,
+        clock: Clock,
+        cache: BridgeCache | None = None,
+        on_update: Callable[[BridgeSnapshot], None] | None = None,
+        on_new_valve: Callable[[Valve], None] | None = None,
+        on_cache_changed: Callable[[BridgeCache], None] | None = None,
+    ) -> None:
+        self._core = BridgeCore(
+            connection,
+            clock=clock,
+            cache=cache,
+            on_update=on_update,
+            on_new_valve=on_new_valve,
+            on_cache_changed=on_cache_changed,
+        )
+        self._unsubscribe: list[Callable[[], None]] = []
+        self._node_unsubscribe: list[Callable[[], None]] = []
+
+    def attach(self) -> Callable[[], None]:
+        """Register the connection listeners and push ``preferred_short``/``avoid_shorts`` from
+        the cache with ``connection.update_node_config``. Returns a detach callable (also
+        removes node listeners). Call before ``connection.start()``.
+
+        ``avoid_shorts`` pushed by the bridge are the known device shorts only (refreshed after
+        every discovery). The connection keeps its own conflict set and merges it in at each
+        join, so a bridge push can never erase a conflicting short; likewise the bridge never
+        re-sets ``preferred_short`` after an address conflict cleared it (it forgets the cached
+        own short on the node's address-conflict callback)."""
+        core = self._core
+        changes: dict[str, object] = {"avoid_shorts": core.known_shorts()}
+        if core.own_short is not None:
+            changes["preferred_short"] = core.own_short
+        core.connection.update_node_config(**changes)
+        self._unsubscribe.append(core.connection.add_ready_listener(self._on_ready))
+        return self._detach
+
+    def _detach(self) -> None:
+        for unsubscribe in (*self._unsubscribe, *self._node_unsubscribe):
+            unsubscribe()
+        self._unsubscribe.clear()
+        self._node_unsubscribe.clear()
+
+    # --- READY (synchronous) ---
+
+    def _on_ready(self, gen: Generation) -> None:
+        core = self._core
+        for unsubscribe in self._node_unsubscribe:
+            unsubscribe()
+        core.start_generation(gen)
+        core.own_short = gen.join.own_short
+        core.zdd_eui = str(gen.join.zdd_eui)
+        node = gen.node
+        self._node_unsubscribe = [
+            node.on_report(lambda event: self._on_report(gen, event)),
+            node.on_device_annce(lambda annce, _src: self._on_annce(gen, annce)),
+            node.on_address_conflict(lambda: self._on_conflict(gen)),
+            node.on_sender(
+                lambda short, ieee: bridge_discovery.on_address(
+                    core, gen, ieee, short, identify=False
+                )
+            ),
+        ]
+        core.changed()
+        bridge_discovery.spawn_safely(
+            core, gen, bridge_discovery.discovery_task(core, gen), "vicare discovery"
+        )
+
+    def _on_report(self, gen: Generation, event: ReportEvent) -> None:
+        core = self._core
+        if not core.is_current(gen):
+            return
+        _LOGGER.debug(
+            "report from 0x%04X: cluster 0x%04X attrs %s",
+            event.src_short,
+            event.cluster,
+            ",".join(f"0x{r.attribute_id:04X}" for r in event.records),
+        )
+        if event.src_ieee is not None:  # address evidence (maybe on a reused valve short)
+            bridge_discovery.on_sender_ieee(core, gen, event.src_ieee, event.src_short)
+        eui = core.eui_for_short(event.src_short, event.src_ieee)
+        if eui is None:
+            return
+        changed = core.apply(eui, event.cluster, event.records, event.manufacturer_code)
+        if core.responded(eui) or changed:
+            core.changed()
+
+    def _on_annce(self, gen: Generation, annce: DeviceAnnce) -> None:
+        bridge_discovery.on_device_annce(self._core, gen, annce)
+
+    def _on_conflict(self, gen: Generation) -> None:
+        core = self._core
+        if core.gen is not gen or core.own_short is None:
+            return
+        _LOGGER.info("address conflict on our short: forgetting it")
+        core.own_short = None
+        core.changed()
+
+    # --- public API ---
+
+    def snapshot(self) -> BridgeSnapshot:
+        """Current state; cheap, never awaits, safe in any connection state."""
+        return self._core.snapshot()
+
+    async def poll(self) -> BridgeSnapshot:
+        """One poll cycle (module docstring); never raises for valve failures."""
+        return await bridge_poll.poll(self._core)
+
+    async def set_setpoint(self, eui: Eui64, celsius: float) -> SetpointStatus:
+        """Write a setpoint and return at the acknowledgement (module docstring).
+
+        Raises ``KeyError`` (unknown valve), ``ValueError`` (non-finite), ``ZclStatusError``
+        (write rejected), ``RequestTimeoutError`` or bare ``TimeoutError`` (no acknowledgement
+        within ``SETPOINT_ACK_DEADLINE``; HA must catch ``TimeoutError``),
+        ``ConnectionLostError`` (not READY, or lost meanwhile) or ``ValveAddressUnknownError``
+        (a ``RouteError``; the valve's short is not established, see module docstring).
+        ``CancelledError`` of the caller propagates after the cleanup described in the module
+        docstring.
+        """
+        return await bridge_setpoint.set_setpoint(self._core, eui, celsius)
+
+    def export_cache(self) -> BridgeCache:
+        return self._core.export_cache()
+
+
+__all__ = [
+    "ANNCE_IDENTIFY_DEBOUNCE",
+    "ANNCE_IDENTIFY_RETRY",
+    "CACHE_VERSION",
+    "DISCOVERY_RETRY_DELAYS",
+    "IDENTIFY_CONCURRENCY",
+    "IDENTIFY_DIAGNOSTIC_AFTER",
+    "MISSES_UNAVAILABLE",
+    "SETPOINT_ACK_DEADLINE",
+    "SETPOINT_TOTAL_DEADLINE",
+    "SILENT_POLLS_REJOIN",
+    "SILENT_REJOIN_BACKOFF",
+    "SILENT_REJOIN_BACKOFF_MAX",
+    "TOPOLOGY_REFRESH",
+    "BridgeCache",
+    "BridgeSnapshot",
+    "CachedValve",
+    "DiscoveryStatus",
+    "JsonValue",
+    "SetpointStatus",
+    "TopologySummary",
+    "ValveAddressUnknownError",
+    "ValveAddressUnverifiedError",
+    "ViCareBridge",
+]

localtrv/bridge_cache.py

@@ -0,0 +1,244 @@
+"""Persisted bridge state: ``BridgeCache``/``CachedValve`` and their JSON round trip.
+
+Re-exported from ``localtrv.bridge``. No key material, ever: only shorts, EUIs (display
+form), identification strings and validated limits.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+import math
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Final, Literal, Self
+
+from localtrv.valves import SetpointLimits, Valve
+from localtrv.zigbee_direct.types import Eui64, validate_short
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+CACHE_VERSION: Final = 1
+
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None
+#: The ``SetpointLimits.source`` values a cache records (``"cached"`` is stored as ``None``).
+type _StoredSource = Literal["limits", "abs"]
+
+_LOGGER = logging.getLogger("localtrv.bridge")
+_ENDPOINT_RANGE: Final = (1, 240)
+
+
+class _BadCacheError(ValueError):
+    """Internal: the persisted data does not have the expected shape."""
+
+
+@dataclass(frozen=True, slots=True)
+class CachedValve:
+    """Persisted identity of a valve (``eui`` in display form); limits in °C.
+
+    ``limits_source`` is the ``SetpointLimits.source`` of the limits. ``None`` (caches written
+    by 0.1.0a1 and earlier have no such field) loads them as provisional ``"cached"`` limits.
+    """
+
+    eui: str
+    short: int
+    endpoint: int
+    manufacturer: str | None
+    model: str | None
+    sw_build: str | None
+    min_c: float | None = None
+    max_c: float | None = None
+    limits_source: _StoredSource | None = None
+
+    @classmethod
+    def from_valve(cls, valve: Valve) -> Self:
+        limits = valve.limits
+        keep = limits.source != "default"
+        source: _StoredSource | None
+        match limits.source:
+            case "limits" | "abs":
+                source = limits.source
+            case _:
+                source = None
+        return cls(
+            eui=str(valve.eui),
+            short=valve.short,
+            endpoint=valve.endpoint,
+            manufacturer=valve.manufacturer,
+            model=valve.model,
+            sw_build=valve.sw_build,
+            min_c=limits.min_c if keep else None,
+            max_c=limits.max_c if keep else None,
+            limits_source=source,
+        )
+
+    def to_valve(self) -> Valve:
+        """Back to a ``Valve``; limits revalidated through ``valves.SetpointLimits``."""
+        return Valve(
+            eui=Eui64.from_str(self.eui),
+            short=self.short,
+            endpoint=self.endpoint,
+            manufacturer=self.manufacturer,
+            model=self.model,
+            sw_build=self.sw_build,
+            limits=self._limits(),
+        )
+
+    def _limits(self) -> SetpointLimits:
+        if self.limits_source == "abs":
+            return SetpointLimits.from_attrs(
+                min_c=None, max_c=None, abs_min_c=self.min_c, abs_max_c=self.max_c
+            )
+        limits = SetpointLimits.from_attrs(min_c=self.min_c, max_c=self.max_c)
+        if self.limits_source is None and limits.source != "default":
+            return dataclasses.replace(limits, source="cached")
+        return limits
+
+    def to_json(self) -> dict[str, JsonValue]:
+        return {
+            "eui": self.eui,
+            "short": self.short,
+            "endpoint": self.endpoint,
+            "manufacturer": self.manufacturer,
+            "model": self.model,
+            "sw_build": self.sw_build,
+            "min_c": self.min_c,
+            "max_c": self.max_c,
+            "limits_source": self.limits_source,
+        }
+
+    @classmethod
+    def from_json(cls, data: object) -> Self:
+        """Strict inverse of ``to_json``; ``_BadCacheError`` on any deviation."""
+        if not isinstance(data, dict):
+            raise _BadCacheError("valve entry is not an object")
+        endpoint = _int(data.get("endpoint"), *_ENDPOINT_RANGE)
+        return cls(
+            eui=_eui(data.get("eui")),
+            short=_short(data.get("short")),
+            endpoint=endpoint,
+            manufacturer=_opt_str(data.get("manufacturer")),
+            model=_opt_str(data.get("model")),
+            sw_build=_opt_str(data.get("sw_build")),
+            min_c=_opt_float(data.get("min_c")),
+            max_c=_opt_float(data.get("max_c")),
+            limits_source=_opt_source(data.get("limits_source")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeCache:
+    """Everything the integration persists between restarts (HA ``Store``). No key material.
+
+    ``own_short`` feeds ``NodeConfig.preferred_short``; valve shorts feed ``avoid_shorts``.
+    ``ignored`` are EUIs identified as not supported (not re-identified every discovery).
+    """
+
+    own_short: int | None = None
+    zdd_eui: str | None = None
+    valves: Mapping[str, CachedValve] = field(default_factory=dict)
+    ignored: frozenset[str] = frozenset()
+
+    def to_json(self) -> dict[str, JsonValue]:
+        """JSON-serialisable dict with ``"version": CACHE_VERSION``."""
+        return {
+            "version": CACHE_VERSION,
+            "own_short": self.own_short,
+            "zdd_eui": self.zdd_eui,
+            "valves": {eui: v.to_json() for eui, v in sorted(self.valves.items())},
+            "ignored": list[JsonValue](sorted(self.ignored)),
+        }
+
+    @classmethod
+    def from_json(cls, data: object) -> Self:
+        """Inverse of ``to_json``. Malformed data, or another version, yields an empty cache
+        (logged at WARNING) rather than raising: a cache is never worth a failed setup."""
+        try:
+            return cls._parse(data)
+        except (_BadCacheError, ValueError, TypeError) as exc:
+            _LOGGER.warning("ignoring the stored bridge cache: %s", _reason(exc))
+            return cls()
+
+    @classmethod
+    def _parse(cls, data: object) -> Self:
+        if not isinstance(data, dict):
+            raise _BadCacheError("not an object")
+        version = data.get("version")
+        if type(version) is not int or version != CACHE_VERSION:
+            raise _BadCacheError("unsupported version")
+        own = data.get("own_short")
+        zdd = data.get("zdd_eui")
+        raw_valves = data.get("valves", {})
+        raw_ignored = data.get("ignored", [])
+        if not isinstance(raw_valves, dict) or not isinstance(raw_ignored, list):
+            raise _BadCacheError("valves or ignored have the wrong type")
+        valves: dict[str, CachedValve] = {}
+        for key, entry in raw_valves.items():
+            valve = CachedValve.from_json(entry)
+            if _eui(key) != valve.eui:
+                raise _BadCacheError("valve key does not match its EUI")
+            valves[valve.eui] = valve
+        return cls(
+            own_short=None if own is None else _short(own),
+            zdd_eui=None if zdd is None else _eui(zdd),
+            valves=valves,
+            ignored=frozenset(_eui(item) for item in raw_ignored),
+        )
+
+
+def _reason(exc: BaseException) -> str:
+    """A log-safe reason: our own messages only (never echo the stored values)."""
+    return str(exc) if isinstance(exc, _BadCacheError) else "malformed data"
+
+
+def _int(value: object, low: int, high: int) -> int:
+    if type(value) is not int or not low <= value <= high:
+        raise _BadCacheError("integer field out of range")
+    return value
+
+
+def _short(value: object) -> int:
+    if type(value) is not int:
+        raise _BadCacheError("short address has the wrong type")
+    try:
+        return validate_short(value)
+    except ValueError as exc:
+        raise _BadCacheError("short address out of range") from exc
+
+
+def _opt_str(value: object) -> str | None:
+    if value is None or isinstance(value, str):
+        return value
+    raise _BadCacheError("string field has the wrong type")
+
+
+def _opt_float(value: object) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise _BadCacheError("number field has the wrong type")
+    if not math.isfinite(value):
+        raise _BadCacheError("number field is not finite")
+    return float(value)
+
+
+def _opt_source(value: object) -> _StoredSource | None:
+    if value is None:
+        return None
+    if value == "limits":
+        return "limits"
+    if value == "abs":
+        return "abs"
+    raise _BadCacheError("limits source is not recognised")
+
+
+def _eui(value: object) -> str:
+    if not isinstance(value, str):
+        raise _BadCacheError("EUI is not a string")
+    try:
+        return str(Eui64.from_str(value))
+    except ValueError as exc:
+        raise _BadCacheError("invalid EUI") from exc
+
+
+__all__ = ["CACHE_VERSION", "BridgeCache", "CachedValve", "JsonValue"]