pycomap 1.0.0__py3-none-any.whl

pycomap/protocol/client.py

@@ -0,0 +1,357 @@
+"""Async client for ComAp's native ``EthernetMessage`` protocol (TCP port 23).
+
+See ``docs/protocol.md`` section 2 for the full reverse-engineering notes this implements,
+and the docstrings on [pycomap.protocol.crypto][] / [pycomap.protocol.framing][] for
+the trickiest details (read/write key-format asymmetry, the single shared IV chain).
+
+Typical usage::
+
+    from pycomap.protocol.transport import EthernetTransport
+
+    async with ComApClient(EthernetTransport("192.168.1.9")) as client:
+        await client.authenticate("0")
+        values = await client.read_object(CommunicationObject.VALUES_ALL)
+"""
+
+from __future__ import annotations
+
+import datetime
+import enum
+import hashlib
+import logging
+import struct
+from types import TracebackType
+
+from pycomap.datatypes import decode_fdate, decode_ftime, encode_fdate, encode_ftime
+from pycomap.exceptions import (
+    ComApAuthError,
+    ComApControllerError,
+    ComApProtocolError,
+)
+from pycomap.protocol import crypto
+from pycomap.protocol.commands import ControllerCommand
+from pycomap.protocol.crypto import ChainedAesCbc
+from pycomap.protocol.framing import (
+    BLOCK_SIZE,
+    Message,
+    Operation,
+    build_inner,
+    pad_to_block,
+    parse_inner,
+    wrap_outer,
+)
+from pycomap.protocol.objects import CommunicationObject, ControllerError
+from pycomap.protocol.transport import Transport
+
+
+class _Mode(enum.Enum):
+    """Wire mode the connection has progressed through: NONE -> ALIGNED -> AES."""
+
+    NONE = enum.auto()
+    ALIGNED = enum.auto()
+    AES = enum.auto()
+
+
+_AUTH_FALLBACK_CODES = {
+    ControllerError.TERMINAL_ACCESS_DISABLED,
+    ControllerError.NON_EXISTING_COMMUNICATION_OBJECT,
+}
+
+_log = logging.getLogger(__name__)
+
+
+class ComApClient:
+    """Speaks the ECDH/AES-encrypted ``EthernetMessage`` protocol over any ``Transport``.
+
+    Pass any ``Transport`` implementation — typically ``EthernetTransport``::
+
+        from pycomap.protocol.transport import EthernetTransport
+
+        async with ComApClient(EthernetTransport("192.168.1.9")) as client:
+            await client.authenticate("0")
+    """
+
+    def __init__(self, transport: Transport) -> None:
+        """
+        Args:
+            transport: Byte-stream transport to use (typically ``EthernetTransport``).
+        """
+        self._transport = transport
+        self._identifier = 0
+        self._mode = _Mode.NONE
+        self._cipher: ChainedAesCbc | None = None
+
+    # -- connection lifecycle -------------------------------------------------
+
+    async def connect(self) -> None:
+        """Open the transport and consume the controller's unsolicited ``VersionIB``."""
+        await self._transport.connect()
+
+        message = await self._read_message()
+        if message.comm_obj != CommunicationObject.VERSION_IB:
+            raise ComApProtocolError(
+                f"expected VersionIB as the first message, got comm_obj={message.comm_obj}"
+            )
+        version_word = struct.unpack_from("<H", message.data, 0)[0]
+        if not version_word & 0x8000:
+            raise ComApProtocolError(
+                "controller requires the legacy Blowfish cipher, which is not supported"
+            )
+        _log.debug("VersionIB received (version_word=0x%04X)", version_word)
+        self._mode = _Mode.ALIGNED
+
+    async def authenticate(self, access_code: str) -> None:
+        """Perform the ECDH handshake and verify ``access_code`` with the controller.
+
+        The AES session key is derived once from ``access_code`` and cannot be changed
+        without reconnecting. Pass the base/anonymous code (often ``"0"``), not a
+        privileged write code. To unlock write-protected setpoints afterward, call
+        [elevate_access][pycomap.protocol.ComApClient.elevate_access] —
+        re-calling this method with a different code would
+        corrupt the cipher state.
+
+        Args:
+            access_code: The controller's base AccessCode (drives ECDH/AES key derivation).
+
+        Raises:
+            ComApAuthError: 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)
+        server_pub_point = server_pub_data[4:]
+
+        private_key = crypto.generate_keypair()
+        our_pub_point = crypto.public_point_bytes(private_key)
+        await self.write_object(
+            CommunicationObject.ECDH_PUBLIC_KEY,
+            bytes([len(our_pub_point)]) + our_pub_point,
+        )
+
+        secret = crypto.shared_secret(private_key, server_pub_point)
+        aes_key, iv = crypto.derive_key_and_iv(secret, access_code)
+        self._cipher = ChainedAesCbc(aes_key, iv)
+        self._mode = _Mode.AES
+
+        try:
+            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
+            _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
+            _log.info("authenticated via plain access code")
+        else:
+            digest = hashlib.md5(nonce + access_code.encode("ascii")).digest()
+            credentials = "".join(f"{b:02X}" for b in digest).encode("ascii")
+            try:
+                await self.write_object(CommunicationObject.VERIFY_ACCESS_HASH, credentials)
+            except ComApControllerError as exc3:
+                raise ComApAuthError("access code rejected by controller") from exc3
+            _log.info("authenticated via hash")
+
+    async def elevate_access(self, password: int) -> None:
+        """Submit the controller's write-protection password to unlock password-protected
+        setpoints for this session.
+
+        This is a completely separate credential from the ``access_code`` passed to
+        [authenticate][pycomap.protocol.ComApClient.authenticate] —
+        the *AccessCode* gates the TCP connection itself, while the
+        *Password* (0-9999) gates individual setpoint writes based on each setpoint's
+        configured ``accessLevel``. Verified live against a real controller: write
+        ``CommunicationObject.PASSWORD_FOR_WRITE`` (24524) with the 2-byte little-endian
+        password value, then setpoint writes that would otherwise return
+        ``ControllerError.INVALID_PASSWORD`` succeed.
+
+        The controller enforces brute-force protection (5 wrong attempts → 1 min block,
+        doubling each time, 100 wrong → permanent lockout). Do not call this in a retry
+        loop. See ``docs/protocol.md`` section 2.4.1 for the full picture.
+        """
+        try:
+            await self.write_object(
+                CommunicationObject.PASSWORD_FOR_WRITE, struct.pack("<H", password)
+            )
+        except ComApControllerError as exc:
+            raise ComApAuthError(
+                "password rejected by controller (wrong password or brute-force lockout active)"
+            ) from exc
+        _log.info("write-protection password accepted")
+
+    async def close(self) -> None:
+        await self._transport.close()
+        self._mode = _Mode.NONE
+        self._cipher = None
+
+    async def __aenter__(self) -> ComApClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    # -- communication objects -------------------------------------------------
+
+    async def read_object(self, comm_obj: int, addr: int = 1) -> bytes:
+        """Read a communication object, handling ``SendToBlock`` continuation transparently.
+
+        Args:
+            comm_obj: Communication object number (C.O.).
+            addr: Controller unit address; ``1`` for the primary unit.
+
+        Returns:
+            Raw payload bytes.
+
+        Raises:
+            ComApControllerError: If the controller responds with an error code.
+            ComApProtocolError: If an unexpected message operation is received.
+        """
+        ident = self._next_identifier()
+        await self._write_message(Operation.SEND_ME, addr, comm_obj, b"", ident)
+
+        data = bytearray()
+        while True:
+            message = await self._read_message()
+            if message.is_error:
+                raise ComApControllerError(message.error_code)
+            if message.op is Operation.SEND_TO:
+                data.extend(message.data)
+                return bytes(data)
+            if message.op is Operation.SEND_TO_BLOCK:
+                data.extend(message.data)
+                if message.is_last_block:
+                    return bytes(data)
+                next_ident = self._next_identifier()
+                await self._write_message(Operation.NEXT, addr, comm_obj, b"", next_ident)
+                continue
+            raise ComApProtocolError(
+                f"unexpected operation {message.op!r} while reading {comm_obj}"
+            )
+
+    async def write_object(self, comm_obj: int, data: bytes, addr: int = 1) -> bytes:
+        """Write a communication object.
+
+        Args:
+            comm_obj: Communication object number (C.O.).
+            data: Raw payload bytes to write.
+            addr: Controller unit address; ``1`` for the primary unit.
+
+        Returns:
+            Any data carried back on the ``NEXT`` acknowledgment (usually empty).
+
+        Raises:
+            ComApControllerError: If the controller responds with an error code.
+        """
+        ident = self._next_identifier()
+        await self._write_message(Operation.SEND_TO, addr, comm_obj, data, ident)
+        message = await self._read_message()
+        if message.is_error:
+            raise ComApControllerError(message.error_code)
+        if message.op is not Operation.NEXT:
+            raise ComApProtocolError(
+                f"unexpected operation {message.op!r} while writing {comm_obj}"
+            )
+        return message.data
+
+    async def execute_command(self, command: ControllerCommand) -> int:
+        """Execute a controller command and return the ``uint32`` result code.
+
+        Writes the argument to ``COMMAND_ARGUMENT`` (24550), triggers via ``COMMAND``
+        (24551), then reads ``COMMAND_ARGUMENT`` back for the return value. Compare the
+        result against ``command.expected_return`` (or use ``command.succeeded(result)``)
+        to determine success. A result of ``ControllerCommand.RESULT_REFUSED`` (``0x02``)
+        means the controller state doesn't allow the action right now (e.g. engine start
+        attempted outside MAN mode); ``RESULT_INVALID_ARGUMENT`` (``0x01``) means the
+        command/argument combination is unrecognised.
+
+        Note: some commands require the session to be password-elevated first via
+        [elevate_access][pycomap.protocol.ComApClient.elevate_access] — the controller will raise
+        ``ControllerError.INVALID_PASSWORD`` on the write if so.
+        """
+        await self.write_object(
+            CommunicationObject.COMMAND_ARGUMENT, struct.pack("<I", command.argument)
+        )
+        await self.write_object(CommunicationObject.COMMAND, struct.pack("<H", command.code))
+        result_raw = await self.read_object(CommunicationObject.COMMAND_ARGUMENT)
+        return struct.unpack("<I", result_raw)[0]
+
+    async def read_datetime(self) -> datetime.datetime | None:
+        """Read the controller's current date and time as a **naive** datetime.
+
+        Reads ``DATE`` (C.O. 24553) and ``TIME`` (C.O. 24554) in two round-trips.
+        Returns ``None`` if the controller reports an invalid/unset clock (e.g. after a
+        factory reset before time sync).
+
+        The value is the controller's local wall-clock time (no timezone info attached).
+        DST is governed by the ``Summer Time Mode`` setpoint (8727) and the UTC offset
+        by the ``Time Zone`` setpoint (24366).
+        """
+        date_raw = await self.read_object(CommunicationObject.DATE)
+        time_raw = await self.read_object(CommunicationObject.TIME)
+        date = decode_fdate(date_raw)
+        time = decode_ftime(time_raw)
+        if date is None or time is None:
+            return None
+        return datetime.datetime.combine(date, time)
+
+    async def write_datetime(self, dt: datetime.datetime) -> None:
+        """Set the controller's clock to the wall-clock components of ``dt``.
+
+        Writes ``DATE`` (C.O. 24553) then ``TIME`` (C.O. 24554). Seconds are included;
+        sub-second precision is dropped. Year must be ≥ 2000.
+
+        Both setpoints have ``access_level=1`` — call
+        [elevate_access][pycomap.protocol.ComApClient.elevate_access] first.
+        Pass the correct **local time** directly.
+        """
+        await self.write_object(CommunicationObject.DATE, encode_fdate(dt.date()))
+        await self.write_object(CommunicationObject.TIME, encode_ftime(dt.time()))
+
+    # -- low-level framing ---------------------------------------------------
+
+    def _next_identifier(self) -> int:
+        ident = self._identifier
+        self._identifier = (self._identifier + 1) & 0xFF
+        return ident
+
+    async def _read_message(self) -> Message:
+        inner = await self._read_inner()
+        return parse_inner(inner)
+
+    async def _write_message(
+        self, op: Operation, addr: int, comm_obj: int, data: bytes, ident: int
+    ) -> None:
+        inner = build_inner(op, addr, comm_obj, data, ident)
+        await self._write_inner(inner)
+
+    async def _read_inner(self) -> bytes:
+        if self._mode is _Mode.NONE:
+            header = await self._transport.read_exactly(8)
+            data_len = struct.unpack_from("<H", header, 0)[0]
+            rest = await self._transport.read_exactly(data_len)
+            return header + rest
+
+        count_byte = await self._transport.read_exactly(1)
+        block_payload = await self._transport.read_exactly(count_byte[0] * BLOCK_SIZE)
+
+        if self._mode is _Mode.ALIGNED:
+            return block_payload
+        assert self._cipher is not None
+        return self._cipher.decrypt(block_payload)
+
+    async def _write_inner(self, inner: bytes) -> None:
+        padded = pad_to_block(inner)
+        if self._mode is _Mode.NONE:
+            await self._transport.write(inner)
+        elif self._mode is _Mode.ALIGNED:
+            await self._transport.write(wrap_outer(padded))
+        else:
+            assert self._cipher is not None
+            await self._transport.write(wrap_outer(self._cipher.encrypt(padded)))

pycomap/protocol/commands.py

@@ -0,0 +1,62 @@
+"""Controller command definitions.
+
+``ControllerCommand`` bundles a command's wire-level code, argument, and expected
+success return value. ``Command`` is a namespace of pre-built named instances for all
+known IL3 commands. Pass them to ``ComApClient.execute_command``.
+
+Source: InteliLite Global Guide §6.1 "List of commands and arguments" and decompiled
+``ComAp.Controller.dll`` ``CommandNumber`` class.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ControllerCommand:
+    """A controller command bundling its code, argument, and the return value that
+    indicates success.
+
+    To execute: ``await client.execute_command(command)``.
+    To check the result: compare the returned ``uint32`` against ``expected_return``
+    or use ``command.succeeded(result)``.
+    """
+
+    code: int
+    argument: int
+    expected_return: int
+
+    # Application-level failure codes returned inside COMMAND_ARGUMENT on error.
+    RESULT_INVALID_ARGUMENT: int = 0x00000001
+    RESULT_REFUSED: int = 0x00000002
+
+    def succeeded(self, result: int) -> bool:
+        """True if ``result`` (the uint32 read back from ``COMMAND_ARGUMENT``) matches
+        the expected success return value for this command.
+
+        Note: a successful return value means the *protocol* acknowledged the command —
+        not that the mechanical action was carried out. The controller's own mode logic
+        gates execution (e.g. ENGINE_START returns the success code even outside MAN mode,
+        but the engine does not start). Always verify the physical outcome separately.
+        """
+        return result == self.expected_return
+
+
+class Command:
+    """Named controller commands. Pass to ``ComApClient.execute_command``.
+
+    Some commands require the controller to be in a specific mode (e.g. MAN for engine
+    start/stop); the controller returns ``RESULT_REFUSED`` (0x02) otherwise.
+    """
+
+    ENGINE_START = ControllerCommand(0x01, 0x01FE0000, 0x000001FF)
+    ENGINE_STOP = ControllerCommand(0x01, 0x02FD0000, 0x000002FE)
+    FAULT_RESET = ControllerCommand(0x01, 0x08F70000, 0x000008F8)
+    HORN_RESET = ControllerCommand(0x01, 0x04FB0000, 0x000004FC)
+    GCB_TOGGLE = ControllerCommand(0x02, 0x11EE0000, 0x000011EF)
+    GCB_ON = ControllerCommand(0x02, 0x11EF0000, 0x000011F0)
+    GCB_OFF = ControllerCommand(0x02, 0x11F00000, 0x000011F1)
+    MCB_TOGGLE = ControllerCommand(0x02, 0x12ED0000, 0x000012EE)
+    MCB_ON = ControllerCommand(0x02, 0x12EE0000, 0x000012EF)
+    MCB_OFF = ControllerCommand(0x02, 0x12EF0000, 0x000012F0)

