pycomap 1.0.0__py3-none-any.whl

pycomap/datatypes.py

@@ -0,0 +1,202 @@
+"""ComAp wire data types, protection states, and raw value encode/decode.
+
+``DataType`` mirrors ``DataTypeIdentifier`` from ``ComAp.GlobalShared.dll``; the byte-length
+table and struct formats are from ``DataTypeDescription.DataTypeLength`` in
+``ComAp.Controller.dll``.  ``decode_raw_value``/``encode_raw_value`` are the round-trip
+codec for individual values/setpoints — their callers (``decode_values_all``,
+``decode_setpoints_all``, ``encode_raw_value``) live in [pycomap.configuration][].
+
+``ProtectionState`` mirrors ``enum ProtectionState`` from ``ComAp.Controller.dll``
+(``ComAp.Controller.DataTypes`` namespace).
+
+``decode_fdate`` / ``decode_ftime`` / ``encode_fdate`` / ``encode_ftime`` implement the
+3-byte BCD ``FDate``/``FTime`` types used by ``CommunicationObject.DATE`` (24553) and
+``CommunicationObject.TIME`` (24554). Source: ``ComAp.Controller.DataTypes.FDate`` /
+``FTime`` in ``ComAp.Controller.dll``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import enum
+import struct
+
+from pycomap.exceptions import ComApProtocolError
+
+
+class DataType(enum.IntEnum):
+    """ComAp ``DataTypeIdentifier`` enum."""
+
+    INTEGER8 = 2
+    INTEGER16 = 3
+    INTEGER32 = 4
+    UNSIGNED8 = 5
+    UNSIGNED16 = 6
+    UNSIGNED32 = 7
+    FLOAT = 8
+    DATE = 11
+    DOMAIN = 15
+    TIMER = 16
+    BINARY8 = 64
+    BINARY16 = 65
+    BINARY32 = 66
+    FTIME = 67
+    FDATE = 68
+    CHAR = 69
+    STRING_LIST = 70
+    SHORT_STRING = 71
+    LONG_STRING = 72
+    HUGE_STRING = 73
+    IP_ADDRESS = 74
+    TELEPHONE_NUMBER = 75
+    EMAIL = 76
+
+
+_DATA_TYPE_LENGTH: dict[DataType, int] = {
+    DataType.INTEGER8: 1,
+    DataType.UNSIGNED8: 1,
+    DataType.BINARY8: 1,
+    DataType.CHAR: 1,
+    DataType.STRING_LIST: 1,
+    DataType.INTEGER16: 2,
+    DataType.UNSIGNED16: 2,
+    DataType.BINARY16: 2,
+    DataType.FTIME: 3,
+    DataType.FDATE: 3,
+    DataType.INTEGER32: 4,
+    DataType.UNSIGNED32: 4,
+    DataType.FLOAT: 4,
+    DataType.BINARY32: 4,
+    DataType.TIMER: 8,
+    DataType.SHORT_STRING: 16,
+    DataType.IP_ADDRESS: 16,
+    DataType.LONG_STRING: 32,
+    DataType.TELEPHONE_NUMBER: 32,
+    DataType.HUGE_STRING: 64,
+    DataType.EMAIL: 64,
+}
+
+_NUMERIC_STRUCT_FORMAT: dict[DataType, str] = {
+    DataType.INTEGER8: "<b",
+    DataType.INTEGER16: "<h",
+    DataType.INTEGER32: "<i",
+    DataType.UNSIGNED8: "<B",
+    DataType.UNSIGNED16: "<H",
+    DataType.UNSIGNED32: "<I",
+    DataType.FLOAT: "<f",
+    DataType.BINARY8: "<B",
+    DataType.BINARY16: "<H",
+    DataType.BINARY32: "<I",
+}
+
+_BINARY_TYPES = (DataType.BINARY8, DataType.BINARY16, DataType.BINARY32)
+
+
+class ProtectionState(enum.IntFlag):
+    """ComAp ``ProtectionState`` enum (``ValueState.Level1``/``Level2``/``SensorFail``).
+
+    ``Delay``, ``Active``, and ``NotConfirmed`` are combinable: ``Active | NotConfirmed``
+    (value 6) means the alarm is active but not yet acknowledged by the operator.
+    Source: ``ComAp.Controller.DataTypes.ProtectionState`` in ``ComAp.Controller.dll``.
+    """
+
+    NOT_ACTIVE = 0
+    DELAY = 1
+    ACTIVE = 2
+    NOT_CONFIRMED = 4
+
+
+def decode_raw_value(
+    data_type: DataType, raw: bytes, decimal_places: int = 0
+) -> int | float | bytes:
+    """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/
+    timer/date types are returned as raw bytes.
+    """
+    fmt = _NUMERIC_STRUCT_FORMAT.get(data_type)
+    if fmt is None:
+        return raw
+    value = struct.unpack(fmt, raw)[0]
+    if decimal_places and data_type not in _BINARY_TYPES:
+        return value / (10**decimal_places)
+    return value
+
+
+def encode_raw_value(data_type: DataType, value: int | float, decimal_places: int = 0) -> bytes:
+    """Encode ``value`` into the raw bytes ``decode_raw_value`` would decode it back from.
+
+    Only numeric and binary(bitfield) types can be encoded -- there's no encoder for
+    string/domain/timer/date types (write raw bytes directly via ``client.write_object``
+    instead). The controller itself enforces the setpoint's min/max (returning
+    ``ControllerError.BAD_WRITE_VALUE`` on rejection), so this doesn't validate limits.
+    """
+    fmt = _NUMERIC_STRUCT_FORMAT.get(data_type)
+    if fmt is None:
+        raise ComApProtocolError(f"cannot encode DataType.{data_type.name} -- not numeric")
+    if data_type is not DataType.FLOAT and decimal_places and data_type not in _BINARY_TYPES:
+        value = round(value * (10**decimal_places))
+    return struct.pack(fmt, value if data_type is DataType.FLOAT else int(value))
+
+
+# -- FDate / FTime BCD codec --------------------------------------------------
+# Source: ComAp.Controller.DataTypes.FDate / FTime in ComAp.Controller.dll.
+# Both types are 3-byte, each byte standard nibble-BCD (high nibble = tens, low = units).
+
+
+def get_bits(value: int, start: int, width: int) -> int:
+    """Extract ``width`` bits from ``value`` starting at bit ``start`` (LSB=0)."""
+    return (value >> start) & ((1 << width) - 1)
+
+
+def _bcd_decode(b: int) -> int:
+    return 10 * ((b >> 4) & 0xF) + (b & 0xF)
+
+
+def _bcd_encode(v: int) -> int:
+    return ((v // 10) << 4) | (v % 10)
+
+
+def decode_fdate(raw: bytes) -> datetime.date | None:
+    """Decode a 3-byte FDate payload ``[BCD(day), BCD(month), BCD(year-2000)]``.
+
+    Returns ``None`` for invalid/unset values (all 0xFF, or day byte == 0).
+    """
+    if len(raw) != 3:
+        raise ComApProtocolError(f"FDate requires 3 bytes, got {len(raw)}")
+    if raw[0] == 0 or (raw[0] == 0xFF and raw[1] == 0xFF and raw[2] == 0xFF):
+        return None
+    day = _bcd_decode(raw[0])
+    month = _bcd_decode(raw[1])
+    year = _bcd_decode(raw[2]) + 2000
+    try:
+        return datetime.date(year, month, day)
+    except ValueError:
+        return None
+
+
+def encode_fdate(date: datetime.date) -> bytes:
+    """Encode a ``datetime.date`` as a 3-byte FDate payload."""
+    if date.year < 2000:
+        raise ComApProtocolError("FDate cannot represent years before 2000")
+    return bytes([_bcd_encode(date.day), _bcd_encode(date.month), _bcd_encode(date.year - 2000)])
+
+
+def decode_ftime(raw: bytes) -> datetime.time | None:
+    """Decode a 3-byte FTime payload ``[BCD(hour), BCD(minute), BCD(second)]``.
+
+    Returns ``None`` for invalid/unset values (hour byte ≥ 0x36 per source check).
+    """
+    if len(raw) != 3:
+        raise ComApProtocolError(f"FTime requires 3 bytes, got {len(raw)}")
+    if raw[0] >= 0x36:
+        return None
+    try:
+        return datetime.time(_bcd_decode(raw[0]), _bcd_decode(raw[1]), _bcd_decode(raw[2]))
+    except ValueError:
+        return None
+
+
+def encode_ftime(time: datetime.time) -> bytes:
+    """Encode a ``datetime.time`` as a 3-byte FTime payload."""
+    return bytes([_bcd_encode(time.hour), _bcd_encode(time.minute), _bcd_encode(time.second)])

pycomap/discovery.py

@@ -0,0 +1,195 @@
+"""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
+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``
+communication object, replied to with a ``SendTo`` carrying a binary ``DiscoveryDevice``
+payload (IP, MAC, TCP port, firmware version, and the list of units behind the gateway).
+
+The controller validates the CRC on this probe just like any other message, so a
+malformed/random payload of the right length is silently ignored — it must be built via
+[pycomap.protocol.framing.build_inner][], not improvised.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import enum
+import logging
+import socket
+import struct
+from dataclasses import dataclass, field
+
+from pycomap.exceptions import ComApProtocolError
+from pycomap.protocol.framing import Operation, build_inner, parse_inner
+from pycomap.protocol.objects import CommunicationObject
+
+DISCOVERY_PORT = 2413
+
+_log = logging.getLogger(__name__)
+
+_HEADER_SIZE_V0 = 42
+_HEADER_SIZE_V1 = 44
+_UNIT_RECORD_SIZE = 21
+
+
+class DeviceType(enum.IntEnum):
+    """ComAp ``DiscoveryDevice.DeviceType`` enum."""
+
+    IB_NT = 0
+    IB_COM = 1
+    IB_LITE = 2
+    CM_ETHERNET = 4
+    IG500_BUILT_IN_ETHERNET = 5
+
+
+class AccessType(enum.IntFlag):
+    """ComAp ``DiscoveryDevice.AccessType`` flags."""
+
+    IP_ADDRESS = 1
+    AIR_GATE = 2
+
+
+@dataclass(slots=True, frozen=True)
+class DiscoveryUnit:
+    """A controller unit reachable through the replying gateway device."""
+
+    type: int
+    name: str
+    serial: str
+
+
+@dataclass(slots=True, frozen=True)
+class DiscoveryDevice:
+    """A controller's decoded reply to a discovery probe."""
+
+    format_version: int
+    device_type: DeviceType
+    serial_number: int
+    firmware_major_minor: int
+    firmware_patch_build: int
+    ip: str
+    mac: str
+    comm_port: int
+    access_type: AccessType
+    airgate_identifier: str
+    connected_units: int
+    is_units_list_complete: bool
+    units: list[DiscoveryUnit] = field(default_factory=list)
+
+
+def _build_probe() -> bytes:
+    """Build the discovery probe: a ``SendMe`` ``EthernetMessage`` for ``Discovery``."""
+    return build_inner(
+        Operation.SEND_ME, addr=1, comm_obj=CommunicationObject.DISCOVERY, data=b"", ident=0
+    )
+
+
+def _parse_device(data: bytes) -> DiscoveryDevice:
+    """Parse a ``DiscoveryDevice`` payload (the ``Message.data`` of a ``Discovery`` reply)."""
+    format_version = data[0]
+    device_type = DeviceType(data[1])
+    serial_number = struct.unpack_from("<I", data, 2)[0]
+
+    header_size = _HEADER_SIZE_V0 if format_version == 0 else _HEADER_SIZE_V1
+    offset = 6
+    firmware_major_minor = struct.unpack_from("<H", data, offset)[0]
+    offset += 2
+    if format_version >= 1:
+        firmware_patch_build = struct.unpack_from("<H", data, offset)[0]
+        offset += 2
+    else:
+        firmware_patch_build = 0
+
+    ip = ".".join(str(b) for b in data[offset : offset + 4])
+    offset += 4
+    mac = ":".join(f"{b:02x}" for b in data[offset : offset + 6])
+    offset += 6
+    comm_port = struct.unpack_from("<H", data, offset)[0]
+    offset += 2
+    access_type = AccessType(data[offset])
+    offset += 1
+    airgate_identifier = data[offset : offset + 16].split(b"\x00", 1)[0].decode("ascii", "replace")
+    offset += 16
+    connected_units = struct.unpack_from("<I", data, offset)[0]
+    offset += 4
+    is_units_list_complete = bool(data[offset])
+    offset += 1
+
+    assert offset == header_size
+    units = [
+        DiscoveryUnit(
+            type=data[i],
+            name=data[i + 1 : i + 17].split(b"\x00", 1)[0].decode("ascii", "replace"),
+            serial=data[i + 17 : i + 21].hex(),
+        )
+        for i in range(header_size, len(data), _UNIT_RECORD_SIZE)
+    ]
+
+    return DiscoveryDevice(
+        format_version=format_version,
+        device_type=device_type,
+        serial_number=serial_number,
+        firmware_major_minor=firmware_major_minor,
+        firmware_patch_build=firmware_patch_build,
+        ip=ip,
+        mac=mac,
+        comm_port=comm_port,
+        access_type=access_type,
+        airgate_identifier=airgate_identifier,
+        connected_units=connected_units,
+        is_units_list_complete=is_units_list_complete,
+        units=units,
+    )
+
+
+async def discover(
+    timeout: float = 2.0,
+    broadcast_address: str = "255.255.255.255",
+) -> list[DiscoveryDevice]:
+    """Broadcast a discovery probe and collect replies for ``timeout`` seconds.
+
+    Returns one [DiscoveryDevice][pycomap.discovery.DiscoveryDevice] per distinct
+    replying IP address. Malformed or unrelated UDP traffic on the same port
+    (CRC mismatch, wrong communication object) is
+    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] = {}
+    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
+    finally:
+        sock.close()
+
+    _log.info("discovery found %d device(s)", len(found))
+    return list(found.values())

pycomap/exceptions.py

@@ -0,0 +1,35 @@
+"""Exception hierarchy for pycomap."""
+
+from __future__ import annotations
+
+
+class ComApError(Exception):
+    """Base class for all pycomap errors."""
+
+
+class ComApConnectionError(ComApError):
+    """Raised on TCP-level connection problems (refused, closed, timed out)."""
+
+
+class ComApProtocolError(ComApError):
+    """Raised when the wire protocol itself misbehaves (bad CRC, unexpected framing,
+    unsupported cipher, unexpected message type, etc.) — never on a clean controller-side
+    error response, see [ComApControllerError][pycomap.ComApControllerError] for that.
+    """
+
+
+class ComApAuthError(ComApError):
+    """Raised when access-code verification fails or is rejected by the controller."""
+
+
+class ComApControllerError(ComApError):
+    """Raised when the controller answers with an explicit ``Error`` operation.
+
+    Attributes:
+        code: the raw ``uint32`` error code reported by the controller. See
+            ``docs/protocol.md`` section 2.6 for known values.
+    """
+
+    def __init__(self, code: int, message: str | None = None) -> None:
+        self.code = code
+        super().__init__(message or f"controller error: {code} (0x{code:08x})")

pycomap/history.py

@@ -0,0 +1,166 @@
+"""History record parsing for IL3 controllers.
+
+Source: ``ClientDrivenHistorySerializer.LoadHeaderIL3`` + ``LoadHeaderIL3CommonPart``
++ ``HistoryTimeStamp.LoadDefinedByHistRecord`` in ``ComAp.Controller.dll``.
+See ``docs/protocol.md`` for the full binary format notes.
+
+IL3 record wire layout (ConfigFormatTerminal < 7, confirmed on live controller):
+
+  Bytes 0-1  uint16 LE  bits 0-11 = reason_index, bits 13-14 = reason_category
+  Byte  2               bits 0-4  = prefix_index, bits 5-7  = level
+  Bytes 3-11  9-byte timestamp (DefinedByHistRecord format):
+      [0]=BCD(day)  [1]=BCD(month)  [2]=BCD(year-2000)
+      [3]=BCD(hour) [4]=BCD(minute) [5]=BCD(second)
+      [6] bit7=type(0=RTC,1=EngHours)  bits0-3=tenths-of-second
+      [7-8] uint16 LE = sequential record index
+  Bytes 12+  payload: null-terminated ASCII for text records, raw value
+             snapshots for alarm/event records
+
+prefix_index sentinel values: 30 = text record, 31 = invalid record.
+reason_category: 0=HistoryReasonNames, 1=CommonNames, 2=DiagNames, 3=AlarmReasonNames
+"""
+
+from __future__ import annotations
+
+import datetime
+import struct
+from dataclasses import dataclass
+
+from pycomap.configuration import NamesCategory, parse_names_heap
+from pycomap.datatypes import _bcd_decode, get_bits
+
+_HIST_PREFIX_TEXT = 30
+_HIST_PREFIX_INVALID = 31
+
+_HIST_CAT_REASON_NAMES: dict[int, NamesCategory] = {
+    0: NamesCategory.HISTORY_REASON_NAMES,
+    1: NamesCategory.COMMON_NAMES,
+    3: NamesCategory.ALARM_REASON_NAMES,
+    # 2 = EcuDiagnosticCodes (DiagNames) — not implemented; returned as empty string
+}
+
+
+@dataclass(slots=True, frozen=True)
+class HistoryRecord:
+    """One entry from the controller's history ring buffer (``YOUNGEST_HISTORY_RECORD``
+    / ``OLDER_HISTORY_RECORD``, C.O. 24569/24567).
+
+    For alarm events: ``reason`` is the value name that triggered the event (e.g.
+    ``"Generator Voltage L1-N"``), ``prefix`` is the protection type (``"Wrn"``,
+    ``"Sd"``, etc.), ``level`` encodes severity (1-3) or transition type (4=Start,
+    5=Stop).
+
+    For configuration-change events (``is_text=True``): ``text`` holds the human-readable
+    description (e.g. ``"T=ETH CA1 A CON(24554)=21:25:08"``); ``reason`` and ``prefix``
+    are usually empty.
+
+    ``timestamp`` is the controller's local time at the event (see ``read_datetime`` note
+    about Summer Time Mode). ``engine_hours`` is set instead when the controller uses
+    run-hours as the time reference (rare; RTC is the norm for IL3).
+    """
+
+    index: int
+    timestamp: datetime.datetime | None
+    engine_hours: datetime.timedelta | None
+    tenth_seconds: int
+    reason: str
+    prefix: str
+    level: int
+    is_text: bool
+    text: str
+    data: bytes
+
+
+def _parse_history_timestamp(
+    ts: bytes,
+) -> tuple[datetime.datetime | None, datetime.timedelta | None, int]:
+    """Decode the 9-byte DefinedByHistRecord timestamp.
+
+    Returns ``(datetime, engine_hours, tenth_seconds)``. Exactly one of the first two
+    will be non-None.
+    """
+    is_engine_hours = bool(ts[6] & 0x80)
+    tenth_seconds = _bcd_decode(ts[6] & 0x0F)
+
+    if is_engine_hours:
+        dw = struct.unpack_from("<I", ts, 0)[0]
+        hours = (dw >> 0) & 0xFFFFFF
+        minutes = (dw >> 24) & 0xFF
+        return None, datetime.timedelta(hours=hours, minutes=minutes), tenth_seconds
+
+    try:
+        dt = datetime.datetime(
+            year=_bcd_decode(ts[2]) + 2000,
+            month=_bcd_decode(ts[1]),
+            day=_bcd_decode(ts[0]),
+            hour=_bcd_decode(ts[3]),
+            minute=_bcd_decode(ts[4]),
+            second=_bcd_decode(ts[5]),
+        )
+    except ValueError:
+        dt = None
+    return dt, None, tenth_seconds
+
+
+def parse_history_record(config_data: bytes, record_data: bytes) -> HistoryRecord | None:
+    """Parse one history record blob returned by ``YOUNGEST_HISTORY_RECORD`` /
+    ``OLDER_HISTORY_RECORD`` (C.O. 24569/24567).
+
+    Returns ``None`` for invalid records (prefix_index=31 or unparseable timestamp).
+    Pass the full raw ``ConfigurationTable`` blob as ``config_data`` — it is used to
+    resolve reason and prefix names from the unified names heap.
+    """
+    if len(record_data) < 12:
+        return None
+
+    word, flags_byte = struct.unpack_from("<HB", record_data, 0)
+    reason_index = get_bits(word, 0, 12)
+    reason_category = get_bits(word, 13, 2)
+    prefix_index = get_bits(flags_byte, 0, 5)
+    level = get_bits(flags_byte, 5, 3)
+
+    if prefix_index == _HIST_PREFIX_INVALID:
+        return None
+
+    is_text = prefix_index == _HIST_PREFIX_TEXT
+    ts_bytes = record_data[3:12]
+    payload = record_data[12:]
+
+    dt, engine_hours, tenth_seconds = _parse_history_timestamp(ts_bytes)
+    index = struct.unpack_from("<H", ts_bytes, 7)[0]
+
+    if dt is None and engine_hours is None:
+        return None
+
+    # Resolve reason name
+    names_cat = _HIST_CAT_REASON_NAMES.get(reason_category)
+    reason = ""
+    if names_cat is not None:
+        names = parse_names_heap(config_data, names_cat)
+        reason = names[reason_index] if reason_index < len(names) else ""
+
+    # Resolve prefix name. Index 0 = '-' (info/status, no protection class).
+    prefix = ""
+    if not is_text:
+        prefix_names = parse_names_heap(config_data, NamesCategory.HISTORY_PREFIX_NAMES)
+        prefix = prefix_names[prefix_index] if prefix_index < len(prefix_names) else ""
+
+    # Decode text payload (null-terminated ASCII)
+    text = ""
+    if is_text:
+        null = payload.find(0)
+        raw_text = payload[:null] if null >= 0 else payload
+        text = raw_text.decode("ascii", errors="replace")
+
+    return HistoryRecord(
+        index=index,
+        timestamp=dt,
+        engine_hours=engine_hours,
+        tenth_seconds=tenth_seconds,
+        reason=reason,
+        prefix=prefix,
+        level=level,
+        is_text=is_text,
+        text=text,
+        data=payload if not is_text else b"",
+    )

pycomap/protocol/__init__.py

@@ -0,0 +1,24 @@
+"""ComAp's native ECDH/AES-encrypted control protocol (TCP port 23).
+
+See ``docs/protocol.md`` section 2 for the reverse-engineering notes this package implements.
+"""
+
+from __future__ import annotations
+
+from pycomap.protocol.client import ComApClient
+from pycomap.protocol.commands import Command, ControllerCommand
+from pycomap.protocol.framing import Message, Operation
+from pycomap.protocol.objects import CommunicationObject, ControllerError
+from pycomap.protocol.transport import EthernetTransport, Transport
+
+__all__ = [
+    "ComApClient",
+    "Command",
+    "CommunicationObject",
+    "ControllerCommand",
+    "ControllerError",
+    "EthernetTransport",
+    "Message",
+    "Operation",
+    "Transport",
+]