pycomap 1.0.0__py3-none-any.whl

pycomap/protocol/objects.py

@@ -0,0 +1,98 @@
+"""Known ``CommunicationObject`` IDs and ``ControllerError`` codes.
+
+Source: decompiled ``ComAp.Controller.dll`` (class ``CommunicationObject`` — a plain class
+with one ``static readonly`` field per object, not a C# ``enum``) and decompiled
+``ComAp.GlobalShared.dll`` (``enum ControllerError : uint``). See ``docs/protocol.md``
+sections 2.5/2.6 for the full table and how to extend it.
+
+This is a partial list — only what's been confirmed useful so far. Re-decompile the DLLs
+with ``ilspycmd`` to extend it.
+
+Controller commands (``ControllerCommand``, ``Command``) live in
+[pycomap.protocol.commands][].
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class CommunicationObject(enum.IntEnum):
+    """Known communication object IDs."""
+
+    VERSION_IB = 24533
+    DISCOVERY = 24237
+    ECDH_PUBLIC_KEY = 24119
+    VERIFY_ACCESS_HASH = 24324
+    VERIFY_ACCESS = 24534
+    MAX_MESSAGE_DATA_LENGTHS = 24269
+    COMAP_PROTOCOL_FEATURES = 24023
+
+    VALUES_ALL = 24560
+    VALUE_STATES_ALL = 24555
+    VALUE_STATES_AND_DATA_ALL = 24529
+    VALUES_CATEGORY_I = 24563
+    VALUES_CATEGORY_II = 24562
+    VALUES_CATEGORY_III = 24561
+    VALUE_STATES_CATEGORY_I = 24558
+    VALUE_STATES_CATEGORY_II = 24557
+    VALUE_STATES_CATEGORY_III = 24556
+
+    SETPOINTS_ALL = 24559
+    SETPOINTS_R = 24543
+    SETPOINTS_P = 24544
+
+    ALARM_LIST = 24545
+    ALARM_LIST_WITH_VERSION = 24024
+
+    CONFIGURATION_TABLE = 24575
+    TERMINAL_CONFIGURATION_TABLE = 24574
+    CONFIGURATION_TABLE_CRC16 = 24573
+    TERMINAL_CONFIGURATION_TABLE_CRC16 = 24572
+
+    SERIAL_NUMBER = 24548
+    FIRMWARE_VERSION_TEXT = 24339
+    BOOTLOADER_FIRMWARE_VERSION = 24277
+    CONTROLLER_FIRMWARE_IDENTIFICATION = 24115
+
+    COMMAND = 24551
+    COMMAND_WITH_ARGUMENT = 23859
+    COMMAND_ARGUMENT = 24550
+
+    CONTROLLER_STATE = 24496
+
+    HISTORY_LENGTH = 24538
+    MAX_HISTORY_RECORDS = 24564
+    READ_INDEX_IN_HISTORY = 24565
+    WRITE_INDEX_IN_HISTORY = 24566
+    OLDER_HISTORY_RECORD = 24567
+    YOUNGER_HISTORY_RECORD = 24568
+    YOUNGEST_HISTORY_RECORD = 24569
+    NEW_HISTORY_RECORDS = 24570
+
+    COMMUNICATION_STATE = 24571
+    CONTROLLER_ADDRESS = 24537
+    DISPLAY_CONTRAST = 24547
+    GSM_PIN = 24536
+    PASSWORD_FOR_WRITE = 24524
+    PASSWORD_FOR_WRITE_HASH = 24286
+    PASSWORD_DECODE = 24202
+    TIME_UNTIL_PASSWORD_ENTERING_UNBLOCKS = 24109
+    CHANGE_ACCESS = 24535
+    SYSTEM_TIME = 24552
+    DATE = 24553  # setpoint FDATE, access_level=1 (requires elevate_access to write)
+    TIME = 24554  # setpoint FTIME, access_level=1 (requires elevate_access to write)
+    TIME_ZONE = 24366  # setpoint STRING_LIST, access_level=0
+    INTELI_MAINS = 24528
+
+
+class ControllerError(enum.IntEnum):
+    """Known ``ControllerError`` values (``uint32`` on the wire)."""
+
+    OK = 0
+    NO_ANSWER = 1
+    ANSWER_POSTPONED = 2
+    NON_EXISTING_COMMUNICATION_OBJECT = 100_794_368
+    TERMINAL_ACCESS_DISABLED = 134_217_960
+    BAD_WRITE_VALUE = 134_217_955
+    INVALID_PASSWORD = 134_217_978

pycomap/protocol/transport.py

@@ -0,0 +1,89 @@
+"""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``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import Protocol, runtime_checkable
+
+from pycomap.exceptions import ComApConnectionError
+
+DEFAULT_PORT = 23
+
+_log = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Byte-stream transport used by ``ComApClient``."""
+
+    async def connect(self) -> None:
+        """Open the underlying connection."""
+        ...
+
+    async def close(self) -> None:
+        """Close the underlying connection, suppressing already-closed errors."""
+        ...
+
+    async def read_exactly(self, n: int) -> bytes:
+        """Read exactly ``n`` bytes, raising ``ComApConnectionError`` if the stream ends."""
+        ...
+
+    async def write(self, data: bytes) -> None:
+        """Write ``data`` and flush."""
+        ...
+
+
+class EthernetTransport:
+    """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: str, port: int = DEFAULT_PORT) -> None:
+        """
+        Args:
+            host: Controller IP address or hostname.
+            port: TCP port; defaults to ``23`` (ComAp native protocol port).
+        """
+        self._host = host
+        self._port = port
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+
+    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)
+        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)
+
+    async def close(self) -> None:
+        if self._writer is not None:
+            self._writer.close()
+            with contextlib.suppress(OSError):
+                await self._writer.wait_closed()
+            _log.info("disconnected from %s:%d", self._host, self._port)
+        self._reader = None
+        self._writer = None
+
+    async def read_exactly(self, n: int) -> bytes:
+        assert self._reader is not None
+        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
+        self._writer.write(data)
+        await self._writer.drain()

