pyronix-cloud 0.1.0__py3-none-any.whl

pyronix_cloud/__init__.py

@@ -0,0 +1,110 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Async client for Pyronix panels via the Pyronix Cloud (HomeControl2) relay.
+
+The protocol is specified in PROTOCOL.md at the repository root.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from pyronix_cloud.backoff import Backoff
+from pyronix_cloud.client import PyronixClient
+from pyronix_cloud.cloud import LIVE_URL, TEST_URL
+from pyronix_cloud.errors import (
+    AccessDeniedError,
+    AuthenticationError,
+    CloudError,
+    CommandNotConfirmedError,
+    CommunicationError,
+    ConnectionClosedError,
+    DocumentError,
+    FrameError,
+    HandshakeError,
+    NotConnectedError,
+    NotPermittedError,
+    PanelBusyError,
+    PanelOfflineError,
+    ProtocolError,
+    PyronixError,
+    PyronixTimeoutError,
+    SubscriptionExpiredError,
+    UnknownCloudReplyError,
+)
+from pyronix_cloud.models import (
+    Area,
+    AreaDocument,
+    AreaEvent,
+    AreaStatus,
+    FaultDocument,
+    Input,
+    InputDocument,
+    InputState,
+    LogDocument,
+    LogEntry,
+    Output,
+    OutputDocument,
+    PanelDocument,
+    PanelFault,
+    PanelInfo,
+    SetType,
+    UnknownDocument,
+    User,
+    UserDocument,
+)
+from pyronix_cloud.panel_state import PanelSnapshot
+from pyronix_cloud.settings import Credentials, Timeouts
+from pyronix_cloud.websocket import aiohttp_connector
+
+try:
+    __version__ = version("pyronix-cloud")
+except PackageNotFoundError:  # pragma: no cover - only when run from a raw checkout
+    __version__ = "0.0.0"
+
+__all__ = [
+    "LIVE_URL",
+    "TEST_URL",
+    "AccessDeniedError",
+    "Area",
+    "AreaDocument",
+    "AreaEvent",
+    "AreaStatus",
+    "AuthenticationError",
+    "Backoff",
+    "CloudError",
+    "CommandNotConfirmedError",
+    "CommunicationError",
+    "ConnectionClosedError",
+    "Credentials",
+    "DocumentError",
+    "FaultDocument",
+    "FrameError",
+    "HandshakeError",
+    "Input",
+    "InputDocument",
+    "InputState",
+    "LogDocument",
+    "LogEntry",
+    "NotConnectedError",
+    "NotPermittedError",
+    "Output",
+    "OutputDocument",
+    "PanelBusyError",
+    "PanelDocument",
+    "PanelFault",
+    "PanelInfo",
+    "PanelOfflineError",
+    "PanelSnapshot",
+    "ProtocolError",
+    "PyronixClient",
+    "PyronixError",
+    "PyronixTimeoutError",
+    "SetType",
+    "SubscriptionExpiredError",
+    "Timeouts",
+    "UnknownCloudReplyError",
+    "UnknownDocument",
+    "User",
+    "UserDocument",
+    "__version__",
+    "aiohttp_connector",
+]

pyronix_cloud/announce.py

