cta2045 0.1.0__py3-none-any.whl

cta2045/__init__.py

@@ -0,0 +1,20 @@
+"""cta2045 — a CTA-2045 protocol library.
+
+CTA-2045 (ANSI/CTA-2045-B) is the modular communications interface between a
+Smart Grid Device (SGD — e.g. a water heater) and a Universal Communications
+Module (UCM). This library encodes and decodes CTA-2045 messages.
+
+Package layout:
+
+- ``cta2045.enums``  — on-the-wire enumerations (the canonical vocabulary).
+- ``cta2045.app``    — application-layer messages (Basic DR, Intermediate DR,
+  commodity/energy, GetInformation).
+- ``cta2045.codec``  — ASCII-hex ↔ bytes and message framing.
+- ``cta2045.link``   — reserved for a future CTA-2045 RS485 link layer.
+- ``cta2045.ucm``    — abstract UCM interface; vendor-proprietary bindings live
+  in separate (non-open) packages.
+
+Status: scaffold. The implementation is tracked in the project's issue tracker.
+"""
+
+__version__ = "0.1.0"

cta2045/app/__init__.py

@@ -0,0 +1,654 @@
+"""CTA-2045 application layer — message encode/decode.
+
+Structured Python objects ↔ CTA-2045 message bytes:
+
+- **Basic DR** (CTA-2045-B § 10) — shed, end-shed, load-up, critical-peak,
+  grid-emergency, power-level, operational-state.
+- **Intermediate DR** (CTA-2045.3 § 11) — commodity/energy reads
+  (:class:`CommodityReadReply`), device information
+  (:class:`GetInformationReply`), thermostat responses.
+
+Decoding starts at :func:`decode` / :func:`decode_all` (bytes) or
+:func:`decode_hex` (ASCII-hex). Encoding helpers (:func:`shed`, :func:`end`,
+:func:`critical_peak`, :func:`grid_emergency`, :func:`load_up`,
+:func:`power_level`) return :class:`BasicDR` objects; call ``.to_bytes()`` for
+the wire frame.
+
+Everything here is pure bytes ⇄ objects: no transport, no I/O.
+"""
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from functools import reduce
+from operator import or_
+from struct import calcsize, pack, unpack_from
+from typing import Union
+
+from cta2045.codec import CodecError, Duration, Frame, build_frame, hex_to_bytes, parse_frame
+from cta2045.enums import (
+    AdvancedLoadUpUnits,
+    BasicDRCategory,
+    Capability,
+    CommodityCode,
+    DeviceType,
+    IntermediateDRCategory,
+    IntermediateDRResponseCode,
+    MessageType,
+    OperationalState,
+)
+
+__all__ = [
+    # message types
+    "BasicDR",
+    "IntermediateDR",
+    "CommodityReport",
+    "CommodityReadReply",
+    "GetInformationReply",
+    "ThermostatResponse",
+    "AdvancedLoadUp",
+    "UnknownMessage",
+    "Message",
+    # decoding
+    "decode",
+    "decode_all",
+    "decode_hex",
+    "decode_frame",
+    # encoding
+    "shed",
+    "end",
+    "critical_peak",
+    "grid_emergency",
+    "load_up",
+    "power_level",
+    "advanced_load_up",
+    "get_advanced_load_up",
+]
+
+# Message type identifiers (CTA-2045-B § 6.1.1).
+_BASIC_DR = (0x08, 0x01)
+_INTERMEDIATE_DR = (0x08, 0x02)
+
+# Basic DR categories whose opcode2 carries an event-duration byte (§ 10.1.2).
+_DURATION_CATEGORIES = frozenset(
+    {
+        BasicDRCategory.Shed,
+        BasicDRCategory.Critical_Peak_Event,
+        BasicDRCategory.Grid_Emergency,
+        BasicDRCategory.Load_Up,
+    }
+)
+
+
+def _enum_or_none(enum_cls: type[Enum], value: int) -> Enum | None:
+    """Return the enum member for ``value``, or ``None`` if not a defined value."""
+    try:
+        return enum_cls(value)
+    except ValueError:
+        return None
+
+
+def _enum_or_raw(enum_cls: type[Enum], value: int) -> Enum | int:
+    """Return the enum member for ``value``, or the raw ``int`` if undefined.
+
+    Lenient decoding: an unrecognized on-the-wire value (vendor extension or a
+    newer spec revision) is preserved as its raw integer rather than raising.
+    """
+    member = _enum_or_none(enum_cls, value)
+    return value if member is None else member
+
+
+def _enum_value(value: Enum | int) -> int:
+    """The on-the-wire int for an enum member or a raw int (for encoding)."""
+    return value.value if isinstance(value, Enum) else value
+
+
+# --------------------------------------------------------------------------- #
+# Basic DR — CTA-2045-B § 10
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class BasicDR:
+    """A Basic DR application message (CTA-2045-B § 10, Table 10-1).
+
+    Two payload bytes: ``category`` (opcode1) and ``opcode2``. ``opcode2`` is
+    overloaded by category — an event-duration byte for the event commands, an
+    :class:`~cta2045.enums.OperationalState` for a state-query response, a
+    power-level percentage for a power-level request, etc.
+
+    Decoding an unrecognized opcode1 yields ``category=None`` with the raw byte
+    preserved in :attr:`opcode1` (lenient decoding).
+    """
+
+    category: BasicDRCategory | None
+    opcode2: int = 0x00
+    opcode1: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.opcode1 is None and self.category is not None:
+            self.opcode1 = self.category.value
+
+    @classmethod
+    def from_payload(cls, payload: bytes) -> "BasicDR":
+        if len(payload) < 2:
+            raise CodecError(f"Basic DR payload too short: {len(payload)} bytes")
+        opcode1 = payload[0]
+        return cls(_enum_or_none(BasicDRCategory, opcode1), payload[1], opcode1)
+
+    def to_payload(self) -> bytes:
+        if self.opcode1 is None:
+            raise CodecError("BasicDR has no opcode1 to encode")
+        return bytes([self.opcode1, self.opcode2])
+
+    def to_bytes(self) -> bytes:
+        return build_frame(*_BASIC_DR, self.to_payload())
+
+    @property
+    def operational_state(self) -> OperationalState | int | None:
+        """The operational state, for a State_Query_Response (else ``None``).
+
+        An unrecognized state value is returned as a raw ``int``.
+        """
+        if self.category is BasicDRCategory.State_Query_Response:
+            return _enum_or_raw(OperationalState, self.opcode2)
+        return None
+
+    @property
+    def duration(self) -> Duration | None:
+        """The event duration, for event commands (else ``None``)."""
+        if self.category in _DURATION_CATEGORIES:
+            return Duration.from_byte(self.opcode2)
+        return None
+
+
+# --------------------------------------------------------------------------- #
+# Intermediate DR — CTA-2045.3 § 11
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class CommodityReport:
+    """One commodity record from a Get CommodityRead reply (§ 11.3.1.2).
+
+    ``instantaneous`` and ``cumulative`` are 48-bit unsigned values, each
+    carried as three big-endian 16-bit words.
+    """
+
+    code: CommodityCode | int
+    instantaneous: int
+    cumulative: int
+
+    _FMT = ">BHHHHHH"
+    SIZE = calcsize(_FMT)  # 13 bytes
+
+    @classmethod
+    def from_bytes(cls, data: bytes, offset: int = 0) -> tuple["CommodityReport", int]:
+        code, m3a, m2a, m1a, m3b, m2b, m1b = unpack_from(cls._FMT, data, offset)
+        instantaneous = (m3a << 32) | (m2a << 16) | m1a
+        cumulative = (m3b << 32) | (m2b << 16) | m1b
+        return cls(_enum_or_raw(CommodityCode, code), instantaneous, cumulative), offset + cls.SIZE
+
+
+@dataclass
+class CommodityReadReply:
+    """Get CommodityRead reply (CTA-2045.3 § 11.3.1.2).
+
+    Body layout: ``opcode2`` (``0x80`` = reply), ``response_code``, then a
+    sequence of 13-byte :class:`CommodityReport` records.
+    """
+
+    opcode2: int
+    response_code: IntermediateDRResponseCode | int | None = None
+    reports: list[CommodityReport] = field(default_factory=list)
+
+    @classmethod
+    def from_body(cls, body: bytes) -> "CommodityReadReply":
+        if len(body) < 2:
+            raise CodecError("Consumption/Production body too short")
+        opcode2, rc = body[0], body[1]
+        reports: list[CommodityReport] = []
+        response_code = None
+        if opcode2 == 0x80:  # Get_CommodityRead_Reply
+            response_code = _enum_or_raw(IntermediateDRResponseCode, rc)
+            offset = 2
+            while offset + CommodityReport.SIZE <= len(body):
+                report, offset = CommodityReport.from_bytes(body, offset)
+                reports.append(report)
+        return cls(opcode2, response_code, reports)
+
+
+@dataclass
+class ThermostatResponse:
+    """Thermostat command response (CTA-2045.3 § 3.2.1)."""
+
+    opcode2: int
+    response_code: IntermediateDRResponseCode | int | None = None
+    type: str | None = None
+
+    @classmethod
+    def from_body(cls, body: bytes) -> "ThermostatResponse":
+        if len(body) < 2:
+            raise CodecError("Thermostat body too short")
+        opcode2, rc = body[0], body[1]
+        type_ = "Set_Hold_Response" if opcode2 == 0x83 else None
+        return cls(opcode2, _enum_or_raw(IntermediateDRResponseCode, rc), type_)
+
+
+@dataclass
+class AdvancedLoadUp:
+    """Advanced Load Up message (CTA-2045-B § 11.6, Intermediate DR 0x0C).
+
+    Models all four variants, distinguished by ``opcode2`` (``0x00`` request,
+    ``0x80`` reply) and which fields are present:
+
+    - **Get request** — ``opcode2=0x00``, no further fields.
+    - **Set request** — ``opcode2=0x00`` + ``duration_minutes`` + ``value`` +
+      ``units`` (+ optional trailing fields).
+    - **Set reply**   — ``opcode2=0x80`` + ``response_code`` only.
+    - **Get reply**   — ``opcode2=0x80`` + ``response_code`` + the measurement
+      block (+ optional trailing fields).
+
+    ``duration_minutes`` is a plain 2-byte minute count (§ 11.6) — *not* the
+    Basic-DR ``2·n²``-seconds duration byte. ``value`` is counted in ``units``
+    (see :class:`~cta2045.enums.AdvancedLoadUpUnits`); energy ≈
+    ``value × units.watt_hours``.
+    """
+
+    opcode2: int = 0x00
+    response_code: IntermediateDRResponseCode | int | None = None
+    duration_minutes: int | None = None
+    value: int | None = None
+    units: AdvancedLoadUpUnits | int | None = None
+    # Optional trailing fields (§ 11.6.2 / 11.6.3).
+    efficiency: int | None = None
+    event_id: int | None = None
+    start_time: int | None = None
+    start_randomization: int | None = None
+    end_randomization: int | None = None
+
+    @classmethod
+    def from_body(cls, body: bytes) -> "AdvancedLoadUp":
+        if not body:
+            raise CodecError("empty Advanced Load Up body")
+        obj = cls(opcode2=body[0])
+        pos = 1
+
+        def take(fmt: str) -> int | None:
+            nonlocal pos
+            size = calcsize(">" + fmt)
+            if pos + size > len(body):
+                return None
+            (value,) = unpack_from(">" + fmt, body, pos)
+            pos += size
+            return value
+
+        # Reply carries a response code before the measurement block.
+        if obj.opcode2 == 0x80:
+            if (v := take("B")) is None:
+                return obj
+            obj.response_code = _enum_or_raw(IntermediateDRResponseCode, v)
+
+        # Measurement block (a Set request always has it; a Get reply has it
+        # only while an event is active).
+        if (v := take("H")) is None:
+            return obj
+        obj.duration_minutes = v
+        if (v := take("H")) is None:
+            return obj
+        obj.value = v
+        if (v := take("B")) is None:
+            return obj
+        obj.units = _enum_or_raw(AdvancedLoadUpUnits, v)
+
+        # Optional trailing block.
+        if (v := take("B")) is None:
+            return obj
+        obj.efficiency = v
+        if (v := take("L")) is None:
+            return obj
+        obj.event_id = v
+        if (v := take("L")) is None:
+            return obj
+        obj.start_time = v
+        if (v := take("B")) is None:
+            return obj
+        obj.start_randomization = v
+        if (v := take("B")) is None:
+            return obj
+        obj.end_randomization = v
+        return obj
+
+    def to_payload(self) -> bytes:
+        out = bytearray([IntermediateDRCategory.Advanced_Load_Up.value, self.opcode2])
+        if self.opcode2 == 0x80 and self.response_code is not None:
+            out.append(_enum_value(self.response_code))
+        if self.duration_minutes is not None:
+            out += pack(">H", self.duration_minutes)
+            out += pack(">H", self.value if self.value is not None else 0)
+            if self.units is None:
+                raise CodecError("Advanced Load Up with a duration requires units")
+            out.append(_enum_value(self.units))
+            # Optional trailing fields, in order; stop at the first absent one.
+            for fmt, attr in (
+                (">B", "efficiency"),
+                (">L", "event_id"),
+                (">L", "start_time"),
+                (">B", "start_randomization"),
+                (">B", "end_randomization"),
+            ):
+                field_value = getattr(self, attr)
+                if field_value is None:
+                    break
+                out += pack(fmt, field_value)
+        return bytes(out)
+
+    def to_bytes(self) -> bytes:
+        return build_frame(*_INTERMEDIATE_DR, self.to_payload())
+
+
+# Field decoders for the GetInformation reply (CTA-2045-B § 11.1.1.2).
+_CAP_MASK = reduce(or_, (c.value for c in Capability))
+
+
+def _ascii(s: bytes) -> str:
+    # Fixed-width string fields are NUL- or space-padded; truncate at the first
+    # NUL, then strip surrounding whitespace.
+    return s.split(b"\x00", 1)[0].decode("ascii", errors="replace").strip()
+
+
+def _version(s: bytes) -> str:
+    v = _ascii(s)
+    return v[0] if v else ""
+
+
+def _serial(s: bytes) -> str:
+    v = _ascii(s)
+    return "Unknown" if re.fullmatch("0+", v) else v
+
+
+def _capabilities(raw: int) -> Capability:
+    # Mask to defined bits; reserved/future bits are ignored.
+    return Capability(raw & _CAP_MASK)
+
+
+@dataclass
+class GetInformationReply:
+    """GetInformation reply (CTA-2045-B § 11.1.1.2).
+
+    Mandatory fields are always present; the trailing model/serial/firmware
+    fields are optional and only set if the message carries them (``None``
+    otherwise).
+    """
+
+    opcode2: int | None = None
+    response_code: IntermediateDRResponseCode | int | None = None
+    cta2045_version: str | None = None
+    vendor_id: int | None = None
+    device_type: DeviceType | int | None = None
+    device_revision: int | None = None
+    capabilities: Capability | None = None
+    reserved: int | None = None
+    model: str | None = None
+    serial: str | None = None
+    fw_year: int | None = None
+    fw_month: int | None = None
+    fw_day: int | None = None
+    fw_major: int | None = None
+    fw_minor: int | None = None
+
+    @classmethod
+    def from_body(cls, body: bytes) -> "GetInformationReply":
+        """Decode the reply, field by field.
+
+        The trailing model/serial/firmware fields are optional with no length
+        marker, so each read is guarded: as soon as the body runs out, the
+        remaining fields stay ``None``.
+        """
+        obj = cls()
+        pos = 0
+
+        def take(fmt: str) -> int | bytes | None:
+            nonlocal pos
+            size = calcsize(">" + fmt)
+            if pos + size > len(body):
+                return None
+            (value,) = unpack_from(">" + fmt, body, pos)
+            pos += size
+            return value
+
+        # Mandatory block.
+        if (v := take("B")) is None:
+            return obj
+        obj.opcode2 = v
+        if (v := take("B")) is None:
+            return obj
+        obj.response_code = _enum_or_raw(IntermediateDRResponseCode, v)
+        if (v := take("2s")) is None:
+            return obj
+        obj.cta2045_version = _version(v)
+        if (v := take("H")) is None:
+            return obj
+        obj.vendor_id = v
+        if (v := take("H")) is None:
+            return obj
+        obj.device_type = _enum_or_raw(DeviceType, v)
+        if (v := take("H")) is None:
+            return obj
+        obj.device_revision = v
+        if (v := take("L")) is None:
+            return obj
+        obj.capabilities = _capabilities(v)
+        if (v := take("B")) is None:
+            return obj
+        obj.reserved = v
+
+        # Optional trailing block.
+        if (v := take("15s")) is None:
+            return obj
+        obj.model = _ascii(v)
+        if (v := take("15s")) is None:
+            return obj
+        obj.serial = _serial(v)
+        if (v := take("B")) is None:
+            return obj
+        obj.fw_year = v
+        if (v := take("B")) is None:
+            return obj
+        obj.fw_month = v
+        if (v := take("B")) is None:
+            return obj
+        obj.fw_day = v
+        if (v := take("B")) is None:
+            return obj
+        obj.fw_major = v
+        if (v := take("B")) is None:
+            return obj
+        obj.fw_minor = v
+        return obj
+
+
+@dataclass
+class IntermediateDR:
+    """An Intermediate DR application message (CTA-2045.3 § 11).
+
+    ``category`` (opcode1) selects the body type. Recognized categories decode
+    to a structured ``body`` (:class:`CommodityReadReply`,
+    :class:`GetInformationReply`, :class:`ThermostatResponse`); an unrecognized
+    opcode1 yields ``category=None`` and the raw body bytes (lenient decoding).
+    """
+
+    category: IntermediateDRCategory | None
+    body: Union["CommodityReadReply", "GetInformationReply", "ThermostatResponse", "AdvancedLoadUp", bytes]
+    opcode1: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.opcode1 is None and self.category is not None:
+            self.opcode1 = self.category.value
+
+    @classmethod
+    def from_payload(cls, payload: bytes) -> "IntermediateDR":
+        if not payload:
+            raise CodecError("empty Intermediate DR payload")
+        opcode1 = payload[0]
+        category = _enum_or_none(IntermediateDRCategory, opcode1)
+        body = payload[1:]
+        if category is IntermediateDRCategory.Consumption_Production:
+            return cls(category, CommodityReadReply.from_body(body), opcode1)
+        if category is IntermediateDRCategory.Device_Mode:
+            return cls(category, GetInformationReply.from_body(body), opcode1)
+        if category is IntermediateDRCategory.Thermostat:
+            return cls(category, ThermostatResponse.from_body(body), opcode1)
+        if category is IntermediateDRCategory.Advanced_Load_Up:
+            return cls(category, AdvancedLoadUp.from_body(body), opcode1)
+        return cls(category, bytes(body), opcode1)
+
+
+@dataclass
+class UnknownMessage:
+    """A frame whose message type this library does not (yet) decode."""
+
+    frame: Frame
+    message_type: MessageType
+
+
+Message = Union[BasicDR, IntermediateDR, UnknownMessage]
+
+
+# --------------------------------------------------------------------------- #
+# Decoding
+# --------------------------------------------------------------------------- #
+
+
+def decode_frame(frame: Frame) -> Message:
+    """Decode an already-parsed :class:`~cta2045.codec.Frame` into a message."""
+    mtype = MessageType.classify(frame.type_msb, frame.type_lsb)
+    if mtype is MessageType.Basic_DR:
+        return BasicDR.from_payload(frame.payload)
+    if mtype is MessageType.Intermediate_DR:
+        return IntermediateDR.from_payload(frame.payload)
+    return UnknownMessage(frame, mtype)
+
+
+def decode(data: bytes, offset: int = 0) -> tuple[Message, int]:
+    """Decode one message from ``data`` at ``offset``.
+
+    Returns the message and the offset just past it (for streaming).
+    """
+    frame, offset = parse_frame(data, offset)
+    return decode_frame(frame), offset
+
+
+def decode_all(data: bytes, offset: int = 0) -> list[Message]:
+    """Decode every back-to-back message in ``data``.
+
+    .. note::
+       This expects a clean buffer of concatenated frames. Transport-specific
+       quirks (framing junk, leading padding) are the binding's job to strip
+       before calling this.
+    """
+    messages: list[Message] = []
+    while offset < len(data):
+        message, offset = decode(data, offset)
+        messages.append(message)
+    return messages
+
+
+def decode_hex(s: str) -> list[Message]:
+    """Decode every message in an ASCII-hex string."""
+    return decode_all(hex_to_bytes(s))
+
+
+# --------------------------------------------------------------------------- #
+# Encoding — Basic DR commands (CTA-2045-B § 10)
+# --------------------------------------------------------------------------- #
+
+
+def _coerce_duration(value: Duration | float | None) -> Duration:
+    """Normalize a duration argument to a :class:`~cta2045.codec.Duration`.
+
+    ``None`` → Unknown; a bare number is interpreted as **minutes** (DR event
+    durations are expressed in minutes, not seconds); a
+    :class:`~cta2045.codec.Duration` passes through (use ``Duration.of_seconds``
+    or ``Duration.too_long()`` for other forms).
+    """
+    if value is None:
+        return Duration.unknown()
+    if isinstance(value, Duration):
+        return value
+    if isinstance(value, (int, float)):
+        return Duration.of_minutes(value)
+    raise TypeError(f"duration must be Duration, minutes (number), or None; got {type(value).__name__}")
+
+
+def shed(duration: Duration | float | None = None) -> BasicDR:
+    """Shed (curtail load) for ``duration`` minutes (CTA-2045-B § 10, opcode 0x01)."""
+    return BasicDR(BasicDRCategory.Shed, _coerce_duration(duration).to_byte())
+
+
+def end() -> BasicDR:
+    """End the current shed event (CTA-2045-B § 10, opcode 0x02)."""
+    return BasicDR(BasicDRCategory.End_Shed, 0x00)
+
+
+def critical_peak(duration: Duration | float | None = None) -> BasicDR:
+    """Critical peak event for ``duration`` minutes (CTA-2045-B § 10, opcode 0x0A)."""
+    return BasicDR(BasicDRCategory.Critical_Peak_Event, _coerce_duration(duration).to_byte())
+
+
+def grid_emergency(duration: Duration | float | None = None) -> BasicDR:
+    """Grid emergency event for ``duration`` minutes (CTA-2045-B § 10, opcode 0x0B)."""
+    return BasicDR(BasicDRCategory.Grid_Emergency, _coerce_duration(duration).to_byte())
+
+
+def load_up(duration: Duration | float | None = None) -> BasicDR:
+    """Load up (store energy) for ``duration`` minutes (CTA-2045-B § 10, opcode 0x17)."""
+    return BasicDR(BasicDRCategory.Load_Up, _coerce_duration(duration).to_byte())
+
+
+def power_level(percent: int) -> BasicDR:
+    """Request a power level of ``percent`` (0–100) (CTA-2045-B § 10, opcode 0x06)."""
+    if not 0 <= percent <= 100:
+        raise ValueError(f"power level percent must be 0-100, got {percent}")
+    return BasicDR(BasicDRCategory.Power_Level_Request, percent)
+
+
+# --------------------------------------------------------------------------- #
+# Encoding — Advanced Load Up (CTA-2045-B § 11.6, Intermediate DR 0x0C)
+# --------------------------------------------------------------------------- #
+
+
+def advanced_load_up(
+    duration_minutes: int,
+    value: int,
+    units: AdvancedLoadUpUnits | int,
+    *,
+    efficiency: int | None = None,
+    event_id: int | None = None,
+    start_time: int | None = None,
+    start_randomization: int | None = None,
+    end_randomization: int | None = None,
+) -> AdvancedLoadUp:
+    """SetAdvancedLoadUp request, UCM→SGD (CTA-2045-B § 11.6.3).
+
+    Asks the SGD to store ``value × units`` watt-hours of extra energy over
+    ``duration_minutes``. The trailing fields are optional; per the wire format
+    they are positional, so include them only as a prefix (e.g. ``event_id``
+    requires ``efficiency``).
+    """
+    return AdvancedLoadUp(
+        opcode2=0x00,
+        duration_minutes=duration_minutes,
+        value=value,
+        units=units,
+        efficiency=efficiency,
+        event_id=event_id,
+        start_time=start_time,
+        start_randomization=start_randomization,
+        end_randomization=end_randomization,
+    )
+
+
+def get_advanced_load_up() -> AdvancedLoadUp:
+    """GetAdvancedLoadUp request, UCM→SGD (CTA-2045-B § 11.6.1)."""
+    return AdvancedLoadUp(opcode2=0x00)