pysilverline 0.2.1__py3-none-any.whl

pysilverline/__init__.py

@@ -0,0 +1,30 @@
+"""Async client for Poolex Silverline / Tuya v3.3 pool heat pumps."""
+
+from __future__ import annotations
+
+from . import const
+from .client import SilverlineClient
+from .discovery import DiscoveryInfo, discover, discover_once
+from .exceptions import (
+    CannotConnect,
+    InvalidAuth,
+    ProtocolError,
+    SilverlineError,
+)
+from .models import DeviceInfo, DeviceState
+
+__all__ = [
+    "CannotConnect",
+    "DeviceInfo",
+    "DeviceState",
+    "DiscoveryInfo",
+    "InvalidAuth",
+    "ProtocolError",
+    "SilverlineClient",
+    "SilverlineError",
+    "const",
+    "discover",
+    "discover_once",
+]
+
+__version__ = "0.2.1"

pysilverline/client.py

@@ -0,0 +1,484 @@
+"""High-level async client for a Poolex Silverline / Tuya v3.3 heat pump."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from . import const
+from .exceptions import (
+    CannotConnect,
+    IncompleteFrame,
+    InvalidAuth,
+    ProtocolError,
+    SilverlineError,
+)
+from .models import DeviceInfo, DeviceState
+from .protocol import Frame, FrameCodec, is_invalid_auth_retcode
+
+_LOGGER = logging.getLogger(__name__)
+
+_DEFAULT_REQUEST_TIMEOUT: float = 10.0
+_HEARTBEAT_INTERVAL: float = 10.0
+_RECONNECT_BACKOFF: tuple[float, ...] = (1.0, 2.0, 4.0, 8.0, 16.0, 30.0, 60.0)
+_READ_CHUNK: int = 4096
+# Hard cap on the inbound buffer when no complete frame has decoded yet. A
+# legitimate frame is < 64 KiB (see protocol._MAX_FRAME_SIZE); 256 KiB gives
+# us comfortable slack but still bounds memory growth from a hostile peer
+# that dribbles bytes after claiming an oversize header.
+_MAX_READ_BUFFER: int = 256 * 1024
+
+PushListener = Callable[[DeviceState], None]
+ConnectionListener = Callable[[bool], None]
+
+
+class SilverlineClient:
+    """Async client for one Tuya v3.3 device.
+
+    Lifecycle: ``connect()`` opens a persistent socket and starts a background
+    reader. ``get_status`` / ``set_dp`` / ``set_multiple`` issue commands.
+    Spontaneous DP pushes from the device are forwarded to listeners
+    registered via ``add_listener``. ``disconnect()`` shuts everything down.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        device_id: str,
+        local_key: str,
+        *,
+        port: int = const.DEFAULT_PORT,
+        request_timeout: float = _DEFAULT_REQUEST_TIMEOUT,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.device_id = device_id
+        self._codec = FrameCodec(local_key)
+        self._timeout = request_timeout
+
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._reader_task: asyncio.Task[None] | None = None
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._reconnect_task: asyncio.Task[None] | None = None
+        self._send_lock = asyncio.Lock()
+
+        self._pending: dict[int, asyncio.Future[Frame]] = {}
+        self._listeners: list[PushListener] = []
+        self._connection_listeners: list[ConnectionListener] = []
+        self._state = DeviceState()
+        self._closing = False
+        self._connection_lost_handled = False
+
+    @property
+    def connected(self) -> bool:
+        return self._writer is not None and not self._writer.is_closing()
+
+    @property
+    def state(self) -> DeviceState:
+        return self._state
+
+    async def connect(self) -> None:
+        """Open the TCP connection and start the background reader."""
+        if self.connected:
+            return
+        self._closing = False
+        self._connection_lost_handled = False
+        try:
+            self._reader, self._writer = await asyncio.wait_for(
+                asyncio.open_connection(self.host, self.port),
+                timeout=self._timeout,
+            )
+        except (OSError, asyncio.TimeoutError) as err:
+            raise CannotConnect(f"connect {self.host}:{self.port}: {err}") from err
+
+        self._reader_task = asyncio.create_task(
+            self._read_loop(), name=f"silverline-read-{self.host}"
+        )
+        self._heartbeat_task = asyncio.create_task(
+            self._heartbeat_loop(), name=f"silverline-hb-{self.host}"
+        )
+        self._notify_connection(True)
+
+    async def disconnect(self) -> None:
+        """Close the connection and stop background tasks.
+
+        Cancels any in-flight reconnect task too — once ``disconnect`` is
+        called, the client stays down until the caller invokes ``connect``
+        again explicitly.
+        """
+        self._closing = True
+        for task in (
+            self._heartbeat_task,
+            self._reader_task,
+            self._reconnect_task,
+        ):
+            if task and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                    pass
+        self._heartbeat_task = None
+        self._reader_task = None
+        self._reconnect_task = None
+
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(CannotConnect("client disconnecting"))
+        self._pending.clear()
+
+        if self._writer is not None:
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except OSError:
+                pass
+        self._reader = None
+        self._writer = None
+
+    def add_listener(self, callback: PushListener) -> Callable[[], None]:
+        """Register a synchronous callback for push DP updates.
+
+        Returns an unsubscribe function.
+        """
+        self._listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            try:
+                self._listeners.remove(callback)
+            except ValueError:
+                pass
+
+        return _unsubscribe
+
+    def add_connection_listener(
+        self, callback: ConnectionListener
+    ) -> Callable[[], None]:
+        """Register a synchronous callback for connection state changes.
+
+        Invoked with ``True`` after a (re)connection succeeds and ``False``
+        when the socket drops unexpectedly. Returns an unsubscribe function.
+        """
+        self._connection_listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            try:
+                self._connection_listeners.remove(callback)
+            except ValueError:
+                pass
+
+        return _unsubscribe
+
+    def _notify_connection(self, connected: bool) -> None:
+        for listener in list(self._connection_listeners):
+            try:
+                listener(connected)
+            except Exception:  # noqa: BLE001
+                _LOGGER.exception("connection listener raised")
+
+    async def get_status(self) -> DeviceState:
+        """Issue a DP_QUERY and return the resulting DeviceState."""
+        body = {
+            "gwId": self.device_id,
+            "devId": self.device_id,
+            "uid": "",
+            "t": int(time.time()),
+        }
+        frame = await self._request(const.CMD_DP_QUERY, body)
+        retcode, ciphertext = self._codec.split_response_payload(
+            frame.cmd, frame.payload
+        )
+        if is_invalid_auth_retcode(retcode):
+            raise InvalidAuth(f"DP_QUERY rejected retcode={retcode}")
+        decoded = self._codec.decrypt_body(ciphertext)
+        dps = decoded.get("dps", {}) if isinstance(decoded, dict) else {}
+        if not isinstance(dps, dict):
+            raise ProtocolError(f"unexpected dps payload: {decoded!r}")
+        # Merge rather than replace: some Tuya firmware variants only
+        # ship certain DPs in spontaneous STATUS pushes, not in
+        # DP_QUERY responses. If we replaced wholesale, those push-only
+        # DPs would flicker to None on every 30s poll. The push path
+        # already merges (_dispatch in this module); the poll path
+        # has to behave symmetrically.
+        self._state = self._state.merge(dps)
+        return self._state
+
+    async def set_dp(self, dp_id: int, value: bool | int | str) -> None:
+        """Convenience wrapper around set_multiple for a single DP."""
+        await self.set_multiple({dp_id: value})
+
+    async def set_multiple(self, values: dict[int, bool | int | str]) -> None:
+        """Send one CONTROL command updating multiple DPs atomically."""
+        if not values:
+            return
+        dps = {str(k): v for k, v in values.items()}
+        body = {
+            "devId": self.device_id,
+            "gwId": self.device_id,
+            "uid": "",
+            "t": int(time.time()),
+            "dps": dps,
+        }
+        frame = await self._request(const.CMD_CONTROL, body)
+        retcode, _ = self._codec.split_response_payload(frame.cmd, frame.payload)
+        if is_invalid_auth_retcode(retcode):
+            raise InvalidAuth(f"device rejected CONTROL retcode={retcode}")
+        if retcode not in (None, 0):
+            raise SilverlineError(f"CONTROL failed retcode=0x{retcode:08x}")
+        # The device usually echoes the new state via a push frame within
+        # ~200ms; merge optimistically so callers see the updated DPs even if
+        # they query before the push arrives.
+        self._state = self._state.merge(dps)
+
+    async def get_device_info(self) -> DeviceInfo:
+        """The Tuya local protocol does not expose firmware/model strings;
+        we return the device_id so callers can build a DeviceInfo block."""
+        return DeviceInfo(device_id=self.device_id)
+
+    async def _request(self, cmd: int, body: dict[str, Any]) -> Frame:
+        if not self.connected:
+            raise CannotConnect("not connected")
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[Frame] = loop.create_future()
+
+        async with self._send_lock:
+            wire = self._codec.encode(cmd, body)
+            # The seq the codec assigned occupies bytes 4..8 of the frame.
+            frame_seq = int.from_bytes(wire[4:8], "big")
+            self._pending[frame_seq] = future
+            try:
+                writer = self._writer
+                if writer is None:
+                    raise CannotConnect("not connected")
+                writer.write(wire)
+                await writer.drain()
+            except (OSError, ConnectionError) as err:
+                self._pending.pop(frame_seq, None)
+                raise CannotConnect(f"send: {err}") from err
+
+        try:
+            return await asyncio.wait_for(future, timeout=self._timeout)
+        except asyncio.TimeoutError as err:
+            self._pending.pop(frame_seq, None)
+            raise CannotConnect(f"timeout waiting for cmd 0x{cmd:02x}") from err
+
+    def _close_writer(self) -> None:
+        """Close the underlying writer, swallowing OS errors.
+
+        Used from the read loop when we decide to bail out (oversize
+        buffer, malformed frame); the disconnect path in the ``finally``
+        block of ``_read_loop`` then notifies listeners and schedules a
+        reconnect.
+        """
+        writer = self._writer
+        if writer is None:
+            return
+        try:
+            writer.close()
+        except OSError:
+            pass
+
+    async def _read_loop(self) -> None:
+        buf = bytearray()
+        reader = self._reader
+        if reader is None:
+            return
+        try:
+            while not self._closing:
+                try:
+                    chunk = await reader.read(_READ_CHUNK)
+                except (OSError, ConnectionError) as err:
+                    _LOGGER.debug("read error: %s", err)
+                    break
+                if not chunk:
+                    _LOGGER.debug("connection closed by peer")
+                    break
+                buf.extend(chunk)
+                if len(buf) > _MAX_READ_BUFFER:
+                    _LOGGER.warning(
+                        "read buffer exceeded %d bytes without a complete frame; "
+                        "closing connection",
+                        _MAX_READ_BUFFER,
+                    )
+                    self._close_writer()
+                    break
+                drop_connection = False
+                while len(buf) >= 24:
+                    try:
+                        frame, remainder = self._codec.decode(bytes(buf))
+                    except IncompleteFrame:
+                        # Normal case under TCP fragmentation: the wire
+                        # delivered the header but not yet the full body,
+                        # or vice versa. Stop draining and wait for the
+                        # next read to fill the gap.
+                        break
+                    except ProtocolError as err:
+                        # Bad prefix / suffix / CRC / oversize means we
+                        # are desynchronized (or talking to something
+                        # hostile). There is no safe recovery from
+                        # mid-stream garbage, so drop the connection and
+                        # let the reconnect path re-establish a fresh
+                        # session.
+                        _LOGGER.warning(
+                            "dropping connection on malformed frame: %s", err
+                        )
+                        buf.clear()
+                        drop_connection = True
+                        break
+                    buf = bytearray(remainder)
+                    self._dispatch(frame)
+                if drop_connection:
+                    self._close_writer()
+                    break
+        except asyncio.CancelledError:
+            raise
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception("read loop crashed")
+        finally:
+            for fut in self._pending.values():
+                if not fut.done():
+                    fut.set_exception(CannotConnect("connection lost"))
+            self._pending.clear()
+            self._on_connection_dropped()
+
+    def _dispatch(self, frame: Frame) -> None:
+        if frame.seq in self._pending:
+            fut = self._pending.pop(frame.seq)
+            if not fut.done():
+                fut.set_result(frame)
+            return
+
+        if frame.cmd in (const.CMD_STATUS, const.CMD_DP_REFRESH):
+            ciphertext = self._codec.split_request_payload(frame.payload)
+            try:
+                decoded = self._codec.decrypt_body(ciphertext)
+            except InvalidAuth:
+                _LOGGER.debug("ignoring undecryptable push frame")
+                return
+            dps = decoded.get("dps", {}) if isinstance(decoded, dict) else {}
+            if not isinstance(dps, dict) or not dps:
+                return
+            self._state = self._state.merge(dps)
+            for listener in list(self._listeners):
+                try:
+                    listener(self._state)
+                except Exception:  # noqa: BLE001
+                    _LOGGER.exception("push listener raised")
+
+    async def _heartbeat_loop(self) -> None:
+        try:
+            while not self._closing and self.connected:
+                await asyncio.sleep(_HEARTBEAT_INTERVAL)
+                if self._closing or not self.connected:
+                    return
+                try:
+                    await self._send_heartbeat()
+                except CannotConnect as err:
+                    _LOGGER.debug("heartbeat failed: %s", err)
+                    self._on_connection_dropped()
+                    return
+        except asyncio.CancelledError:
+            raise
+
+    async def _send_heartbeat(self) -> None:
+        async with self._send_lock:
+            writer = self._writer
+            if writer is None:
+                return
+            wire = self._codec.encode(const.CMD_HEART_BEAT, {})
+            try:
+                writer.write(wire)
+                await writer.drain()
+            except (OSError, ConnectionError) as err:
+                raise CannotConnect(f"heartbeat write: {err}") from err
+
+    def _on_connection_dropped(self) -> None:
+        """Called from inside the read/heartbeat tasks when the socket dies.
+
+        Idempotent: a single drop triggers exactly one ``False`` listener
+        callback and one reconnect task even though both background loops
+        will eventually call this on their way out.
+        """
+        if self._closing or self._connection_lost_handled:
+            return
+        self._connection_lost_handled = True
+        _LOGGER.warning("connection to %s lost; scheduling reconnect", self.host)
+        self._notify_connection(False)
+        # Schedule the reconnect from a fresh task so we don't block whichever
+        # background loop just fell over.
+        if self._reconnect_task is None or self._reconnect_task.done():
+            self._reconnect_task = asyncio.create_task(
+                self._reconnect_loop(),
+                name=f"silverline-reconnect-{self.host}",
+            )
+
+    async def _reconnect_loop(self) -> None:
+        """Walk the backoff schedule trying to reopen the socket.
+
+        The body runs inside a ``try/finally`` that clears
+        ``self._reconnect_task`` on exit. Without that, a peer that drops
+        the freshly reconnected socket *before this coroutine returns*
+        would have its ``_on_connection_dropped`` signal suppressed —
+        that callback bails when ``self._reconnect_task`` is still
+        running, leaving the client dead with no scheduled retry.
+        """
+        try:
+            # Close the dead writer so the next connect() succeeds cleanly.
+            if self._writer is not None:
+                try:
+                    self._writer.close()
+                    await self._writer.wait_closed()
+                except OSError:
+                    pass
+            self._reader = None
+            self._writer = None
+            # Reap the dead reader/heartbeat tasks before kicking new ones.
+            for task_attr in ("_reader_task", "_heartbeat_task"):
+                task: asyncio.Task[None] | None = getattr(self, task_attr)
+                if task and not task.done():
+                    task.cancel()
+                    try:
+                        await task
+                    except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                        pass
+                setattr(self, task_attr, None)
+
+            for delay in _RECONNECT_BACKOFF:
+                if self._closing:
+                    return
+                await asyncio.sleep(delay)
+                if self._closing:
+                    return
+                try:
+                    await self.connect()
+                except CannotConnect as err:
+                    _LOGGER.debug("reconnect attempt failed: %s", err)
+                    continue
+                # connect() notifies True; refresh state so listeners see
+                # fresh DPs. If the brand-new socket already died (the peer
+                # closed it mid-reconnect, and our own reader fired
+                # _on_connection_dropped while we were still the current
+                # reconnect task — so the schedule check below was a no-op),
+                # roll over to the next backoff iteration instead of
+                # returning to a dead connection.
+                try:
+                    await self.get_status()
+                except (CannotConnect, InvalidAuth) as err:
+                    _LOGGER.debug("post-reconnect refresh failed: %s", err)
+                if not self.connected:
+                    continue
+                return
+            _LOGGER.error(
+                "exhausted reconnect backoff to %s; giving up until next connect()",
+                self.host,
+            )
+        finally:
+            # Clearing this here is what makes back-to-back drops keep
+            # triggering reconnects: any drop signal that arrives after
+            # this point sees no active reconnect task and schedules a
+            # fresh one via _on_connection_dropped.
+            self._reconnect_task = None