pycomap/protocol/crc.py

@@ -0,0 +1,20 @@
+"""CRC16 used to checksum every ComAp ``EthernetMessage``.
+
+Standard MODBUS/ANSI CRC16: init ``0xFFFF``, polynomial ``0xA001`` (reflected ``0x8005``),
+no final XOR. Verified byte-for-byte against live ComAp traffic — see
+``docs/protocol.md`` section 2.2.
+"""
+
+from __future__ import annotations
+
+_POLY = 0xA001
+
+
+def crc16(data: bytes) -> int:
+    """Compute the CRC16 used by the ComAp wire protocol over ``data``."""
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ _POLY if crc & 1 else crc >> 1
+    return crc

pycomap/protocol/crypto.py

@@ -0,0 +1,90 @@
+"""ECDH handshake and the chained-IV AES-256-CBC cipher used after it.
+
+See ``docs/protocol.md`` section 2.4 (steps 4-9) for the full derivation. The key points
+that are easy to get wrong (and were, during reverse-engineering):
+
+- The EC key exchange uses curve secp256r1 (P-256), raw uncompressed point encoding
+  (``0x04 || X[32] || Y[32]``).
+- The *read* and *write* wire formats for the public key are different: reading the
+  controller's key requires skipping a 4-byte prefix; writing ours requires prefixing a
+  single length byte. See [pycomap.protocol.client][].
+- The AES key/IV are derived via double HMAC-SHA256 keyed by the access code (not the shared
+  secret) — see [derive_key_and_iv][].
+- There is exactly **one** IV for the whole connection, shared between encryption and
+  decryption, advanced after *every* AES operation (either direction) to that operation's
+  ciphertext's last 16 bytes. [ChainedAesCbc][] models this with a single internal IV.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac as _hmac
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers import Cipher as _CryptoCipher
+from cryptography.hazmat.primitives.ciphers import algorithms, modes
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+CURVE = ec.SECP256R1()
+EC_POINT_LENGTH = 65  # 1 (0x04 prefix) + 32 (X) + 32 (Y)
+AES_KEY_LENGTH = 32
+AES_IV_LENGTH = 16
+
+
+def generate_keypair() -> ec.EllipticCurvePrivateKey:
+    """Generate a fresh ephemeral keypair on secp256r1."""
+    return ec.generate_private_key(CURVE, default_backend())
+
+
+def public_point_bytes(private_key: ec.EllipticCurvePrivateKey) -> bytes:
+    """Raw uncompressed point encoding of ``private_key``'s public key (65 bytes)."""
+    return private_key.public_key().public_bytes(
+        encoding=Encoding.X962,
+        format=PublicFormat.UncompressedPoint,
+    )
+
+
+def shared_secret(private_key: ec.EllipticCurvePrivateKey, peer_point: bytes) -> bytes:
+    """Compute the ECDH shared secret (32 bytes) from our private key and the peer's
+    raw uncompressed public point.
+    """
+    peer_key = ec.EllipticCurvePublicKey.from_encoded_point(CURVE, peer_point)
+    secret = private_key.exchange(ec.ECDH(), peer_key)
+    return secret.rjust(AES_KEY_LENGTH, b"\x00")
+
+
+def derive_key_and_iv(shared_secret_bytes: bytes, access_code: str) -> tuple[bytes, bytes]:
+    """Derive the AES-256 key and initial IV from the ECDH shared secret and access code."""
+    access_bytes = access_code.encode("utf-8")
+    aes_key = _hmac.new(access_bytes, shared_secret_bytes, hashlib.sha256).digest()
+    iv = _hmac.new(access_bytes, aes_key, hashlib.sha256).digest()[:AES_IV_LENGTH]
+    return aes_key, iv
+
+
+class ChainedAesCbc:
+    """AES-256-CBC with a single IV shared between encrypt and decrypt, chained on
+    ciphertext across the whole connection (see module docstring).
+    """
+
+    def __init__(self, key: bytes, iv: bytes) -> None:
+        self._key = key
+        self._iv = iv
+
+    def encrypt(self, block_payload: bytes) -> bytes:
+        """Encrypt an already 16-byte-aligned plaintext payload, advancing the shared IV."""
+        encryptor = _CryptoCipher(
+            algorithms.AES(self._key), modes.CBC(self._iv), backend=default_backend()
+        ).encryptor()
+        ciphertext = encryptor.update(block_payload) + encryptor.finalize()
+        self._iv = ciphertext[-16:]
+        return ciphertext
+
+    def decrypt(self, block_payload: bytes) -> bytes:
+        """Decrypt an already 16-byte-aligned ciphertext payload, advancing the shared IV."""
+        decryptor = _CryptoCipher(
+            algorithms.AES(self._key), modes.CBC(self._iv), backend=default_backend()
+        ).decryptor()
+        plaintext = decryptor.update(block_payload) + decryptor.finalize()
+        self._iv = block_payload[-16:]
+        return plaintext

