pycomap 1.1.0__tar.gz → 2.1.0__tar.gz

{pycomap-1.1.0 → pycomap-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycomap
-Version: 1.1.0
+Version: 2.1.0
 Summary: Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol
 Author: Igor Panteleyev
 Author-email: Igor Panteleyev <panteleev.igor69@gmail.com>
@@ -33,11 +33,13 @@ siblings): LAN discovery and the native ECDH/AES-encrypted control protocol on p
 ## Quick start
 
 ```python
+from ipaddress import IPv4Address
+
 from pycomap import Controller, EthernetTransport
 from pycomap.protocol import ComApClient
 
 async with Controller(
-    ComApClient(EthernetTransport("192.168.1.9")),
+    ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))),
     access_code="0",   # factory default (drives ECDH key derivation)
     password=1234,     # write-protection password (0-9999); omit for read-only
 ) as ctrl:

{pycomap-1.1.0 → pycomap-2.1.0}/README.md

@@ -6,11 +6,13 @@ siblings): LAN discovery and the native ECDH/AES-encrypted control protocol on p
 ## Quick start
 
 ```python
+from ipaddress import IPv4Address
+
 from pycomap import Controller, EthernetTransport
 from pycomap.protocol import ComApClient
 
 async with Controller(
-    ComApClient(EthernetTransport("192.168.1.9")),
+    ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))),
     access_code="0",   # factory default (drives ECDH key derivation)
     password=1234,     # write-protection password (0-9999); omit for read-only
 ) as ctrl:

{pycomap-1.1.0 → pycomap-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pycomap"
-version = "1.1.0"
+version = "2.1.0"
 description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
 readme = "README.md"
 license = "MIT"
@@ -33,11 +33,12 @@ Issues = "https://github.com/igor-panteleev/pycomap/issues"
 Changelog = "https://github.com/igor-panteleev/pycomap/releases"
 
 [build-system]
-requires = ["uv_build>=0.9.26,<0.10.0"]
+requires = ["uv_build>=0.9.26,<0.12.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "ifaddr>=0.2.0",
     "mkdocs>=1.6,<2",
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",
@@ -89,4 +90,5 @@ known-first-party = ["pycomap"]
 python-version = "3.14"
 
 [tool.uv]
+required-version = ">=0.11.24"
 publish-url = "https://upload.pypi.org/legacy/"

{pycomap-1.1.0 → pycomap-2.1.0}/src/pycomap/__init__.py

@@ -2,9 +2,11 @@
 
 Quick start::
 
+    from ipaddress import IPv4Address
+
     from pycomap import Command, Controller, EthernetTransport, discover
 
-    async with ComApClient(EthernetTransport("192.168.1.9")) as client:
+    async with ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))) as client:
         await client.authenticate("0")
         await client.elevate_access(password)
         result = await client.execute_command(Command.FAULT_RESET)

{pycomap-1.1.0 → pycomap-2.1.0}/src/pycomap/controller.py

@@ -6,6 +6,8 @@ elevation for protected setpoints, and timezone-aware time synchronisation.
 
 Typical usage::
 
+    from ipaddress import IPv4Address
+
     import pytz
     from pycomap import Controller
     from pycomap.protocol import ComApClient
@@ -13,7 +15,7 @@ Typical usage::
 
     tz = pytz.timezone("Europe/Kiev")
     async with Controller(
-        ComApClient(EthernetTransport("192.168.1.9")),
+        ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))),
         access_code="0",
         password=1234,
     ) as ctrl:
@@ -29,6 +31,7 @@ import logging
 import re
 from collections.abc import Mapping
 from types import MappingProxyType, TracebackType
