pycomap 1.0.0__tar.gz

pycomap-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,45 @@
+# 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/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "pycomap"
+version = "1.0.0"
+description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Igor Panteleyev", email = "panteleev.igor69@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "cryptography>=42",
+    "pytz>=2026.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+    "pre-commit>=4.6.0",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=7.1.0",
+    "pytest-env>=1.6.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15",
+    "ty>=0.0.16",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "integration: requires real ComAp hardware reachable on the network (set PYCOMAP_TEST_HOST, see .env.example)",
+]
+
+[tool.pytest_env]
+env_files = [".env"]
+
+[tool.coverage.run]
+source = ["src/pycomap"]
+omit = ["tests/*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "C4",  # flake8-comprehensions
+    "RUF", # ruff-specific
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pycomap"]
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.uv]
+publish-url = "https://upload.pypi.org/legacy/"

pycomap-1.0.0/src/pycomap/__init__.py

@@ -0,0 +1,56 @@
+"""pycomap — async Python client for ComAp controllers (InteliLite/AMF25 and others).
+
+Quick start::
+
+    from pycomap import Command, Controller, EthernetTransport, discover
+
+    async with ComApClient(EthernetTransport("192.168.1.9")) as client:
+        await client.authenticate("0")
+        await client.elevate_access(password)
+        result = await client.execute_command(Command.FAULT_RESET)
+
+Public API surface:
+
+- [ComApClient][pycomap.protocol.ComApClient] — low-level protocol client
+- [Command][pycomap.protocol.Command] — named controller commands
+- [EthernetTransport][pycomap.protocol.EthernetTransport] /
+  [Transport][pycomap.protocol.transport.Transport]
+- [discover][pycomap.discovery.discover] — UDP controller discovery
+- [pycomap.configuration][] — `ConfigurationTable` parsing and value/setpoint decode
+- [pycomap.alarms][] — alarm list parsing
+- [pycomap.history][] — history record parsing
+- [pycomap.datatypes][] — wire types and BCD codec
+
+See ``docs/protocol.md`` in the project repository for the full reverse-engineering notes.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pycomap.controller import Controller
+from pycomap.discovery import discover
+from pycomap.exceptions import (
+    ComApAuthError,
+    ComApConnectionError,
+    ComApControllerError,
+    ComApError,
+    ComApProtocolError,
+)
+from pycomap.protocol import ComApClient, Command, ControllerCommand, EthernetTransport
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "ComApAuthError",
+    "ComApClient",
+    "ComApConnectionError",
+    "ComApControllerError",
+    "ComApError",
+    "ComApProtocolError",
+    "Command",
+    "Controller",
+    "ControllerCommand",
+    "EthernetTransport",
+    "discover",
+]

pycomap-1.0.0/src/pycomap/alarms.py

@@ -0,0 +1,100 @@
+"""Alarm list parsing for IL3 controllers.
+
+Source: ``AlarmListRecord.LoadIL3`` + ``LoadCommonPart`` in ``ComAp.Controller.dll``.
+See ``docs/protocol.md`` for the full binary format notes.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from pycomap.configuration import NamesCategory, parse_names_heap
+from pycomap.datatypes import get_bits
+
+# IL3 alarm list: 112 bytes = up to 16 x 7-byte records.
+# Record: uint32 dw + uint16 flags + uint8 source.
+# IsUsed: bit 31 of dw must be 1 AND not all fields 0xFF.
+# DiagnosticCodeType.ComAp = 7 (bits 0-2 of flags).
+
+_IL3_ALARM_RECORD_SIZE = 7
+_DIAGNOSTIC_CODE_TYPE_COMAP = 7
+_ALARM_RECORD_STRUCT = struct.Struct("<IHB")  # uint32 dw, uint16 flags, uint8 source
+
+
+@dataclass(slots=True, frozen=True)
+class AlarmRecord:
+    """One entry from the controller's alarm list (``CommunicationObject.ALARM_LIST``,
+    C.O. 24545).
+
+    Source: ``AlarmListRecord.LoadIL3`` + ``LoadCommonPart`` in ``ComAp.Controller.dll``.
+    The IL3 format is 112 bytes = up to 16 x 7-byte records; records stop at the first
+    unused slot (all fields at max value) or end of buffer.
+
+    ``reason`` is resolved from ``AlarmReasonNames`` and matches the value's display name
+    (e.g. ``"Generator Voltage L1-N"``). ``prefix`` comes from ``HistoryPrefixNames`` and
+    encodes the protection type (e.g. ``"Wrn"``, ``"Sd"``).
+
+    For non-ComAp diagnostic codes (ECU alarms from CAN bus), ``reason`` and ``prefix``
+    will be empty strings and ``fault_code`` carries the raw ECU fault code.
+    """
+
+    is_active: bool
+    is_confirmed: bool
+    reason: str
+    prefix: str
+    occurred: int
+    source: int
+    fault_code: int
+
+
+def parse_alarm_list(config_data: bytes, alarm_data: bytes) -> list[AlarmRecord]:
+    """Parse the controller's ``ALARM_LIST`` blob (C.O. 24545) into a list of
+    ``AlarmRecord`` objects, in list order (most recent first per controller behaviour).
+
+    Only active (``IsUsed``) slots are returned; the list will be empty if there are no
+    current alarms.  Pass the full raw ``ConfigurationTable`` blob as ``config_data`` —
+    it is used to resolve the ``AlarmReasonNames`` and ``HistoryPrefixNames`` heaps.
+    """
+    reason_names = parse_names_heap(config_data, NamesCategory.ALARM_REASON_NAMES)
+    prefix_names = parse_names_heap(config_data, NamesCategory.HISTORY_PREFIX_NAMES)
+
+    records: list[AlarmRecord] = []
+    for offset in range(0, len(alarm_data) - _IL3_ALARM_RECORD_SIZE + 1, _IL3_ALARM_RECORD_SIZE):
+        dw, flags, source = _ALARM_RECORD_STRUCT.unpack_from(alarm_data, offset)
+
+        is_used = bool(get_bits(dw, 31, 1)) and not (
+            dw == 0xFFFFFFFF and flags == 0xFFFF and source == 0xFF
+        )
+        if not is_used:
+            break
+
+        kind = get_bits(flags, 0, 3)
+        reason_index = get_bits(flags, 3, 11)
+        is_active = bool(get_bits(flags, 14, 1))
+        is_confirmed = bool(get_bits(flags, 15, 1))
+
+        fault_code = get_bits(dw, 0, 19)
+        prefix_index = get_bits(dw, 19, 5)
+        occurred = get_bits(dw, 24, 7)
+
+        if kind == _DIAGNOSTIC_CODE_TYPE_COMAP:
+            reason = reason_names[reason_index] if reason_index < len(reason_names) else ""
+            prefix = prefix_names[prefix_index] if prefix_index < len(prefix_names) else ""
+        else:
+            reason = ""
+            prefix = ""
+
+        records.append(
+            AlarmRecord(
+                is_active=is_active,
+                is_confirmed=is_confirmed,
+                reason=reason,
+                prefix=prefix,
+                occurred=occurred,
+                source=source,
+                fault_code=fault_code,
+            )
+        )
+
+    return records