pysilverline/const.py

@@ -0,0 +1,75 @@
+"""Constants for the Tuya v3.3 protocol and Poolex Silverline DPs."""
+
+from __future__ import annotations
+
+from typing import Final
+
+DEFAULT_PORT: Final = 6668
+DISCOVERY_PORT_PLAIN: Final = 6666
+DISCOVERY_PORT_ENCRYPTED: Final = 6667
+
+PROTOCOL_VERSION: Final = b"3.3"
+PROTOCOL_33_HEADER: Final = PROTOCOL_VERSION + b"\x00" * 12  # 15 bytes
+FRAME_PREFIX: Final = 0x000055AA
+FRAME_SUFFIX: Final = 0x0000AA55
+
+CMD_CONTROL: Final = 0x07
+CMD_STATUS: Final = 0x08
+CMD_HEART_BEAT: Final = 0x09
+CMD_DP_QUERY: Final = 0x0A
+CMD_DP_REFRESH: Final = 0x12
+
+CMDS_WITHOUT_HEADER: Final = frozenset({CMD_DP_QUERY})
+
+DP_POWER: Final = 1
+DP_TEMP_SET: Final = 2
+DP_TEMP_CURRENT: Final = 3
+DP_MODE: Final = 4
+DP_FAULT: Final = 13
+DP_EXHAUST_TEMP: Final = 101
+DP_RETURN_TEMP: Final = 102
+DP_COIL_TEMP: Final = 103
+DP_AMBIENT_TEMP: Final = 104
+DP_INLET_TEMP: Final = 105
+DP_OUTLET_TEMP: Final = 106
+DP_TARGET_FREQUENCY: Final = 107
+DP_ACTUAL_FREQUENCY: Final = 108
+DP_EEV_STEPS: Final = 109
+DP_FAN_SPEED: Final = 110
+DP_WATER_PUMP: Final = 111
+
+MODE_HEAT: Final = "Heat"
+MODE_COOL: Final = "Cool"
+MODE_AUTO: Final = "Auto"
+MODE_BOOST_HEAT: Final = "BoostHeat"
+MODE_BOOST_COOL: Final = "BoostCool"
+MODE_SILENT_HEAT: Final = "SilentHeat"
+MODE_SILENT_COOL: Final = "SilentCool"
+
+ALL_MODES: Final = frozenset(
+    {
+        MODE_HEAT,
+        MODE_COOL,
+        MODE_AUTO,
+        MODE_BOOST_HEAT,
+        MODE_BOOST_COOL,
+        MODE_SILENT_HEAT,
+        MODE_SILENT_COOL,
+    }
+)
+
+TEMP_MIN: Final = 8
+TEMP_MAX: Final = 40
+
+FAULT_BIT_NAMES: Final = {
+    0: "E03",
+    1: "E04",
+    2: "E05",
+    3: "E06",
+    4: "E09",
+    5: "E10",
+    6: "P3",
+    7: "P4",
+    8: "P1",
+    9: "P7",
+}