@@ -0,0 +1,107 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Decode the panel's ``a`` announce: System ID, modem type and key extra bytes.
+
+PROTOCOL.md §4.4 (step 3), §4.6.
+
+The modem byte ``p[1]`` is read unsigned, fixing the app bug that left 0x81-0x86
+as ``UNKNOWN``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import enum
+from typing import Final
+
+_FLAGS_AT: Final = 1
+_ID_START: Final = 2
+_EXTRA_START: Final = 10
+_EXTRA_MAX: Final = 4
+_EXTRA_BASE_LEN: Final = 42
+_EXTENDED: Final = 0x80
+
+
+class ModemType(enum.Enum):
+    """The panel's uplink. Values are the extended codes of §4.6 (0 = unknown)."""
+
+    UNKNOWN = 0
+    GSM = 0x84
+    GPRS = 0x85
+    WAN_LAN = 0x83
+    USB = 0x81
+    PSTN = 0x86
+    RS232 = 0x82
+
+
+_MODEM_FLAGS: Final = (
+    (0x60, ModemType.WAN_LAN),
+    (0x02, ModemType.GPRS),
+    (0x01, ModemType.GSM),
+    (0x04, ModemType.PSTN),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Announced:
+    """What the panel announced about itself, as reported to callers."""
+
+    modem: ModemType
+    """The uplink the panel reports."""
+
+    json_version: int
+    """The first key extra byte, or 0 if there is none (``getJsonVersion``)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Announce:
+    """The fields of an ``a`` announce frame."""
+
+    panel_id: bytes
+    """Payload bytes 2-9, to compare with the configured System ID."""
+
+    key_extra: bytes
+    """Up to 4 bytes mixed into the session key (``announceExtra``)."""
+
+    announced: Announced
+    """The part reported to callers."""
+
+
+def modem_type(flags: int) -> ModemType:
+    """Decode the announce modem byte.
+
+    Args:
+        flags: ``p[1]``, read unsigned (0..255).
+
+    Returns:
+        The extended code if bit 7 is set, else the first matching flag bit.
+    """
+    if flags & _EXTENDED:
+        return next((m for m in ModemType if m.value == flags), ModemType.UNKNOWN)
+    return next((m for bit, m in _MODEM_FLAGS if flags & bit), ModemType.UNKNOWN)
+
+
+def parse_announce(payload: bytes, frame_len: int) -> Announce:
+    """Decode a verified ``a`` frame's payload.
+
+    The extra bytes are ``p[10 : 10 + min(frame_len - 42, 4)]``, kept only when
+    bit 7 of ``p[1]`` is set, exactly as ``initialKeyMessages`` does.
+
+    Args:
+        payload: The frame payload (after the 5-byte header).
+        frame_len: The length of the whole raw frame.
+
+    Returns:
+        The decoded announce. A payload too short for a field yields a short
+        ``panel_id`` (which will not match) and flags of 0.
+    """
+    flags = payload[_FLAGS_AT] if len(payload) > _FLAGS_AT else 0
+    extra_len = min(frame_len - _EXTRA_BASE_LEN, _EXTRA_MAX)
+    extra = b""
+    if flags & _EXTENDED and extra_len > 0:
+        extra = payload[_EXTRA_START : _EXTRA_START + extra_len]
+    return Announce(
+        panel_id=payload[_ID_START:_EXTRA_START],
+        key_extra=extra,
+        announced=Announced(modem_type(flags), extra[0] if extra else 0),
+    )

pyronix_cloud/area_rules.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Decide whether a set/unset command is allowed and when the panel has confirmed it.
+
+Both checks read only a :class:`~pyronix_cloud.panel_state.PanelSnapshot`, so
+they are pure functions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from pyronix_cloud.errors import NotPermittedError
+from pyronix_cloud.models import AreaStatus
+
+if TYPE_CHECKING:
+    from pyronix_cloud.panel_state import PanelSnapshot
+
+ARMED: Final = frozenset({AreaStatus.SETTING, AreaStatus.SET, AreaStatus.ALARMED})
+"""Statuses that confirm a set command: the area left unset."""
+
+DISARMED: Final = frozenset({AreaStatus.UNSET})
+"""Statuses that confirm an unset command."""
+
+
+def all_in(
+    snapshot: PanelSnapshot, areas: tuple[int, ...], statuses: frozenset[AreaStatus]
+) -> bool:
+    """Return whether every area is known and has one of ``statuses``.
+
+    Args:
+        snapshot: The panel state.
+        areas: Area numbers.
+        statuses: The accepted statuses.
+    """
+    known = snapshot.areas
+    return all(n in known and known[n].status in statuses for n in areas)
+
+
+def check_permitted(
+    snapshot: PanelSnapshot, areas: tuple[int, ...], *, set_areas: bool
+) -> None:
+    """Raise unless the logged-in user may set (or unset) every area.
+
+    Args:
+        snapshot: The panel state, with the ``user`` document.
+        areas: Area numbers.
+        set_areas: True for a set command, False for unset.
+
+    Raises:
+        NotPermittedError: The user may not act on some of the areas (or no
+            user is known yet).
+    """
+    user = snapshot.user
+    allowed = frozenset[int]()
+    if user is not None:
+        allowed = user.set_areas if set_areas else user.unset_areas
+    denied = sorted(set(areas) - allowed)
+    if denied:
+        verb = "set" if set_areas else "unset"
+        msg = f"the user may not {verb} areas {denied}"
+        raise NotPermittedError(msg)

pyronix_cloud/backoff.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Exponential reconnect back-off with jitter for persistent sessions.
+
+Repeated failed logins may lock the panel or raise tamper alerts (AGENTS.md), so a
+persistent connection must never retry in a tight loop.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class Backoff:
+    """Delays that grow by ``factor`` per failure, capped at ``maximum``."""
+
+    def __init__(
+        self,
+        *,
+        initial: float = 5.0,
+        maximum: float = 300.0,
+        factor: float = 2.0,
+        jitter: float = 0.1,
+        rng: Callable[[], float] = random.random,
+    ) -> None:
+        """Configure the back-off.
+
+        Args:
+            initial: Delay in seconds after the first failure.
+            maximum: Upper bound for any delay, before jitter.
+            factor: Growth per consecutive failure.
+            jitter: Fraction of the delay added at random (0.1 adds up to 10 %).
+            rng: Source of uniform floats in [0, 1); injectable for tests.
+        """
+        if initial <= 0 or maximum < initial or factor < 1 or not 0 <= jitter <= 1:
+            msg = "invalid back-off parameters"
+            raise ValueError(msg)
+        self._initial = initial
+        self._maximum = maximum
+        self._factor = factor
+        self._jitter = jitter
+        self._rng = rng
+        self._failures = 0
+
+    @property
+    def failures(self) -> int:
+        """Consecutive failures since the last :meth:`reset`."""
+        return self._failures
+
+    def next_delay(self) -> float:
+        """Record a failure and return the seconds to wait before the next try."""
+        base = min(self._maximum, self._initial * self._factor**self._failures)
+        self._failures += 1
+        return base * (1 + self._jitter * self._rng())
+
+    def reset(self) -> None:
+        """Forget earlier failures after a successful connection."""
+        self._failures = 0

pyronix_cloud/client.py

@@ -0,0 +1,265 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Async client for one panel session over the cloud relay with arm and disarm commands.
+
+:class:`PyronixClient` opens a WebSocket through an injected
+:data:`~pyronix_cloud.websocket.Connector`, runs the protocol session to the end
+of the login dump (:mod:`pyronix_cloud.connection`), keeps the panel state
+(:mod:`pyronix_cloud.panel_feed`) and sends set/unset commands, waiting for the
+panel to confirm them. It never logs the app password, the user code or the
+login payload.
+"""
+
+from __future__ import annotations
+
+from contextlib import suppress
+import logging
+from typing import TYPE_CHECKING, Self
+
+from pyronix_cloud import commands
+from pyronix_cloud.area_rules import ARMED, DISARMED, all_in, check_permitted
+from pyronix_cloud.cloud import LIVE_URL, CloudIdentity
+from pyronix_cloud.connection import Connection, open_socket
+from pyronix_cloud.errors import (
+    CommandNotConfirmedError,
+    ConnectionClosedError,
+    NotConnectedError,
+    PyronixError,
+)
+from pyronix_cloud.panel_feed import PanelFeed
+from pyronix_cloud.session import ProtocolSession
+from pyronix_cloud.settings import Credentials, Timeouts
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from types import TracebackType
+
+    from pyronix_cloud.models import AreaStatus
+    from pyronix_cloud.panel_feed import SnapshotListener
+    from pyronix_cloud.panel_state import PanelSnapshot
+    from pyronix_cloud.websocket import Connector
+
+__all__ = ["Credentials", "PyronixClient", "Timeouts"]
+
+_LOGGER = logging.getLogger(__name__)
+
+type DisconnectListener = Callable[[BaseException | None], None]
+
+
+class PyronixClient:
+    """One panel session over the Pyronix Cloud relay."""
+
+    def __init__(
+        self,
+        credentials: Credentials,
+        connector: Connector,
+        *,
+        url: str = LIVE_URL,
+        timeouts: Timeouts | None = None,
+    ) -> None:
+        """Prepare the client; nothing is sent until :meth:`connect`.
+
+        Args:
+            credentials: The panel identity and secrets.
+            connector: Opens the WebSocket (see ``aiohttp_connector``).
+            url: The cloud relay URL.
+            timeouts: Phase timeouts; :class:`Timeouts` defaults if None.
+
+        Raises:
+            ValueError: A credential is malformed (the value is not echoed).
+        """
+        self._user_code = credentials.user_code
+        self._identity = CloudIdentity(
+            app_user=credentials.app_user,
+            panel_id=credentials.panel_id,
+            app_password=credentials.app_password,
+            device_id=credentials.device_id,
+            push_id=credentials.push_id,
+        )
+        commands.login(credentials.user_code)  # validate the code now, not later
+        self._connector = connector
+        self._url = url
+        self._timeouts = timeouts or Timeouts()
+        self._feed = PanelFeed(self._timeouts)
+        self._connection: Connection | None = None
+        self._connected = False
+        self._disconnect_listeners: list[DisconnectListener] = []
+
+    @property
+    def snapshot(self) -> PanelSnapshot:
+        """The latest panel state."""
+        return self._feed.snapshot
+
+    @property
+    def connected(self) -> bool:
+        """Whether a session is in data mode with its login dump complete."""
+        return self._connected
+
+    def add_listener(self, listener: SnapshotListener) -> Callable[[], None]:
+        """Call ``listener`` with each changed snapshot; returns a remover."""
+        return self._feed.add_listener(listener)
+
+    def add_disconnect_listener(
+        self, listener: DisconnectListener
+    ) -> Callable[[], None]:
+        """Call ``listener`` when a connected session ends on its own.
+
+        It gets the error, or None after a clean panel goodbye. It is not
+        called after :meth:`close`. Returns a remover.
+        """
+        self._disconnect_listeners.append(listener)
+
+        def remove() -> None:
+            with suppress(ValueError):
+                self._disconnect_listeners.remove(listener)
+
+        return remove
+
+    async def connect(self) -> PanelSnapshot:
+        """Open a session and wait for the panel's login dump.
+
+        On any failure or cancellation the goodbye is sent and the socket
+        closed before the error propagates.
+
+        Returns:
+            The snapshot once the dump is complete.
+
+        Raises:
+            RuntimeError: A session is already open.
+            CommunicationError: The cloud relay could not be reached.
+            CloudError: The cloud relay refused the session.
+            AuthenticationError: The panel rejected the credentials.
+            PyronixTimeoutError: A stage or the dump did not finish in time.
+            PyronixError: Any other protocol or socket failure.
+        """
+        if self._connection is not None:
+            msg = "the client already has a session; close it first"
+            raise RuntimeError(msg)
+        self._feed.restart()
+        session = ProtocolSession(self._identity, self._user_code)
+        connection = Connection(
+            await open_socket(self._connector, self._url, self._timeouts.connect),
+            session,
+            on_event=self._feed.handle,
+            on_end=self._on_end,
+            close_timeout=self._timeouts.close,
+        )
+        self._connection = connection
+        try:
+            await connection.start()
+            await self._feed.wait_for_dump()
+        except BaseException:
+            self._connection = None
+            await connection.close()
+            raise
+        self._connected = True
+        _LOGGER.debug("Connected; login dump complete")
+        return self.snapshot
+
+    async def arm(self, areas: Iterable[int], *, force: bool = True) -> PanelSnapshot:
+        """Set areas and wait until each is setting, set or in alarm.
+
+        Args:
+            areas: Area numbers.
+            force: Omit open inputs and set anyway (as the app does).
+
+        Returns:
+            The snapshot that confirmed the command.
+
+        Raises:
+            NotConnectedError: No session is connected.
+            ValueError: The area numbers are invalid.
+            NotPermittedError: The user may not set one of the areas.
+            CommandNotConfirmedError: The panel did not confirm in time.
+        """
+        numbers = tuple(areas)
+        connection = self._require_connection()
+        payload = commands.set_areas(numbers, force=force)
+        check_permitted(self.snapshot, numbers, set_areas=True)
+        await connection.send_command(payload)
+        return await self._confirm(numbers, ARMED)
+
+    async def disarm(self, areas: Iterable[int]) -> PanelSnapshot:
+        """Unset areas and wait until each is unset.
+
+        Args:
+            areas: Area numbers.
+
+        Returns:
+            The snapshot that confirmed the command (at once, without sending,
+            if every area is already unset).
+
+        Raises:
+            NotConnectedError: No session is connected.
+            ValueError: The area numbers are invalid.
+            NotPermittedError: The user may not unset one of the areas.
+            CommandNotConfirmedError: The panel did not confirm in time.
+        """
+        numbers = tuple(areas)
+        connection = self._require_connection()
+        payload = commands.unset_areas(numbers)
+        check_permitted(self.snapshot, numbers, set_areas=False)
+        if all_in(self.snapshot, numbers, DISARMED):
+            return self.snapshot
+        await connection.send_command(payload)
+        return await self._confirm(numbers, DISARMED)
+
+    async def close(self) -> None:
+        """Say goodbye and close the socket.
+
+        Idempotent. The goodbye completes even if the caller is cancelled, and
+        takes at most ``Timeouts.close``.
+        """
+        self._connected = False
+        connection, self._connection = self._connection, None
+        if connection is not None:
+            await connection.close()
+            self._feed.end(ConnectionClosedError("the client closed the session"))
+
+    async def __aenter__(self) -> Self:
+        """Connect and return the client."""
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Close the session."""
+        await self.close()
+
+    def _require_connection(self) -> Connection:
+        """Return the connection, or raise if no session is connected."""
+        if not self._connected or self._connection is None:
+            msg = "the panel session is not connected"
+            raise NotConnectedError(msg)
+        return self._connection
+
+    async def _confirm(
+        self, numbers: tuple[int, ...], statuses: frozenset[AreaStatus]
+    ) -> PanelSnapshot:
+        """Wait until every area in ``numbers`` reaches one of ``statuses``."""
+        return await self._feed.wait_until(
+            lambda snapshot: all_in(snapshot, numbers, statuses),
+            self._timeouts.command,
+            lambda: CommandNotConfirmedError(f"areas {list(numbers)} not confirmed"),
+        )
+
+    def _on_end(self, error: PyronixError | None) -> None:
+        """Record that the session ended and tell the disconnect listeners."""
+        self._feed.end(error)
+        was_connected, self._connected = self._connected, False
+        if not was_connected:
+            return
+        self._connection = None
+        if error is None:
+            _LOGGER.debug("The panel ended the session")
+        else:
+            _LOGGER.warning("The panel session ended: %s", error)
+        for listener in list(self._disconnect_listeners):
+            try:
+                listener(error)
+            except Exception:
+                _LOGGER.exception("Error in a disconnect listener")