pycomap/protocol/framing.py

@@ -0,0 +1,145 @@
+"""ComAp ``EthernetMessage`` wire framing.
+
+See ``docs/protocol.md`` section 2.1 for the full format. Two nested layers:
+
+Outer "block alignment" wrapper (present on every message except the very first one on a
+connection, see [pycomap.protocol.client][])::
+
+    [1 byte: block_count][block_count * 16 bytes: payload, zero-padded to the boundary]
+
+Inner ``EthernetMessage``::
+
+    offset  size  field
+    0       2     data_length (uint16 LE)
+    2       1     bits[0:3]=Operation, bits[3:8]=ControllerAddress-1
+    3       1     Identifier
+    4       2     CommunicationObject id (uint16 LE)
+    6       dlen  data (or, for SendToBlock: 1 block-info byte + (dlen-1) bytes of data)
+    6+dlen  2     CRC16 LE over bytes [0 .. 6+dlen)
+
+This module only deals with bytes — it knows nothing about sockets or encryption. The outer
+wrapper's payload may be plaintext (before AES is established) or AES-CBC ciphertext (after);
+either way this module just packs/unpacks the block-count-prefixed, 16-byte-aligned blob.
+"""
+
+from __future__ import annotations
+
+import enum
+import struct
+from dataclasses import dataclass
+
+from pycomap.exceptions import ComApProtocolError
+from pycomap.protocol.crc import crc16
+
+BLOCK_SIZE = 16
+
+
+class Operation(enum.IntEnum):
+    """ComAp ``Message.Operation`` enum (3 bits on the wire)."""
+
+    SEND_ME = 0
+    SEND_TO = 1
+    SEND_TO_BLOCK = 2
+    NEXT = 3  # aka "Acknowledgment"
+    ERROR = 4
+    REPEAT = 5
+
+
+@dataclass(slots=True)
+class Message:
+    """A parsed (or about-to-be-built) inner ``EthernetMessage``."""
+
+    op: Operation
+    addr: int
+    ident: int
+    comm_obj: int
+    data: bytes
+    block_index: int | None = None
+    is_last_block: bool | None = None
+
+    @property
+    def is_error(self) -> bool:
+        return self.op is Operation.ERROR
+
+    @property
+    def error_code(self) -> int:
+        """Decode the ``uint32`` LE error code carried in an ``ERROR`` message's data."""
+        if not self.is_error:
+            raise ValueError("not an ERROR message")
+        return struct.unpack_from("<I", self.data, 0)[0]
+
+
+def parse_inner(buf: bytes) -> Message:
+    """Parse one inner ``EthernetMessage`` from ``buf`` (CRC-validated)."""
+    if len(buf) < 8:
+        raise ComApProtocolError(f"message too short: {len(buf)} bytes")
+    data_len = struct.unpack_from("<H", buf, 0)[0]
+    total = data_len + 8
+    if total > len(buf):
+        raise ComApProtocolError(f"truncated message: need {total} bytes, have {len(buf)}")
+    buf = buf[:total]
+
+    b2 = buf[2]
+    op = Operation(b2 & 0x07)
+    addr = (b2 >> 3) + 1
+    ident = buf[3]
+    comm_obj = struct.unpack_from("<H", buf, 4)[0]
+
+    block_index: int | None = None
+    is_last_block: bool | None = None
+    if op is Operation.SEND_TO_BLOCK:
+        block_byte = buf[6]
+        block_index = block_byte & 0x7F
+        is_last_block = bool(block_byte & 0x80)
+        data = buf[7 : 6 + data_len]
+    else:
+        data = buf[6 : 6 + data_len]
+
+    crc_expected = struct.unpack_from("<H", buf, len(buf) - 2)[0]
+    crc_actual = crc16(buf[:-2])
+    if crc_expected != crc_actual:
+        raise ComApProtocolError(
+            f"CRC mismatch: expected {crc_expected:#06x}, got {crc_actual:#06x} ({buf.hex()})"
+        )
+
+    return Message(
+        op=op,
+        addr=addr,
+        ident=ident,
+        comm_obj=comm_obj,
+        data=bytes(data),
+        block_index=block_index,
+        is_last_block=is_last_block,
+    )
+
+
+def build_inner(
+    op: Operation,
+    addr: int,
+    comm_obj: int,
+    data: bytes,
+    ident: int,
+) -> bytes:
+    """Build one inner ``EthernetMessage`` (header + data + CRC), CRC-validated by construction."""
+    b2 = (op & 0x07) | ((addr - 1) << 3)
+    header = struct.pack("<H", len(data)) + bytes([b2, ident]) + struct.pack("<H", comm_obj)
+    msg = header + data
+    return msg + struct.pack("<H", crc16(msg))
+
+
+def pad_to_block(payload: bytes) -> bytes:
+    """Zero-pad ``payload`` up to the next 16-byte boundary."""
+    remainder = len(payload) % BLOCK_SIZE
+    if remainder == 0:
+        return payload
+    return payload + b"\x00" * (BLOCK_SIZE - remainder)
+
+
+def wrap_outer(block_payload: bytes) -> bytes:
+    """Prefix an already block-aligned payload with its 1-byte block count."""
+    if len(block_payload) % BLOCK_SIZE != 0:
+        raise ComApProtocolError("outer payload is not block-aligned")
+    count = len(block_payload) // BLOCK_SIZE
+    if count > 255:
+        raise ComApProtocolError("message too long for a single block-count byte")
+    return bytes([count]) + block_payload