pysilverline/discovery.py

@@ -0,0 +1,204 @@
+"""UDP broadcast discovery for Tuya v3.3 devices.
+
+Every Tuya device that's running the standard Tuya local stack
+(WBR3 / Realtek-based modules in particular) broadcasts a small JSON
+blob announcing its presence every ~10-30 seconds, encrypted with a
+*static* AES-128-ECB key shared across the entire Tuya ecosystem:
+
+    UDP_DISCOVERY_KEY = MD5(b"yGAdlopoPVldABfn")
+
+That key is published in tinytuya and tuya-local; it's the same on
+every Tuya device, regardless of cloud account.
+
+Frame format on the wire (verified live against a Poolex PC-SLP090N
+on 2026-05-22):
+
+    [prefix 0x000055AA][seq][cmd=0x13][size][payload][crc32][suffix 0x0000AA55]
+    payload = [4 zero bytes (retcode)][AES-128-ECB ciphertext]
+
+Note that this is subtly different from the TCP push frames — the UDP
+payload has NO inner ``3.3`` header between the retcode and the
+ciphertext.
+
+Decoded JSON fields seen in the wild:
+
+    {
+        "ip":         "10.2.1.98",
+        "gwId":       "bf90769136c9ac3653oqwj",
+        "active":     2,
+        "ablility":   0,        # sic — Tuya typo, sometimes "ablilty"
+        "encrypt":    true,
+        "productKey": "3bhylhz5zhogklel",
+        "version":    "3.3"
+    }
+"""
+
+from __future__ import annotations
+
+import asyncio
+import binascii
+import hashlib
+import json
+import logging
+import struct
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from . import const
+from .protocol import aes_decrypt
+
+_LOGGER = logging.getLogger(__name__)
+
+CMD_UDP: int = 0x13
+UDP_DISCOVERY_KEY: bytes = hashlib.md5(b"yGAdlopoPVldABfn").digest()
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class DiscoveryInfo:
+    """One device announcement parsed from a UDP broadcast."""
+
+    device_id: str
+    ip: str
+    version: str = "3.3"
+    product_key: str | None = None
+    encrypt: bool = True
+
+
+def _decode_broadcast(data: bytes, *, encrypted: bool) -> DiscoveryInfo | None:
+    """Parse a single UDP datagram. Returns None on any malformation —
+    discovery must tolerate any garbage that lands on the listening port."""
+    if len(data) < 24:
+        return None
+    try:
+        prefix, _seq, _cmd, size = struct.unpack(">IIII", data[:16])
+    except struct.error:
+        return None
+    if prefix != const.FRAME_PREFIX:
+        return None
+    total = 16 + size
+    if len(data) < total:
+        return None
+    # Last 8 bytes are crc32 + suffix; validate CRC so we don't decrypt junk.
+    expected_crc, suffix = struct.unpack(">II", data[total - 8 : total])
+    if suffix != const.FRAME_SUFFIX:
+        return None
+    if expected_crc != binascii.crc32(data[: total - 8]) & 0xFFFFFFFF:
+        return None
+    payload = data[16 : total - 8]
+    if len(payload) < 4:
+        return None
+    # UDP discovery payloads always carry a 4-byte zero retcode; the rest
+    # is either plaintext JSON (port 6666) or AES-128-ECB ciphertext (port 6667).
+    body = payload[4:]
+    if encrypted:
+        if len(body) == 0 or len(body) % 16 != 0:
+            return None
+        try:
+            plaintext = aes_decrypt(body, UDP_DISCOVERY_KEY)
+        except Exception:  # noqa: BLE001 — codec raises ProtocolError/ValueError/InvalidAuth
+            return None
+    else:
+        plaintext = body
+    try:
+        parsed: Any = json.loads(plaintext)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    gw_id = parsed.get("gwId")
+    ip = parsed.get("ip")
+    if not isinstance(gw_id, str) or not isinstance(ip, str):
+        return None
+    return DiscoveryInfo(
+        device_id=gw_id,
+        ip=ip,
+        version=str(parsed.get("version", "3.3")),
+        product_key=parsed.get("productKey") if isinstance(parsed.get("productKey"), str) else None,
+        encrypt=bool(parsed.get("encrypt", encrypted)),
+    )
+
+
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    """Pushes parsed DiscoveryInfo events onto an asyncio.Queue."""
+
+    def __init__(
+        self, queue: asyncio.Queue[DiscoveryInfo], *, encrypted: bool
+    ) -> None:
+        self._queue = queue
+        self._encrypted = encrypted
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        info = _decode_broadcast(data, encrypted=self._encrypted)
+        if info is None:
+            return
+        try:
+            self._queue.put_nowait(info)
+        except asyncio.QueueFull:
+            _LOGGER.debug("discovery queue full; dropping %s", info.device_id)
+
+
+async def _bind_listeners(
+    queue: asyncio.Queue[DiscoveryInfo],
+) -> tuple[asyncio.DatagramTransport, asyncio.DatagramTransport]:
+    """Bind to both Tuya discovery ports. Returns the two transports
+    so callers can close them when done."""
+    loop = asyncio.get_running_loop()
+    t_plain, _ = await loop.create_datagram_endpoint(
+        lambda: _DiscoveryProtocol(queue, encrypted=False),
+        local_addr=("0.0.0.0", const.DISCOVERY_PORT_PLAIN),
+        allow_broadcast=True,
+        reuse_port=True,
+    )
+    t_enc, _ = await loop.create_datagram_endpoint(
+        lambda: _DiscoveryProtocol(queue, encrypted=True),
+        local_addr=("0.0.0.0", const.DISCOVERY_PORT_ENCRYPTED),
+        allow_broadcast=True,
+        reuse_port=True,
+    )
+    return t_plain, t_enc
+
+
+async def discover_once(timeout: float = 15.0) -> list[DiscoveryInfo]:
+    """Listen for UDP broadcasts for ``timeout`` seconds.
+
+    Returns the set of unique devices seen (deduplicated by ``device_id``).
+    Returns an empty list if no devices announce in the window. Never
+    raises on garbage input.
+    """
+    queue: asyncio.Queue[DiscoveryInfo] = asyncio.Queue()
+    t_plain, t_enc = await _bind_listeners(queue)
+    seen: dict[str, DiscoveryInfo] = {}
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    try:
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                break
+            try:
+                info = await asyncio.wait_for(queue.get(), timeout=remaining)
+            except asyncio.TimeoutError:
+                break
+            seen[info.device_id] = info
+    finally:
+        t_plain.close()
+        t_enc.close()
+    return list(seen.values())
+
+
+async def discover() -> AsyncIterator[DiscoveryInfo]:
+    """Listen indefinitely for UDP broadcasts.
+
+    Yields every parsed announcement (no deduplication — callers that
+    care can track ``device_id``s themselves). Cancel the task to stop.
+    """
+    queue: asyncio.Queue[DiscoveryInfo] = asyncio.Queue()
+    t_plain, t_enc = await _bind_listeners(queue)
+    try:
+        while True:
+            info = await queue.get()
+            yield info
+    finally:
+        t_plain.close()
+        t_enc.close()

