pycomap 1.0.2__tar.gz → 2.0.0__tar.gz

{pycomap-1.0.2 → pycomap-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycomap
-Version: 1.0.2
+Version: 2.0.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.0.2 → pycomap-2.0.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.0.2 → pycomap-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pycomap"
-version = "1.0.2"
+version = "2.0.0"
 description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
 readme = "README.md"
 license = "MIT"
@@ -38,6 +38,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "ifaddr>=0.2.0",
     "mkdocs>=1.6,<2",
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",

{pycomap-1.0.2 → pycomap-2.0.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)
@@ -29,12 +31,15 @@ from __future__ import annotations
 import logging
 
 from pycomap.controller import Controller
+from pycomap.datatypes import Value
 from pycomap.discovery import discover
 from pycomap.exceptions import (
     ComApAuthError,
     ComApConnectionError,
     ComApControllerError,
     ComApError,
+    ComApInvalidAccessCodeError,
+    ComApInvalidPasswordError,
     ComApProtocolError,
 )
 from pycomap.protocol import ComApClient, Command, ControllerCommand, EthernetTransport
@@ -47,10 +52,13 @@ __all__ = [
     "ComApConnectionError",
     "ComApControllerError",
     "ComApError",
+    "ComApInvalidAccessCodeError",
+    "ComApInvalidPasswordError",
     "ComApProtocolError",
     "Command",
     "Controller",
     "ControllerCommand",
     "EthernetTransport",
+    "Value",
     "discover",
 ]

{pycomap-1.0.2 → pycomap-2.0.0}/src/pycomap/configuration.py

@@ -33,6 +33,7 @@ from __future__ import annotations
 import dataclasses
 import enum
 import functools
+import logging
 import struct
 from collections.abc import Sequence
 from dataclasses import dataclass
@@ -41,12 +42,15 @@ from pycomap.datatypes import (
     _DATA_TYPE_LENGTH,
     DataType,
     ProtectionState,
+    RawValue,
     decode_raw_value,
     encode_raw_value,
     get_bits,
 )
 from pycomap.exceptions import ComApProtocolError
 
+_log = logging.getLogger(__name__)
+
 __all__ = [
     "ConfigurationTable",
     "NamesCategory",
@@ -465,25 +469,34 @@ def _parse_setpoints(
     return setpoints
 
 
-def decode_values_all(table: ConfigurationTable, data: bytes) -> dict[int, int | float | bytes]:
+def decode_values_all(table: ConfigurationTable, data: bytes) -> dict[int, RawValue]:
     """Decode a ``ValuesAll`` (or the data portion of ``ValueStatesAndDataAll``) blob.
 
-    Returns a mapping of value ``number`` -> decoded value, for every value in
-    ``ValueCategory.FIRST``/``SECOND``/``THIRD`` (``ONE_TIME`` values are never included in
-    these communication objects).
+    Returns a mapping of value ``number`` -> decoded value for every
+    ``ValueCategory.FIRST``/``SECOND``/``THIRD`` value. ``ONE_TIME`` values are excluded
+    — they are not present in ``ValuesAll`` and must be read individually.
     """
-    result: dict[int, int | float | bytes] = {}
+    result: dict[int, RawValue] = {}
     for value in table.values:
         if value.category is ValueCategory.ONE_TIME:
             continue
-        raw = data[value.data_index : value.data_index + value.data_length]
+        end = value.data_index + value.data_length
+        if end > len(data):
+            _log.warning(
+                "value %r (number %d) data_index %d+%d exceeds blob size %d — skipping",
+                value.name,
+                value.number,
+                value.data_index,
+                value.data_length,
+                len(data),
+            )
+            continue
+        raw = data[value.data_index : end]
         result[value.number] = decode_raw_value(value.data_type, raw, value.decimal_places)
     return result
 
 
-def decode_history_snapshot(
-    table: ConfigurationTable, snapshot: bytes
-) -> dict[int, int | float | bytes]:
+def decode_history_snapshot(table: ConfigurationTable, snapshot: bytes) -> dict[int, RawValue]:
     """Decode the value snapshot from a ``HistoryRecord.data`` field.
 
     Alarm/event history records carry a snapshot of the first N bytes of the
@@ -497,7 +510,7 @@ def decode_history_snapshot(
     [decode_values_all][pycomap.configuration.decode_values_all]. ``ONE_TIME`` values
     are never included.  Returns an empty dict if ``snapshot`` is empty (text records).
     """
-    result: dict[int, int | float | bytes] = {}
+    result: dict[int, RawValue] = {}
     for value in table.values:
         if value.category is ValueCategory.ONE_TIME:
             continue
@@ -509,12 +522,12 @@ def decode_history_snapshot(
     return result
 
 
-def decode_setpoints_all(table: ConfigurationTable, data: bytes) -> dict[int, int | float | bytes]:
+def decode_setpoints_all(table: ConfigurationTable, data: bytes) -> dict[int, RawValue]:
     """Decode a ``SetpointsAll`` blob into a mapping of setpoint ``number`` -> decoded value.
 
     Unlike values, every setpoint (both ``P`` and ``R`` categories) is included.
     """
-    result: dict[int, int | float | bytes] = {}
+    result: dict[int, RawValue] = {}
     for setpoint in table.setpoints:
         raw = data[setpoint.data_index : setpoint.data_index + setpoint.data_length]
         result[setpoint.number] = decode_raw_value(setpoint.data_type, raw, setpoint.decimal_places)

{pycomap-1.0.2 → pycomap-2.0.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:
@@ -27,13 +29,15 @@ from __future__ import annotations
 import datetime
 import logging
 import re
-from types import TracebackType
+from collections.abc import Mapping
+from types import MappingProxyType, TracebackType
 
 from pycomap.alarms import AlarmRecord, parse_alarm_list
 from pycomap.configuration import (
     ConfigurationTable,
     NamesCategory,
     SetpointDescription,
+    ValueCategory,
     ValueDescription,
     ValueState,
     decode_history_snapshot,
@@ -47,6 +51,8 @@ from pycomap.datatypes import (
     _BINARY_TYPES,
     _DATA_TYPE_LENGTH,
     DataType,
+    RawValue,
+    Value,
     decode_raw_value,
     encode_raw_value,
 )
@@ -109,7 +115,7 @@ def _parse_gmt_label(label: str) -> datetime.timedelta | None:
 def _encode_setpoint_value(
     data_type: DataType,
     decimal_places: int,
-    value: int | float | str | bytes,
+    value: Value,
 ) -> bytes:
     if isinstance(value, bytes):
         return value
@@ -131,10 +137,9 @@ class Controller:
     """High-level async client for a ComAp controller.
 
     Fetches and caches the ``ConfigurationTable`` on [connect][pycomap.Controller.connect],
-    which enables
-    name-based lookup for all subsequent calls.  Password elevation for write-protected
-    setpoints is handled automatically (lazy, on first protected write) when ``password``
-    is provided.
+    enabling name-based lookup for all subsequent calls.  Password elevation for
+    write-protected setpoints is handled automatically (lazy, on first protected write)
+    when ``password`` is provided.
 
     Args:
         client: A ``ComApClient`` wrapping any transport.  The ``Controller`` takes
@@ -143,19 +148,22 @@ class Controller:
             ``"0"``).  Drives ECDH/AES key derivation — **not** the write password.
         password: The write-protection password (integer 0-9999).  Required for setpoints
             with ``access_level > 0``; omit to operate in read-only mode.
+        include_invisible: When ``False`` (default), ONE_TIME values in the ``'Invisible'``
+            group are skipped during connect, saving one ``read_object`` round-trip per
+            invisible item.  Set to ``True`` to cache them anyway.
 
     Examples:
         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:
@@ -167,20 +175,25 @@ class Controller:
         client: ComApClient,
         access_code: str,
         password: int | None = None,
+        include_invisible: bool = False,
     ) -> None:
         self._client = client
         self._access_code = access_code
         self._password = password
+        self._include_invisible = include_invisible
         self._elevated = False
         self._config_data: bytes | None = None
         self._table: ConfigurationTable | None = None
         self._values_by_name: dict[str, ValueDescription] = {}
         self._values_by_number: dict[int, ValueDescription] = {}
+        self._ambiguous_value_names: set[str] = set()
         self._setpoints_by_name: dict[str, SetpointDescription] = {}
         self._setpoints_by_number: dict[int, SetpointDescription] = {}
+        self._ambiguous_setpoint_names: set[str] = set()
         self._common_names: list[str] = []
         self._timezone: datetime.timezone = datetime.UTC
         self._summer_time_mode_raw: int = 0
+        self._one_time_values: dict[int, Value] = {}
 
     # -- connection lifecycle -------------------------------------------------
 
@@ -235,14 +248,22 @@ class Controller:
         """All setpoint descriptions from the cached ``ConfigurationTable``."""
         return self.table.setpoints
 
+    @property
+    def one_time_values(self) -> Mapping[int, Value]:
+        """Static ``ONE_TIME`` values read once at connect time.
+
+        Returns a read-only ``{comm_object_number: value}`` mapping for every ``ONE_TIME``
+        value successfully read during [connect][pycomap.Controller.connect]. Entries use
+        the same type and resolution rules as [read_values][pycomap.Controller.read_values].
+        Empty before connect; stable for the lifetime of the connection.
+        """
+        return MappingProxyType(self._one_time_values)
+
     # -- name / number resolution --------------------------------------------
 
     def value_info(self, name_or_number: str | int) -> ValueDescription:
         """Look up a value description by name or comm object number.
 
-        Names must match exactly as returned by the controller's names heap.
-        If multiple values share a name, the first one in the table is returned.
-
         Args:
             name_or_number: Exact value name (e.g. ``"RPM"``) or comm object number.
 
@@ -251,12 +272,18 @@ class Controller:
 
         Raises:
             KeyError: If no value with that name or number exists.
+            ComApProtocolError: If the name is shared by multiple values — use a number instead.
         """
         if isinstance(name_or_number, int):
             try:
                 return self._values_by_number[name_or_number]
             except KeyError:
                 raise KeyError(f"no value with number {name_or_number}") from None
+        if name_or_number in self._ambiguous_value_names:
+            raise ComApProtocolError(
+                f"value name {name_or_number!r} is ambiguous — "
+                "multiple values share this name; use a comm object number instead"
+            )
         try:
             return self._values_by_name[name_or_number]
         except KeyError:
@@ -273,12 +300,18 @@ class Controller:
 
         Raises:
             KeyError: If no setpoint with that name or number exists.
+            ComApProtocolError: If the name is shared by multiple setpoints — use a number instead.
         """
         if isinstance(name_or_number, int):
             try:
                 return self._setpoints_by_number[name_or_number]
             except KeyError:
                 raise KeyError(f"no setpoint with number {name_or_number}") from None
+        if name_or_number in self._ambiguous_setpoint_names:
+            raise ComApProtocolError(
+                f"setpoint name {name_or_number!r} is ambiguous — "
+                "multiple setpoints share this name; use a comm object number instead"
+            )
         try:
             return self._setpoints_by_name[name_or_number]
         except KeyError:
@@ -377,9 +410,9 @@ class Controller:
 
     def _resolve_raws(
         self,
-        raw: dict[int, int | float | bytes],
+        raw: dict[int, RawValue],
         by_number: dict[int, ValueDescription] | dict[int, SetpointDescription],
-    ) -> dict[int, int | float | bytes | str]:
+    ) -> dict[int, Value]:
         """Resolve ``STRING_LIST`` wire bytes to labels and text-typed bytes to strings.
 
         Works for both value and setpoint dicts.  ``STRING_LIST`` entries arrive as 1-byte
@@ -387,7 +420,7 @@ class Controller:
         Text-typed entries (``SHORT_STRING``, ``IP_ADDRESS``, etc.) arrive as null-padded
         byte strings and are decoded to ASCII.
         """
-        result: dict[int, int | float | bytes | str] = {}
+        result: dict[int, Value] = {}
         for number, val in raw.items():
             if not isinstance(val, bytes):
                 result[number] = val
@@ -402,12 +435,12 @@ class Controller:
                     self._common_names[idx] if idx < len(self._common_names) else str(wire)
                 )
             elif desc.data_type in _STRING_TYPES:
-                result[number] = val.rstrip(b"\x00").decode("ascii", "replace")
+                result[number] = val.split(b"\x00")[0].decode("ascii", "replace")
             else:
                 result[number] = val
         return result
 
-    async def read_values(self) -> dict[int, int | float | bytes | str]:
+    async def read_values(self) -> dict[int, Value]:
         """Read all values from ``ValuesAll`` (C.O. 24560).
 
         ``STRING_LIST`` values are resolved to their display label. Text-typed values
@@ -415,8 +448,9 @@ class Controller:
         values are ``int``, ``float``, or raw ``bytes`` (binary, domain, timer types).
 
         Returns:
-            ``{comm_object_number: value}`` for every value in the controller's table
-            except ``ONE_TIME`` category values, which are excluded from ``ValuesAll``.
+            ``{comm_object_number: value}`` for every value whose data fits within the
+            ``ValuesAll`` blob, including static ``ONE_TIME`` values (firmware version,
+            ID string, etc.).
 
         Examples:
             >>> values = await ctrl.read_values()
@@ -427,7 +461,7 @@ class Controller:
         data = await self._client.read_object(CommunicationObject.VALUES_ALL)
         return self._resolve_raws(decode_values_all(self.table, data), self._values_by_number)
 
-    async def read_setpoints(self) -> dict[int, int | float | bytes | str]:
+    async def read_setpoints(self) -> dict[int, Value]:
         """Read all setpoints from ``SetpointsAll`` (C.O. 24559).
 
         ``STRING_LIST`` setpoints are resolved to their display label, matching what
@@ -471,9 +505,7 @@ class Controller:
                 records.append(rec)
         return records
 
-    def decode_history_snapshot(
-        self, record: HistoryRecord
-    ) -> dict[int, int | float | bytes | str]:
+    def decode_history_snapshot(self, record: HistoryRecord) -> dict[int, Value]:
         """Decode the value snapshot embedded in an alarm ``HistoryRecord``.
 
         Alarm/event records carry a snapshot of the ``ValuesAll`` blob captured at the
@@ -497,12 +529,14 @@ class Controller:
 
     # -- individual read/write -----------------------------------------------
 
-    async def read_value(self, name_or_number: str | int) -> int | float | bytes | str:
+    async def read_value(self, name_or_number: str | int) -> Value:
         """Read a single value by name or number.
 
         Reads ``ValuesAll`` internally — use
         [read_values][pycomap.Controller.read_values] when you need multiple
-        values to avoid redundant round-trips.
+        values to avoid redundant round-trips. For ``ONE_TIME`` static values use
+        [one_time_value][pycomap.Controller.one_time_value] or
+        [one_time_values][pycomap.Controller.one_time_values].
 
         Args:
             name_or_number: Value name or comm object number.
@@ -512,18 +546,54 @@ class Controller:
 
         Raises:
             KeyError: If no value with that name or number exists.
-            ComApProtocolError: If the value is ``ONE_TIME`` category (not in ``ValuesAll``).
+            ComApProtocolError: If the name is shared by multiple values, or if the value
+                is ``ONE_TIME`` category — use ``one_time_value()`` instead.
         """
         desc = self.value_info(name_or_number)
+        if desc.category is ValueCategory.ONE_TIME:
+            raise ComApProtocolError(
+                f"value {desc.name!r} (number {desc.number}) is ONE_TIME — "
+                "use Controller.one_time_values instead"
+            )
         values = await self.read_values()
         if desc.number not in values:
             raise ComApProtocolError(
-                f"value {desc.name!r} (number {desc.number}) is ONE_TIME and not "
-                "included in ValuesAll"
+                f"value {desc.name!r} (number {desc.number}) is not present in ValuesAll"
             )
         return values[desc.number]
 
-    async def read_setpoint(self, name_or_number: str | int) -> int | float | bytes | str:
+    def one_time_value(self, name_or_number: str | int) -> Value:
+        """Return a cached ONE_TIME value by name or number (no network call).
+
+        ONE_TIME values are read once at connect time and stored in
+        [one_time_values][pycomap.Controller.one_time_values].
+
+        Args:
+            name_or_number: Value name or comm object number.
+
+        Returns:
+            Resolved value; strings are already null-stripped.
+
+        Raises:
+            KeyError: If no value with that name or number exists in the table.
+            ComApProtocolError: If the name is shared by multiple values, if the value
+                is not ``ONE_TIME`` category, or if it was not cached (e.g. skipped as
+                invisible or failed to read at connect).
+        """
+        desc = self.value_info(name_or_number)
+        if desc.category is not ValueCategory.ONE_TIME:
+            raise ComApProtocolError(
+                f"value {desc.name!r} (number {desc.number}) is not ONE_TIME — "
+                "use read_value() instead"
+            )
+        if desc.number not in self._one_time_values:
+            raise ComApProtocolError(
+                f"ONE_TIME value {desc.name!r} (number {desc.number}) is not in cache "
+                "(skipped as invisible or failed to read at connect)"
+            )
+        return self._one_time_values[desc.number]
+
+    async def read_setpoint(self, name_or_number: str | int) -> Value:
         """Read a single setpoint by name or number (one round-trip).
 
         Args:
@@ -543,8 +613,8 @@ class Controller:
     def _coerce_setpoint_value(
         self,
         desc: SetpointDescription,
-        value: int | float | str | bytes,
-    ) -> int | float | str | bytes:
+        value: Value,
+    ) -> Value:
         """Resolve and validate ``value`` for ``desc`` before encoding.
 
         - ``STRING_LIST`` + ``str``: looks up the label in
@@ -594,9 +664,7 @@ class Controller:
 
         return value
 
-    async def set_setpoint(
-        self, name_or_number: str | int, value: int | float | str | bytes
-    ) -> None:
+    async def set_setpoint(self, name_or_number: str | int, value: Value) -> None:
         """Write a setpoint by name or number.
 
         Args:
@@ -627,7 +695,7 @@ class Controller:
         """
         desc = self.setpoint_info(name_or_number)
         if desc.needs_password:
-            await self._ensure_elevated()
+            await self.elevate_access()
         value = self._coerce_setpoint_value(desc, value)
         raw = _encode_setpoint_value(desc.data_type, desc.decimal_places, value)
         await self._client.write_object(desc.number, raw)
@@ -744,7 +812,7 @@ class Controller:
         Raises:
             ComApAuthError: If write access is needed but no password was provided.
         """
-        await self._ensure_elevated()
+        await self.elevate_access()
         effective_tz: datetime.tzinfo = tz if tz is not None else self._timezone
         now = datetime.datetime.now(datetime.UTC).astimezone(effective_tz).replace(tzinfo=None)
         await self._client.write_datetime(now)
@@ -754,24 +822,66 @@ class Controller:
     async def _load_config(self) -> None:
         self._config_data = await self._client.read_object(CommunicationObject.CONFIGURATION_TABLE)
         self._table = parse_configuration_table(self._config_data)
-        # Build name → description lookup maps.  If names are duplicated, first wins.
         self._values_by_number = {v.number: v for v in self._table.values}
         self._values_by_name = {}
+        self._ambiguous_value_names = set()
         for v in self._table.values:
-            self._values_by_name.setdefault(v.name, v)
+            if v.name in self._values_by_name:
+                self._ambiguous_value_names.add(v.name)
+            else:
+                self._values_by_name[v.name] = v
         self._setpoints_by_number = {s.number: s for s in self._table.setpoints}
         self._setpoints_by_name = {}
+        self._ambiguous_setpoint_names = set()
         for s in self._table.setpoints:
-            self._setpoints_by_name.setdefault(s.name, s)
+            if s.name in self._setpoints_by_name:
+                self._ambiguous_setpoint_names.add(s.name)
+            else:
+                self._setpoints_by_name[s.name] = s
         self._common_names = parse_names_heap(self._config_data, NamesCategory.COMMON_NAMES)
         await self.refresh_timezone()
+        await self._cache_one_time_values()
         _log.info(
-            "configuration loaded: %d values, %d setpoints",
+            "configuration loaded: %d values, %d setpoints, %d one-time",
             len(self._table.values),
             len(self._table.setpoints),
+            len(self._one_time_values),
         )
 
-    async def _ensure_elevated(self) -> None:
+    async def _cache_one_time_values(self) -> None:
+        descs = [
+            v
+            for v in self.table.values
+            if v.category is ValueCategory.ONE_TIME
+            and (self._include_invisible or v.group != "Invisible")
+        ]
+        if not descs:
+            return
+        raw_map: dict[int, RawValue] = {}
+        for desc in descs:
+            try:
+                raw = await self._client.read_object(desc.number)
+            except Exception as exc:
+                _log.warning(
+                    "failed to read ONE_TIME value %r (number %d): %s",
+                    desc.name,
+                    desc.number,
+                    exc,
+                )
+                continue
+            raw_map[desc.number] = decode_raw_value(desc.data_type, raw, desc.decimal_places)
+        self._one_time_values = self._resolve_raws(raw_map, self._values_by_number)
+
+    async def elevate_access(self) -> None:
+        """Send the write-protection password to the controller, enabling protected writes.
+
+        Idempotent — safe to call multiple times; the password is only sent once.
+        Call this early to validate the password without waiting for the first write.
+
+        Raises:
+            ComApAuthError: If no password was supplied to the ``Controller``.
+            ComApInvalidPasswordError: If the controller rejects the password.
+        """
         if self._elevated:
             return
         if self._password is None:

{pycomap-1.0.2 → pycomap-2.0.0}/src/pycomap/datatypes.py

@@ -91,6 +91,9 @@ _NUMERIC_STRUCT_FORMAT: dict[DataType, str] = {
 
 _BINARY_TYPES = (DataType.BINARY8, DataType.BINARY16, DataType.BINARY32)
 
+RawValue = int | float | bytes
+Value = int | float | bytes | str
+
 
 class ProtectionState(enum.IntFlag):
     """ComAp ``ProtectionState`` enum (``ValueState.Level1``/``Level2``/``SensorFail``).
@@ -106,9 +109,7 @@ class ProtectionState(enum.IntFlag):
     NOT_CONFIRMED = 4
 
 
-def decode_raw_value(
-    data_type: DataType, raw: bytes, decimal_places: int = 0
-) -> int | float | bytes:
+def decode_raw_value(data_type: DataType, raw: bytes, decimal_places: int = 0) -> RawValue:
     """Decode ``raw`` bytes (``len(raw) == _DATA_TYPE_LENGTH[data_type]``) per ``data_type``.
 
     Only numeric and binary(bitfield) types are decoded to Python numbers; string/domain/

{pycomap-1.0.2 → pycomap-2.0.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,9 +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, IPv4Interface
 
 from pycomap.exceptions import ComApProtocolError
 from pycomap.protocol.framing import Operation, build_inner, parse_inner
@@ -70,7 +71,7 @@ class DiscoveryDevice:
     serial_number: int
     firmware_major_minor: int
     firmware_patch_build: int
-    ip: str
+    ip: IPv4Address
     mac: str
     comm_port: int
     access_type: AccessType
@@ -103,7 +104,7 @@ def _parse_device(data: bytes) -> DiscoveryDevice:
     else:
         firmware_patch_build = 0
 
-    ip = ".".join(str(b) for b in data[offset : offset + 4])
+    ip = IPv4Address(bytes(data[offset : offset + 4]))
     offset += 4
     mac = ":".join(f"{b:02x}" for b in data[offset : offset + 6])
     offset += 6
@@ -145,11 +146,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 = "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
@@ -157,39 +209,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[str, DiscoveryDevice] = {}
+    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(), (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.0.2 → pycomap-2.0.0}/src/pycomap/exceptions.py

@@ -22,6 +22,14 @@ class ComApAuthError(ComApError):
     """Raised when access-code verification fails or is rejected by the controller."""
 
 
+class ComApInvalidAccessCodeError(ComApAuthError):
+    """Raised when the controller rejects the access code during authentication."""
+
+
+class ComApInvalidPasswordError(ComApAuthError):
+    """Raised when the controller rejects the write-protection password."""
+
+
 class ComApControllerError(ComApError):
     """Raised when the controller answers with an explicit ``Error`` operation.
 

{pycomap-1.0.2 → pycomap-2.0.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)
 """
@@ -24,8 +26,9 @@ from types import TracebackType
 
 from pycomap.datatypes import decode_fdate, decode_ftime, encode_fdate, encode_ftime
 from pycomap.exceptions import (
-    ComApAuthError,
     ComApControllerError,
+    ComApInvalidAccessCodeError,
+    ComApInvalidPasswordError,
     ComApProtocolError,
 )
 from pycomap.protocol import crypto
@@ -65,9 +68,11 @@ class ComApClient:
 
     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")
     """
 
@@ -81,6 +86,11 @@ class ComApClient:
         self._mode = _Mode.NONE
         self._cipher: ChainedAesCbc | None = None
 
+    @property
+    def transport(self) -> Transport:
+        """The underlying byte-stream transport."""
+        return self._transport
+
     # -- connection lifecycle -------------------------------------------------
 
     async def connect(self) -> None:
@@ -114,7 +124,7 @@ class ComApClient:
             access_code: The controller's base AccessCode (drives ECDH/AES key derivation).
 
         Raises:
-            ComApAuthError: If the controller rejects the access code.
+            ComApInvalidAccessCodeError: If the controller rejects the access code.
             ComApProtocolError: If the ECDH exchange produces an unexpected response.
         """
         server_pub_data = await self.read_object(CommunicationObject.ECDH_PUBLIC_KEY)
@@ -136,13 +146,13 @@ class ComApClient:
             nonce = await self.read_object(CommunicationObject.VERIFY_ACCESS_HASH)
         except ComApControllerError as exc:
             if exc.code not in _AUTH_FALLBACK_CODES:
-                raise ComApAuthError("access verification failed") from exc
+                raise ComApInvalidAccessCodeError("access verification failed") from exc
             _log.warning("hash auth not supported by controller, falling back to plain access code")
             source = access_code.encode("ascii").ljust(16, b"\x00")
             try:
                 await self.write_object(CommunicationObject.VERIFY_ACCESS, source)
             except ComApControllerError as exc2:
-                raise ComApAuthError("access code rejected by controller") from exc2
+                raise ComApInvalidAccessCodeError("access code rejected by controller") from exc2
             _log.info("authenticated via plain access code")
         else:
             digest = hashlib.md5(nonce + access_code.encode("ascii")).digest()
@@ -150,7 +160,7 @@ class ComApClient:
             try:
                 await self.write_object(CommunicationObject.VERIFY_ACCESS_HASH, credentials)
             except ComApControllerError as exc3:
-                raise ComApAuthError("access code rejected by controller") from exc3
+                raise ComApInvalidAccessCodeError("access code rejected by controller") from exc3
             _log.info("authenticated via hash")
 
     async def elevate_access(self, password: int) -> None:
@@ -175,7 +185,7 @@ class ComApClient:
                 CommunicationObject.PASSWORD_FOR_WRITE, struct.pack("<H", password)
             )
         except ComApControllerError as exc:
-            raise ComApAuthError(
+            raise ComApInvalidPasswordError(
                 "password rejected by controller (wrong password or brute-force lockout active)"
             ) from exc
         _log.info("write-protection password accepted")

{pycomap-1.0.2 → pycomap-2.0.0}/src/pycomap/protocol/transport.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import logging
+from ipaddress import IPv4Address
 from typing import Protocol, runtime_checkable
 
 from pycomap.exceptions import ComApConnectionError
@@ -48,10 +49,12 @@ class EthernetTransport:
     ECDH/AES framing on top.
     """
 
-    def __init__(self, host: str, port: int = DEFAULT_PORT) -> None:
+    def __init__(self, host: IPv4Address, port: int = DEFAULT_PORT) -> None:
         """
         Args:
-            host: Controller IP address 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 = host
@@ -59,10 +62,15 @@ class EthernetTransport:
         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
+
     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)