+from typing import Self
 
 from pycomap.alarms import AlarmRecord, parse_alarm_list
 from pycomap.configuration import (
@@ -59,6 +62,7 @@ from pycomap.history import HistoryRecord, parse_history_record
 from pycomap.protocol.client import ComApClient
 from pycomap.protocol.commands import ControllerCommand
 from pycomap.protocol.objects import CommunicationObject
+from pycomap.protocol.transport import Transport
 
 _log = logging.getLogger(__name__)
 
@@ -131,7 +135,7 @@ def _encode_setpoint_value(
     return encode_raw_value(data_type, value, decimal_places)
 
 
-class Controller:
+class Controller[TransportT: Transport]:
     """High-level async client for a ComAp controller.
 
     Fetches and caches the ``ConfigurationTable`` on [connect][pycomap.Controller.connect],
@@ -154,14 +158,14 @@ class Controller:
         Read-only access::
 
             async with Controller(
-                ComApClient(EthernetTransport("192.168.1.9")), access_code="0"
+                ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))), access_code="0"
             ) as ctrl:
                 values = await ctrl.read_values()
 
         With write access::
 
             async with Controller(
-                ComApClient(EthernetTransport("192.168.1.9")),
+                ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))),
                 access_code="0",
                 password=1234,
             ) as ctrl:
@@ -170,7 +174,7 @@ class Controller:
 
     def __init__(
         self,
-        client: ComApClient,
+        client: ComApClient[TransportT],
         access_code: str,
         password: int | None = None,
         include_invisible: bool = False,
@@ -205,7 +209,7 @@ class Controller:
         """Close the underlying transport."""
         await self._client.close()
 
-    async def __aenter__(self) -> Controller:
+    async def __aenter__(self) -> Self:
         await self.connect()
         return self
 
@@ -220,7 +224,7 @@ class Controller:
     # -- properties ----------------------------------------------------------
 
     @property
-    def client(self) -> ComApClient:
+    def client(self) -> ComApClient[TransportT]:
         """The underlying low-level client (escape hatch for direct comm object access)."""
         return self._client
 

{pycomap-1.1.0 → pycomap-2.1.0}/src/pycomap/discovery.py

@@ -1,7 +1,8 @@
 """UDP discovery of ComAp controllers on the local network.
 
 See ``docs/protocol.md`` section 1. InteliConfig broadcasts a probe to
-``<broadcast>:2413``; controllers reply unicast from port 2413. Despite living on its own
+``<subnet-broadcast>:2413`` (e.g. ``192.168.1.255``, never the global ``255.255.255.255``);
+controllers reply unicast from port 2413. Despite living on its own
 UDP port, the probe and reply are not a bespoke discovery-only format — they're a regular
 [pycomap.protocol.framing.Message][] (the exact same CRC16-validated `EthernetMessage`
 framing used by the TCP protocol on port 23): a ``SendMe`` for the ``Discovery``
@@ -18,10 +19,9 @@ from __future__ import annotations
 import asyncio
 import enum
 import logging
-import socket
 import struct
 from dataclasses import dataclass, field
-from ipaddress import IPv4Address
+from ipaddress import IPv4Address, IPv4Interface
 
 from pycomap.exceptions import ComApProtocolError
 from pycomap.protocol.framing import Operation, build_inner, parse_inner
@@ -119,7 +119,10 @@ def _parse_device(data: bytes) -> DiscoveryDevice:
     is_units_list_complete = bool(data[offset])
     offset += 1
 
-    assert offset == header_size
+    if offset != header_size:
+        raise ComApProtocolError(
+            f"discovery device header parse offset mismatch: got {offset}, expected {header_size}"
+        )
     units = [
         DiscoveryUnit(
             type=data[i],
@@ -146,11 +149,62 @@ def _parse_device(data: bytes) -> DiscoveryDevice:
     )
 
 
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    """Collects decoded ``Discovery`` replies, keyed by replying IP address."""
+
+    def __init__(self, found: dict[IPv4Address, DiscoveryDevice]) -> None:
+        self._found = found
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        try:
+            message = parse_inner(data)
+        except ComApProtocolError:
+            return
+        if message.comm_obj != CommunicationObject.DISCOVERY:
+            return
+        if message.is_error or not message.data:
+            return
+        device = _parse_device(message.data)
+        self._found[device.ip] = device
+
+
+async def _send_probe(
+    loop: asyncio.AbstractEventLoop,
+    local_ip: IPv4Address,
+    destination: IPv4Address,
+    found: dict[IPv4Address, DiscoveryDevice],
+    *,
+    allow_broadcast: bool = False,
+) -> asyncio.DatagramTransport:
+    """Bind a socket to ``local_ip`` and send a discovery probe to ``destination``.
+
+    Replies land in ``found`` (keyed by replying IP) as they arrive; the caller is responsible
+    for waiting out the collection window and closing the returned transport.
+    """
+    transport, _protocol = await loop.create_datagram_endpoint(
+        lambda: _DiscoveryProtocol(found),
+        local_addr=(str(local_ip), 0),
+        allow_broadcast=allow_broadcast,
+    )
+    _log.debug("sending discovery probe from %s to %s:%d", local_ip, destination, DISCOVERY_PORT)
+    transport.sendto(_build_probe(), (str(destination), DISCOVERY_PORT))
+    return transport
+
+
 async def discover(
+    *interfaces: IPv4Interface,
     timeout: float = 2.0,
-    broadcast_address: str | IPv4Address = "255.255.255.255",
 ) -> list[DiscoveryDevice]:
-    """Broadcast a discovery probe and collect replies for ``timeout`` seconds.
+    """Broadcast a discovery probe from each of ``interfaces`` and collect replies for
+    ``timeout`` seconds.
+
+    On a host with multiple NICs on different subnets, a probe sent to the global broadcast
+    address `255.255.255.255` only egresses via whichever interface the OS routes it through,
+    so it may never reach the controller's actual subnet — pass one `IPv4Interface` per local
+    interface you want to probe from (e.g. `IPv4Interface("192.168.1.5/24")`, your own address
+    on that subnet) to bind and broadcast on each of them; this module doesn't enumerate
+    network interfaces itself. Pass `IPv4Interface("0.0.0.0/0")` to fall back to the wildcard
+    bind + global broadcast address on a single-NIC host.
 
     Returns one [DiscoveryDevice][pycomap.discovery.DiscoveryDevice] per distinct
     replying IP address. Malformed or unrelated UDP traffic on the same port
@@ -158,39 +212,40 @@ async def discover(
     silently skipped.
     """
     loop = asyncio.get_running_loop()
-    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
-    sock.setblocking(False)
-
     found: dict[IPv4Address, DiscoveryDevice] = {}
+    transports = await asyncio.gather(
+        *(
+            _send_probe(
+                loop, interface.ip, interface.network.broadcast_address, found, allow_broadcast=True
+            )
+            for interface in interfaces
+        )
+    )
     try:
-        sock.bind(("", 0))
-        _log.debug("sending discovery probe to %s:%d", broadcast_address, DISCOVERY_PORT)
-        sock.sendto(_build_probe(), (str(broadcast_address), DISCOVERY_PORT))
-
-        end_time = loop.time() + timeout
-        while True:
-            remaining = end_time - loop.time()
-            if remaining <= 0:
-                break
-            try:
-                payload, _peer_addr = await asyncio.wait_for(
-                    loop.sock_recvfrom(sock, 4096), timeout=remaining
-                )
-            except TimeoutError:
-                break
-            try:
-                message = parse_inner(payload)
-            except ComApProtocolError:
-                continue
-            if message.comm_obj != CommunicationObject.DISCOVERY:
-                continue
-            if message.is_error or not message.data:
-                continue
-            device = _parse_device(message.data)
-            found[device.ip] = device
+        await asyncio.sleep(timeout)
     finally:
-        sock.close()
+        for transport in transports:
+            transport.close()
 
     _log.info("discovery found %d device(s)", len(found))
     return list(found.values())
+
+
+async def discover_host(ip: IPv4Address, timeout: float = 2.0) -> DiscoveryDevice | None:
+    """Send a discovery probe directly (unicast) to a known ``ip`` and wait up to ``timeout``
+    seconds for its reply.
+
+    Useful when the controller's address is already known, so there's no need to broadcast
+    and no ambiguity about which local interface/subnet to use.
+
+    Returns `None` if ``ip`` doesn't reply within ``timeout``.
+    """
+    loop = asyncio.get_running_loop()
+    found: dict[IPv4Address, DiscoveryDevice] = {}
+    transport = await _send_probe(loop, IPv4Address("0.0.0.0"), ip, found)
+    try:
+        await asyncio.sleep(timeout)
+    finally:
+        transport.close()
+
+    return found.get(ip)

{pycomap-1.1.0 → pycomap-2.1.0}/src/pycomap/protocol/client.py

@@ -6,9 +6,11 @@ the trickiest details (read/write key-format asymmetry, the single shared IV cha
 
 Typical usage::
 
+    from ipaddress import IPv4Address
+
     from pycomap.protocol.transport import EthernetTransport
 
-    async with ComApClient(EthernetTransport("192.168.1.9")) as client:
+    async with ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))) as client:
         await client.authenticate("0")
         values = await client.read_object(CommunicationObject.VALUES_ALL)
 """
@@ -21,6 +23,7 @@ import hashlib
 import logging
 import struct
 from types import TracebackType
+from typing import Self
 
 from pycomap.datatypes import decode_fdate, decode_ftime, encode_fdate, encode_ftime
 from pycomap.exceptions import (
@@ -61,18 +64,25 @@ _AUTH_FALLBACK_CODES = {
 _log = logging.getLogger(__name__)
 
 
-class ComApClient:
+class ComApClient[TransportT: Transport]:
     """Speaks the ECDH/AES-encrypted ``EthernetMessage`` protocol over any ``Transport``.
 
+    Generic over the concrete ``Transport`` type, so
+    [transport][pycomap.protocol.ComApClient.transport] gives back the type you passed in
+    (e.g. ``ComApClient[EthernetTransport]`` exposes ``.transport.host``) instead of the
+    narrower structural ``Transport`` protocol.
+
     Pass any ``Transport`` implementation — typically ``EthernetTransport``::
 
+        from ipaddress import IPv4Address
+
         from pycomap.protocol.transport import EthernetTransport
 
-        async with ComApClient(EthernetTransport("192.168.1.9")) as client:
+        async with ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))) as client:
             await client.authenticate("0")
     """
 
-    def __init__(self, transport: Transport) -> None:
+    def __init__(self, transport: TransportT) -> None:
         """
         Args:
             transport: Byte-stream transport to use (typically ``EthernetTransport``).
@@ -82,6 +92,11 @@ class ComApClient:
         self._mode = _Mode.NONE
         self._cipher: ChainedAesCbc | None = None
 
+    @property
+    def transport(self) -> TransportT:
+        """The underlying byte-stream transport."""
+        return self._transport
+
     # -- connection lifecycle -------------------------------------------------
 
     async def connect(self) -> None:
@@ -186,7 +201,7 @@ class ComApClient:
         self._mode = _Mode.NONE
         self._cipher = None
 
-    async def __aenter__(self) -> ComApClient:
+    async def __aenter__(self) -> Self:
         await self.connect()
         return self
 
@@ -344,7 +359,8 @@ class ComApClient:
 
         if self._mode is _Mode.ALIGNED:
             return block_payload
-        assert self._cipher is not None
+        if self._cipher is None:
+            raise ComApProtocolError("AES mode active but cipher not initialized")
         return self._cipher.decrypt(block_payload)
 
     async def _write_inner(self, inner: bytes) -> None:
@@ -354,5 +370,6 @@ class ComApClient:
         elif self._mode is _Mode.ALIGNED:
             await self._transport.write(wrap_outer(padded))
         else:
-            assert self._cipher is not None
+            if self._cipher is None:
+                raise ComApProtocolError("AES mode active but cipher not initialized")
             await self._transport.write(wrap_outer(self._cipher.encrypt(padded)))

{pycomap-1.1.0 → pycomap-2.1.0}/src/pycomap/protocol/transport.py

@@ -1,9 +1,8 @@
 """Transport layer abstraction for the ComAp native protocol.
 
-``Transport`` is a structural ``typing.Protocol`` — any object with the four async
-methods qualifies, no subclassing required. ``EthernetTransport`` is the only
-implementation for now; AirGate (cloud relay) and serial transports can be added later
-without changing ``ComApClient``.
+``Transport`` is an ``abc.ABC`` — implementations must subclass it and provide the four
+async methods. ``EthernetTransport`` is the only implementation for now; AirGate (cloud
+relay) and serial transports can be added later without changing ``ComApClient``.
 """
 
 from __future__ import annotations
@@ -11,8 +10,8 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import logging
+from abc import ABC, abstractmethod
 from ipaddress import IPv4Address
-from typing import Protocol, runtime_checkable
 
 from pycomap.exceptions import ComApConnectionError
 
@@ -21,49 +20,60 @@ DEFAULT_PORT = 23
 _log = logging.getLogger(__name__)
 
 
-@runtime_checkable
-class Transport(Protocol):
+class Transport(ABC):
     """Byte-stream transport used by ``ComApClient``."""
 
+    @abstractmethod
     async def connect(self) -> None:
         """Open the underlying connection."""
-        ...
 
+    @abstractmethod
     async def close(self) -> None:
         """Close the underlying connection, suppressing already-closed errors."""
-        ...
 
+    @abstractmethod
     async def read_exactly(self, n: int) -> bytes:
         """Read exactly ``n`` bytes, raising ``ComApConnectionError`` if the stream ends."""
-        ...
 
+    @abstractmethod
     async def write(self, data: bytes) -> None:
         """Write ``data`` and flush."""
-        ...
 
 
-class EthernetTransport:
+class EthernetTransport(Transport):
     """TCP transport for the ComAp native protocol (port 23).
 
     Connects to ``host:port`` via plain TCP; the ``ComApClient`` layer adds the
     ECDH/AES framing on top.
     """
 
-    def __init__(self, host: IPv4Address | str, port: int = DEFAULT_PORT) -> None:
+    def __init__(self, host: IPv4Address, port: int = DEFAULT_PORT) -> None:
         """
         Args:
-            host: Controller IP address (``IPv4Address`` or dotted string) or hostname.
+            host: Controller IP address. Exposed back via
+                [host][pycomap.protocol.EthernetTransport.host] for e.g. probing reachability
+                via [discover_host][pycomap.discovery.discover_host].
             port: TCP port; defaults to ``23`` (ComAp native protocol port).
         """
-        self._host = str(host)
+        self._host = host
         self._port = port
         self._reader: asyncio.StreamReader | None = None
         self._writer: asyncio.StreamWriter | None = None
 
+    @property
+    def host(self) -> IPv4Address:
+        """The controller's configured IP address."""
+        return self._host
+
+    @property
+    def port(self) -> int:
+        """The controller's configured TCP port."""
+        return self._port
+
     async def connect(self) -> None:
         _log.debug("connecting to %s:%d", self._host, self._port)
         try:
-            self._reader, self._writer = await asyncio.open_connection(self._host, self._port)
+            self._reader, self._writer = await asyncio.open_connection(str(self._host), self._port)
         except OSError as exc:
             raise ComApConnectionError(f"failed to connect to {self._host}:{self._port}") from exc
         _log.info("connected to %s:%d", self._host, self._port)
@@ -78,13 +88,15 @@ class EthernetTransport:
         self._writer = None
 
     async def read_exactly(self, n: int) -> bytes:
-        assert self._reader is not None
+        if self._reader is None:
+            raise ComApConnectionError("not connected — call connect() first")
         try:
             return await self._reader.readexactly(n)
         except asyncio.IncompleteReadError as exc:
             raise ComApConnectionError("connection closed while reading a message") from exc
 
     async def write(self, data: bytes) -> None:
-        assert self._writer is not None
+        if self._writer is None:
+            raise ComApConnectionError("not connected — call connect() first")
         self._writer.write(data)
         await self._writer.drain()