pysilverline/exceptions.py

@@ -0,0 +1,30 @@
+"""Exceptions raised by pysilverline."""
+
+from __future__ import annotations
+
+
+class SilverlineError(Exception):
+    """Base error."""
+
+
+class CannotConnect(SilverlineError):
+    """Network or transport-level failure."""
+
+
+class InvalidAuth(SilverlineError):
+    """The local_key was rejected by the device."""
+
+
+class ProtocolError(SilverlineError):
+    """The frame was malformed or out of spec."""
+
+
+class IncompleteFrame(SilverlineError):
+    """Not malformed — just not all bytes have arrived yet.
+
+    Distinct from ProtocolError so callers can tell the difference
+    between "drop the connection, we're desynchronized" (ProtocolError)
+    and "wait for the next chunk and try again" (IncompleteFrame).
+    TCP is free to split any frame across read boundaries, so this
+    is the normal case, not an error condition.
+    """

pysilverline/models.py

@@ -0,0 +1,95 @@
+"""Typed data models for device state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import const
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class DeviceInfo:
+    """Static device identity. Tuya v3.3 does not return a model string;
+    fields are populated from the config entry plus what we infer."""
+
+    device_id: str
+    firmware: str | None = None
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class DeviceState:
+    """Snapshot of all known DPs at a point in time. Missing DPs are None."""
+
+    power: bool | None = None
+    temp_set: int | None = None
+    temp_current: int | None = None
+    mode: str | None = None
+    fault: int | None = None
+    exhaust_temp: int | None = None
+    return_temp: int | None = None
+    coil_temp: int | None = None
+    ambient_temp: int | None = None
+    inlet_temp: int | None = None
+    outlet_temp: int | None = None
+    target_frequency: int | None = None
+    actual_frequency: int | None = None
+    eev_steps: int | None = None
+    fan_speed: int | None = None
+    water_pump: bool | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dps(cls, dps: dict[str, Any]) -> DeviceState:
+        """Build a DeviceState from a Tuya `dps` mapping (string keys).
+
+        Coerces each DP through a type filter rather than trusting the
+        wire payload — a malformed frame or a firmware that ships a
+        string where we expect an int would otherwise propagate into
+        entity arithmetic (e.g. `d.temp_set - d.temp_current`) and
+        break consumers in surprising ways. The defensive choice for a
+        DP whose value does not match its declared type is to expose
+        it as None and keep the raw dict intact for diagnostics.
+        """
+
+        def _bool(dp: int) -> bool | None:
+            value = dps.get(str(dp))
+            return value if isinstance(value, bool) else None
+
+        def _int(dp: int) -> int | None:
+            value = dps.get(str(dp))
+            # bool is a subclass of int in Python; reject it explicitly
+            # so a power-style DP doesn't accidentally satisfy an int DP.
+            if isinstance(value, bool):
+                return None
+            return value if isinstance(value, int) else None
+
+        def _str(dp: int) -> str | None:
+            value = dps.get(str(dp))
+            return value if isinstance(value, str) else None
+
+        return cls(
+            power=_bool(const.DP_POWER),
+            temp_set=_int(const.DP_TEMP_SET),
+            temp_current=_int(const.DP_TEMP_CURRENT),
+            mode=_str(const.DP_MODE),
+            fault=_int(const.DP_FAULT),
+            exhaust_temp=_int(const.DP_EXHAUST_TEMP),
+            return_temp=_int(const.DP_RETURN_TEMP),
+            coil_temp=_int(const.DP_COIL_TEMP),
+            ambient_temp=_int(const.DP_AMBIENT_TEMP),
+            inlet_temp=_int(const.DP_INLET_TEMP),
+            outlet_temp=_int(const.DP_OUTLET_TEMP),
+            target_frequency=_int(const.DP_TARGET_FREQUENCY),
+            actual_frequency=_int(const.DP_ACTUAL_FREQUENCY),
+            eev_steps=_int(const.DP_EEV_STEPS),
+            fan_speed=_int(const.DP_FAN_SPEED),
+            water_pump=_bool(const.DP_WATER_PUMP),
+            raw=dict(dps),
+        )
+
+    def merge(self, dps: dict[str, Any]) -> DeviceState:
+        """Return a new state with `dps` overlaid onto the current `raw` dict."""
+
+        merged = {**self.raw, **dps}
+        return DeviceState.from_dps(merged)

pysilverline/protocol.py

@@ -0,0 +1,224 @@
+"""Tuya local protocol v3.3 frame codec.
+
+A frame on the wire is:
+
+    [prefix:4][seq:4][cmd:4][size:4][payload:N][crc32:4][suffix:4]
+
+with `size = N + 8`. CRC32 is computed over everything before the CRC bytes.
+All multi-byte integers are big-endian.
+
+Payloads for outbound CONTROL/REFRESH commands are prefixed with 15 bytes of
+v3.3 header (b"3.3" + 12 nulls) before AES encryption; DP_QUERY (0x0a) is
+encrypted directly. Inbound payloads start with a 4-byte return code on most
+command echoes, optionally followed by the v3.3 header and the AES-encrypted
+JSON body.
+"""
+
+from __future__ import annotations
+
+import binascii
+import itertools
+import json
+import struct
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from . import const
+from .exceptions import IncompleteFrame, InvalidAuth, ProtocolError
+
+_HEADER_FMT = ">IIII"  # prefix, seq, cmd, size
+_HEADER_SIZE = struct.calcsize(_HEADER_FMT)
+_FOOTER_FMT = ">II"  # crc32, suffix
+_FOOTER_SIZE = struct.calcsize(_FOOTER_FMT)
+_BLOCK_SIZE = 16  # AES-128 block size
+# Upper bound on the wire-claimed `size` field. Real Tuya frames from a heat
+# pump are well under 1 KiB; capping at 64 KiB prevents a hostile LAN peer
+# from claiming a 4 GiB frame to exhaust memory while we wait for bytes.
+_MAX_FRAME_SIZE = 64 * 1024
+
+_RETCODE_INVALID_KEY = {0x00000FFF, 0xFFFFFFFF}
+
+
+def _pkcs7_pad(data: bytes) -> bytes:
+    pad_len = _BLOCK_SIZE - (len(data) % _BLOCK_SIZE)
+    return data + bytes([pad_len]) * pad_len
+
+
+def _pkcs7_unpad(data: bytes) -> bytes:
+    if not data or len(data) % _BLOCK_SIZE != 0:
+        raise ProtocolError("ciphertext length not a multiple of block size")
+    pad_len = data[-1]
+    if pad_len < 1 or pad_len > _BLOCK_SIZE:
+        raise ProtocolError("invalid PKCS#7 padding")
+    if data[-pad_len:] != bytes([pad_len]) * pad_len:
+        raise ProtocolError("corrupt PKCS#7 padding")
+    return data[:-pad_len]
+
+
+def _make_cipher(key: bytes) -> Cipher[modes.ECB]:
+    if len(key) != 16:
+        raise ValueError(f"local_key must be 16 bytes, got {len(key)}")
+    return Cipher(algorithms.AES(key), modes.ECB())
+
+
+def aes_encrypt(plaintext: bytes, key: bytes) -> bytes:
+    """AES-128-ECB encrypt with PKCS#7 padding."""
+    encryptor = _make_cipher(key).encryptor()
+    return encryptor.update(_pkcs7_pad(plaintext)) + encryptor.finalize()
+
+
+def aes_decrypt(ciphertext: bytes, key: bytes) -> bytes:
+    """AES-128-ECB decrypt with PKCS#7 unpadding."""
+    decryptor = _make_cipher(key).decryptor()
+    raw = decryptor.update(ciphertext) + decryptor.finalize()
+    return _pkcs7_unpad(raw)
+
+
+@dataclass(slots=True, kw_only=True)
+class Frame:
+    """A decoded Tuya wire frame.
+
+    ``payload`` is the raw inner bytes; use ``FrameCodec.split_response_payload``
+    or ``FrameCodec.split_request_payload`` to peel the retcode / v3.3 header
+    before decryption, depending on direction.
+    """
+
+    seq: int
+    cmd: int
+    payload: bytes
+
+
+class FrameCodec:
+    """Encodes outbound frames and decodes inbound ones for one device.
+
+    Sequence numbers monotonically increase per outbound frame; the codec is
+    not thread-safe, callers should serialize use within their own locks.
+    """
+
+    def __init__(self, local_key: str) -> None:
+        self._key = local_key.encode("utf-8")
+        if len(self._key) != 16:
+            raise ValueError("local_key must be 16 ASCII characters")
+        self._seq = itertools.count(1)
+
+    def next_seq(self) -> int:
+        return next(self._seq)
+
+    def encode(self, cmd: int, body: dict[str, Any]) -> bytes:
+        """Build a complete frame for `cmd` with JSON-serialized `body`."""
+
+        plaintext = json.dumps(body, separators=(",", ":")).encode("utf-8")
+        ciphertext = aes_encrypt(plaintext, self._key)
+        if cmd not in const.CMDS_WITHOUT_HEADER:
+            payload = const.PROTOCOL_33_HEADER + ciphertext
+        else:
+            payload = ciphertext
+
+        seq = self.next_seq()
+        size = len(payload) + _FOOTER_SIZE
+        header = struct.pack(_HEADER_FMT, const.FRAME_PREFIX, seq, cmd, size)
+        body_bytes = header + payload
+        crc = binascii.crc32(body_bytes) & 0xFFFFFFFF
+        return body_bytes + struct.pack(_FOOTER_FMT, crc, const.FRAME_SUFFIX)
+
+    def decode(self, data: bytes) -> tuple[Frame, bytes]:
+        """Decode the first complete frame from `data`.
+
+        Returns the decoded frame (with its raw inner payload — the v3.3
+        header and any retcode prefix are NOT stripped here, since that
+        depends on whether the frame is a request or a response) and the
+        unconsumed remainder of the buffer.
+
+        Raises ``IncompleteFrame`` when more bytes are needed before a
+        frame can be decoded — caller should accumulate more bytes and
+        retry. Raises ``ProtocolError`` only when the bytes that have
+        arrived violate the spec (bad prefix/suffix/size/CRC), in which
+        case the connection is desynchronized and must be dropped.
+        """
+
+        if len(data) < _HEADER_SIZE + _FOOTER_SIZE:
+            raise IncompleteFrame("header not yet complete")
+        prefix, seq, cmd, size = struct.unpack(_HEADER_FMT, data[:_HEADER_SIZE])
+        # Validate the prefix BEFORE the size cap: a peer that sends
+        # garbage shaped vaguely like a Tuya frame might also produce a
+        # plausibly-sized but bogus size field, and we want the more
+        # specific "bad prefix" diagnostic in the logs.
+        if prefix != const.FRAME_PREFIX:
+            raise ProtocolError(f"bad prefix 0x{prefix:08x}")
+        if size > _MAX_FRAME_SIZE:
+            raise ProtocolError(f"frame too large: {size}")
+        total = _HEADER_SIZE + size
+        if len(data) < total:
+            raise IncompleteFrame(f"need {total - len(data)} more bytes")
+
+        payload_end = total - _FOOTER_SIZE
+        payload = data[_HEADER_SIZE:payload_end]
+        crc, suffix = struct.unpack(_FOOTER_FMT, data[payload_end:total])
+        if suffix != const.FRAME_SUFFIX:
+            raise ProtocolError(f"bad suffix 0x{suffix:08x}")
+        if crc != binascii.crc32(data[:payload_end]) & 0xFFFFFFFF:
+            raise ProtocolError("CRC mismatch")
+
+        return Frame(seq=seq, cmd=cmd, payload=payload), data[total:]
+
+    @staticmethod
+    def split_response_payload(cmd: int, payload: bytes) -> tuple[int | None, bytes]:
+        """Peel a 4-byte retcode and a v3.3 header off a response payload.
+
+        Use this on frames received in response to commands we sent
+        (CONTROL/DP_QUERY/DP_REFRESH). Spontaneous pushes (CMD_STATUS,
+        CMD_HEART_BEAT) carry no retcode, so callers should pass them
+        directly to ``decrypt_body``.
+        """
+        retcode: int | None = None
+        body = payload
+        if cmd in (const.CMD_CONTROL, const.CMD_DP_QUERY, const.CMD_DP_REFRESH):
+            if len(body) >= 4:
+                retcode = struct.unpack(">I", body[:4])[0]
+                body = body[4:]
+        if body.startswith(const.PROTOCOL_VERSION):
+            body = body[len(const.PROTOCOL_33_HEADER):]
+        return retcode, body
+
+    @staticmethod
+    def split_request_payload(payload: bytes) -> bytes:
+        """Strip the optional v3.3 header from a push frame payload.
+
+        Real WBR3 firmwares send spontaneous ``CMD_STATUS`` pushes shaped
+        as ``[4-byte zero retcode][v3.3 header][ciphertext]``, even though
+        the Tuya protocol notes describe pushes as headerless. We peel
+        either shape so push DPs decrypt correctly.
+        """
+        if payload.startswith(const.PROTOCOL_VERSION):
+            return payload[len(const.PROTOCOL_33_HEADER):]
+        if len(payload) >= 4 and payload[4:].startswith(const.PROTOCOL_VERSION):
+            return payload[4 + len(const.PROTOCOL_33_HEADER):]
+        return payload
+
+    def decrypt_body(self, body: bytes) -> dict[str, Any]:
+        """Decrypt a payload body and parse it as JSON.
+
+        Empty bodies return an empty dict; a non-JSON or auth-rejected
+        ciphertext raises InvalidAuth so the caller can trigger a reauth flow.
+        """
+
+        if not body:
+            return {}
+        try:
+            plaintext = aes_decrypt(body, self._key)
+        except (ProtocolError, ValueError) as err:
+            raise InvalidAuth("decryption failed — local_key likely wrong") from err
+        try:
+            parsed = json.loads(plaintext)
+        except (UnicodeDecodeError, json.JSONDecodeError) as err:
+            raise InvalidAuth("decrypted payload is not JSON") from err
+        if not isinstance(parsed, dict):
+            raise InvalidAuth(f"decrypted payload is not a JSON object: {type(parsed).__name__}")
+        return parsed
+
+
+def is_invalid_auth_retcode(retcode: int | None) -> bool:
+    """Some firmwares signal a wrong local_key with these return codes."""
+    return retcode is not None and retcode in _RETCODE_INVALID_KEY

