pycomap 1.0.2__tar.gz → 1.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycomap
-Version: 1.0.2
+Version: 1.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>

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

@@ -1,6 +1,6 @@
 [project]
 name = "pycomap"
-version = "1.0.2"
+version = "1.1.0"
 description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
 readme = "README.md"
 license = "MIT"

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

@@ -29,12 +29,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 +50,13 @@ __all__ = [
     "ComApConnectionError",
     "ComApControllerError",
     "ComApError",
+    "ComApInvalidAccessCodeError",
+    "ComApInvalidPasswordError",
     "ComApProtocolError",
     "Command",
     "Controller",
     "ControllerCommand",
     "EthernetTransport",
+    "Value",
     "discover",
 ]

{pycomap-1.0.2 → pycomap-1.1.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-1.1.0}/src/pycomap/controller.py

@@ -27,13 +27,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 +49,8 @@ from pycomap.datatypes import (
     _BINARY_TYPES,
     _DATA_TYPE_LENGTH,
     DataType,
+    RawValue,
+    Value,
     decode_raw_value,
     encode_raw_value,
 )
@@ -109,7 +113,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 +135,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,6 +146,9 @@ 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::
@@ -167,20 +173,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 +246,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 +270,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 +298,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 +408,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 +418,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 +433,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 +446,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 +459,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 +503,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 +527,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 +544,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 +611,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 +662,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 +693,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 +810,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 +820,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-1.1.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-1.1.0}/src/pycomap/discovery.py

@@ -21,6 +21,7 @@ import logging
 import socket
 import struct
 from dataclasses import dataclass, field
+from ipaddress import IPv4Address
 
 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
@@ -147,7 +148,7 @@ def _parse_device(data: bytes) -> DiscoveryDevice:
 
 async def discover(
     timeout: float = 2.0,
-    broadcast_address: str = "255.255.255.255",
+    broadcast_address: str | IPv4Address = "255.255.255.255",
 ) -> list[DiscoveryDevice]:
     """Broadcast a discovery probe and collect replies for ``timeout`` seconds.
 
@@ -161,11 +162,11 @@ async def discover(
     sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
     sock.setblocking(False)
 
-    found: dict[str, DiscoveryDevice] = {}
+    found: dict[IPv4Address, DiscoveryDevice] = {}
     try:
         sock.bind(("", 0))
         _log.debug("sending discovery probe to %s:%d", broadcast_address, DISCOVERY_PORT)
-        sock.sendto(_build_probe(), (broadcast_address, DISCOVERY_PORT))
+        sock.sendto(_build_probe(), (str(broadcast_address), DISCOVERY_PORT))
 
         end_time = loop.time() + timeout
         while True:

{pycomap-1.0.2 → pycomap-1.1.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-1.1.0}/src/pycomap/protocol/client.py

@@ -24,8 +24,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
@@ -114,7 +115,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 +137,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 +151,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 +176,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-1.1.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,13 +49,13 @@ class EthernetTransport:
     ECDH/AES framing on top.
     """
 
-    def __init__(self, host: str, port: int = DEFAULT_PORT) -> None:
+    def __init__(self, host: IPv4Address | str, port: int = DEFAULT_PORT) -> None:
         """
         Args:
-            host: Controller IP address or hostname.
+            host: Controller IP address (``IPv4Address`` or dotted string) or hostname.
             port: TCP port; defaults to ``23`` (ComAp native protocol port).
         """
-        self._host = host
+        self._host = str(host)
         self._port = port
         self._reader: asyncio.StreamReader | None = None
         self._writer: asyncio.StreamWriter | None = None