pycomap-1.0.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pycomap
+Version: 1.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>
+License-Expression: MIT
+Requires-Dist: cryptography>=42
+Requires-Dist: pytz>=2026.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# pycomap
+
+Async Python client for ComAp controllers (InteliLite AMF25 and likely compatible
+siblings): LAN discovery and the native ECDH/AES-encrypted control protocol on port 23.
+
+Reverse-engineered from `ComAp.Controller.dll` and cross-validated against live hardware.
+
+Requires Python 3.13+. Dependencies: `cryptography`, `pytz`.
+
+## Quick start
+
+```python
+from pycomap import Controller, EthernetTransport
+from pycomap.protocol import ComApClient
+
+async with Controller(
+    ComApClient(EthernetTransport("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:
+    values = await ctrl.read_values()
+    print(values)
+
+    await ctrl.set_setpoint("Nominal RPM", 1500)
+    await ctrl.set_setpoint("Summer Time Mode", "Winter")  # STRING_LIST by label
+```
+
+See the [API docs](docs/) for full reference. `just docs-serve` to browse locally.
+
+## Development
+
+```sh
+just format       # ruff check --fix + ruff format
+just typecheck    # ty check
+just unit         # tests/unit (no hardware needed)
+just integration  # tests/integration (requires .env with PYCOMAP_TEST_HOST)
+just docs-serve   # browse API docs locally
+just ai-docs      # regenerate llms.txt and CLAUDE.md
+```
+
+`pre-commit` runs format + typecheck on every commit:
+
+```sh
+uv run pre-commit install
+```

pycomap-1.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+pycomap/__init__.py,sha256=eXgucOTO_NZvdfAeBUgOIaCY43K6Pqc0V8hxQbEpTA4,1766
+pycomap/alarms.py,sha256=2Yzn8DTfWTtUjuYd3Svfq8h6zyNSZ50haTpQPSS9RH4,3720
+pycomap/configuration.py,sha256=fmdXAw0Xs0jhRxSKGb9ZTt85zUoHyODK1_yVduUxa8k,22009
+pycomap/controller.py,sha256=HCpbxx0aQ01BE21kJna4pDHSfKyc7rA3sEEVacuQn4Y,32734
+pycomap/datatypes.py,sha256=dNLol4tnOxDohraDsm3z9A27PMj_VQrO0e2e6Mm6G1w,6811
+pycomap/discovery.py,sha256=i0PzsQm-wXh7fP_XOumi_L-o8pog5GT0i_QWrskg1yA,6313
+pycomap/exceptions.py,sha256=Zn8Rq4B94L6yFZjaXkgAewNp-NQ5xPXD82uRIBeklIM,1171
+pycomap/history.py,sha256=2AKctZRdRz7B2oPVqHG63UpbpvptW1Azzf_4HTUWNhQ,5904
+pycomap/protocol/__init__.py,sha256=FJOnzdjrrQff7s6CxOiIRtAH7B3CmXnvvT6L4ysqlNQ,714
+pycomap/protocol/client.py,sha256=hE4t9z8PDWH_zX4v0zMs4hCsWZrYniwimVOnOqmo_no,14919
+pycomap/protocol/commands.py,sha256=F_DhytdsFLqmA0y-WcanC-5LRcJBaYVVj-EggGZLe3U,2572
+pycomap/protocol/crc.py,sha256=5J4gQ7PCSc247KxK4RwYm4EZOIKn2p2L-BGLxlq5xAA,584
+pycomap/protocol/crypto.py,sha256=v2ywWRzezqTUXsGvaIdLr-CRsc1Sf010zV5IupxfV5E,3947
+pycomap/protocol/framing.py,sha256=Hsws2G8af9ect2OFksBqc8PbQcrJvPJD_77fiwKg-BU,4541
+pycomap/protocol/objects.py,sha256=wtf8x5FdqyplFRAljg1HCpLfzF-nsWGDIQi4Ew7U72k,2961
+pycomap/protocol/transport.py,sha256=jI5cxeAXP9gdzAsD-Jv-25AciJNKgbd5y5FnjbGXuno,2987
+pycomap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycomap-1.0.0.dist-info/WHEEL,sha256=s49dN1sxqzkgPplo4QuUaKomil-_cbDzeLK4-pZKD-A,81
+pycomap-1.0.0.dist-info/METADATA,sha256=XlA1Sz4jBXFfAsuggtBgFHuEOrD90HCl1rF1tQipfJI,1790
+pycomap-1.0.0.dist-info/RECORD,,

pycomap-1.0.0.dist-info/WHEEL

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