pysilverline-0.2.1.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: pysilverline
+Version: 0.2.1
+Summary: Async client for Poolex Silverline / Tuya v3.3 pool heat pumps.
+Project-URL: Homepage, https://github.com/christianreiss/ha-silverline
+Project-URL: Issues, https://github.com/christianreiss/ha-silverline/issues
+Author-email: Christian Reiss <email@christian-reiss.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: heatpump,home-assistant,poolex,silverline,tuya
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: cryptography>=41.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pysilverline
+
+Async client for **Poolex Silverline / Tuya v3.3** pool heat pumps. Speaks the
+local Tuya protocol (TCP/6668, AES-128-ECB) directly — no cloud, no Smart Life
+account at runtime.
+
+This package is the I/O layer underneath the
+[`poolex_silverline`](https://github.com/christianreiss/ha-silverline) Home
+Assistant integration but works standalone too.
+
+## Install
+
+```bash
+pip install pysilverline
+```
+
+## Use
+
+```python
+import asyncio
+from pysilverline import SilverlineClient
+
+async def main():
+    client = SilverlineClient(
+        host="10.0.0.50",
+        device_id="bf1234567890abcdefghij",
+        local_key="0123456789abcdef",
+    )
+    await client.connect()
+    state = await client.get_status()
+    print(state)
+    await client.set_dp(2, 28)        # set target temp to 28 °C
+    await client.set_dp(4, "BoostHeat")
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+Listen for spontaneous push updates from the device:
+
+```python
+def on_update(state):
+    print("push:", state.mode, state.temp_current)
+
+unsub = client.add_listener(on_update)
+# ... later
+unsub()
+```
+
+## Compatible devices
+
+The Tuya schema is shared across the Poolex Silverline FI family and several
+OEM siblings: Poolex JetLine Selection FI, Steinbach Silent Mini, Brustec BR
+series, Phalén Calidi XP. DPs 1, 2, 3, 4, 13 are confirmed across the family;
+DPs 101–111 are firmware-dependent.
+
+## License
+
+MIT

pysilverline-0.2.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pysilverline/__init__.py,sha256=kkEFBWeO_XpLWZiIuXtkoBQU2K8Pd6EX2t9dNFwYIzs,628
+pysilverline/client.py,sha256=uQ1Dbdze4h3bFQU1fOoZJ_oSMwFUVs92_fs0mIAPQeE,19235
+pysilverline/const.py,sha256=p_lD2_ZJrpWlLazArVO8GW1tCrwz9YCBmexWm8ni-XY,1665
+pysilverline/discovery.py,sha256=bzqjjipM2jIthfjQJPaenRHdKZvsItwVK8qOz-UNRIY,6758
+pysilverline/exceptions.py,sha256=ahmODhZEr8s08ZggmY4Gx0ImlAfe5G2v3I1OyfvO5T0,835
+pysilverline/models.py,sha256=5JGBw_e5XMjIaQUsDSiSev0fGaNk55g_N1myR454PC0,3539
+pysilverline/protocol.py,sha256=L2wSV9y2a5iwvZc5gx2DHribasdLF8VTckUS44LJors,8934
+pysilverline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pysilverline-0.2.1.dist-info/METADATA,sha256=UvZAawiUl8Nz_ZNyRlT4KodenoJbIhOb9VKOi13osqw,2318
+pysilverline-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pysilverline-0.2.1.dist-info/licenses/LICENSE,sha256=_TcJXhABY2mEfjP6dLgAghPRnVus7cj7Y_RzJg17xXo,1072
+pysilverline-0.2.1.dist-info/RECORD,,

pysilverline-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pysilverline-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Reiss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.