pmri-dccex 0.1.0__py3-none-any.whl

pmri_dccex/__init__.py

@@ -0,0 +1,37 @@
+"""pmri-dccex -- DCC-EX driver. Bracket-delimited ASCII protocol."""
+from pmri_dccex.beans import (
+    DccexPowerManager,
+    DccexSensor,
+    DccexSensorManager,
+    DccexTurnout,
+    DccexTurnoutManager,
+)
+from pmri_dccex.codec import DccexMessage, DccexUnknown, decode, encode
+from pmri_dccex.connection import DccexConnection
+from pmri_dccex.exrail import (
+    DccexExRailManager,
+    ExRailAspect,
+    ExRailEntry,
+    ExRailKind,
+)
+from pmri_dccex.programmer import (
+    DccexOpsProgrammer,
+    DccexProgrammer,
+    DccexProgrammerManager,
+    DccexServiceProgrammer,
+)
+from pmri_dccex.throttle import DccexThrottle, DccexThrottleManager
+from pmri_dccex.traffic import DccexTrafficController
+from pmri_dccex.transport import BytePort, LoopbackPort, SerialPort, TcpPort, loopback_pair
+
+__version__ = "0.1.0"
+__all__ = [
+    "BytePort", "DccexConnection", "DccexExRailManager", "DccexMessage",
+    "DccexOpsProgrammer", "DccexPowerManager", "DccexProgrammer",
+    "DccexProgrammerManager", "DccexSensor", "DccexSensorManager",
+    "DccexServiceProgrammer", "DccexThrottle", "DccexThrottleManager",
+    "DccexTrafficController", "DccexTurnout", "DccexTurnoutManager",
+    "DccexUnknown", "ExRailAspect", "ExRailEntry", "ExRailKind",
+    "LoopbackPort", "SerialPort", "TcpPort", "__version__", "decode",
+    "encode", "loopback_pair",
+]

pmri_dccex/beans.py

@@ -0,0 +1,167 @@
+"""DCC-EX-aware beans + their managers + power manager.
+
+Wire-protocol summary (CommandStation-EX docs, command-summary-consolidated):
+
+* Turnouts: ``<T id state>`` where state 0 = CLOSED, 1 = THROWN.
+  Response: ``<H id state>`` using the same encoding.
+  Note: this is the OPPOSITE of the NMRA DCC packet convention where
+  bit 0 of the accessory data byte is 1 = "closed / normal". DCC-EX
+  chose the human-facing "0 = at rest, 1 = deflected" mapping instead.
+  Do not "correct" this to match DCC -- verified against
+  https://dcc-ex.com/reference/software/command-summary-consolidated.html
+* Sensors:  ``<Q id>`` = active, ``<q id>`` = inactive (server -> client).
+* Power:    ``<1>`` = on, ``<0>`` = off. Response: ``<p state>``.
+"""
+from __future__ import annotations
+
+import contextlib
+
+from pmri_core.beans.power import PowerManager
+from pmri_core.beans.sensor import Sensor
+from pmri_core.beans.turnout import Turnout
+from pmri_core.manager import Manager
+from pmri_core.state import PowerState, SensorState, TurnoutState
+
+from pmri_dccex.codec import DccexMessage
+from pmri_dccex.traffic import DccexTrafficController
+
+# ----- Turnout -------------------------------------------------------------
+
+
+class DccexTurnout(Turnout):
+    """Sends ``<T id state>`` on commanded-state change."""
+
+    __slots__ = ("_address", "_tc")
+
+    def __init__(self, system_name: str, address: int, tc: DccexTrafficController) -> None:
+        super().__init__(system_name)
+        self._address = address
+        self._tc = tc
+
+    @property
+    def address(self) -> int:
+        return self._address
+
+    async def set_commanded_state(self, state: TurnoutState) -> None:
+        # DCC-EX: 0 = CLOSED, 1 = THROWN (opposite of the DCC accessory
+        # packet convention -- see module docstring).
+        wire = 0 if state == TurnoutState.CLOSED else 1
+        await self._tc.send(DccexMessage(command="T", args=(str(self._address), str(wire))))
+        await super().set_commanded_state(state)
+
+
+class DccexTurnoutManager(Manager[DccexTurnout]):
+    type_letter = "T"
+
+    def __init__(self, system_prefix: str, *, tc: DccexTrafficController) -> None:
+        super().__init__(system_prefix)
+        self._tc = tc
+        self._by_address: dict[int, DccexTurnout] = {}
+        self._unsub = tc.inbound.connect(self._on_message)
+
+    def _create(self, system_name: str) -> DccexTurnout:
+        address = _parse_address(system_name, self.full_prefix)
+        bean = DccexTurnout(system_name, address, self._tc)
+        self._by_address[address] = bean
+        return bean
+
+    def get_by_address(self, address: int) -> DccexTurnout | None:
+        return self._by_address.get(address)
+
+    async def _on_message(self, msg: DccexMessage) -> None:
+        # <H id state> -- turnout state echo from CS.
+        if msg.command != "H" or len(msg.args) < 2:
+            return
+        try:
+            addr = int(msg.args[0])
+            state_int = int(msg.args[1])
+        except ValueError:
+            return
+        bean = self._by_address.get(addr)
+        if bean is None:
+            return
+        # DCC-EX response encoding matches the command: 0 = CLOSED, 1 = THROWN.
+        state = TurnoutState.THROWN if state_int else TurnoutState.CLOSED
+        await bean._set_known_state(state)
+
+
+# ----- Sensor --------------------------------------------------------------
+
+
+class DccexSensor(Sensor):
+    __slots__ = ("_address",)
+
+    def __init__(self, system_name: str, address: int) -> None:
+        super().__init__(system_name)
+        self._address = address
+
+    @property
+    def address(self) -> int:
+        return self._address
+
+
+class DccexSensorManager(Manager[DccexSensor]):
+    type_letter = "S"
+
+    def __init__(self, system_prefix: str, *, tc: DccexTrafficController) -> None:
+        super().__init__(system_prefix)
+        self._by_address: dict[int, DccexSensor] = {}
+        self._unsub = tc.inbound.connect(self._on_message)
+
+    def _create(self, system_name: str) -> DccexSensor:
+        address = _parse_address(system_name, self.full_prefix)
+        bean = DccexSensor(system_name, address)
+        self._by_address[address] = bean
+        return bean
+
+    def get_by_address(self, address: int) -> DccexSensor | None:
+        return self._by_address.get(address)
+
+    async def _on_message(self, msg: DccexMessage) -> None:
+        # <Q id> active, <q id> inactive.
+        if msg.command not in ("Q", "q") or not msg.args:
+            return
+        with contextlib.suppress(ValueError):
+            addr = int(msg.args[0])
+            bean = self._by_address.get(addr)
+            if bean is not None:
+                state = SensorState.ACTIVE if msg.command == "Q" else SensorState.INACTIVE
+                await bean._set_known_state(state)
+
+
+# ----- Power ---------------------------------------------------------------
+
+
+class DccexPowerManager(PowerManager):
+    """``<1>`` on, ``<0>`` off."""
+
+    def __init__(self, tc: DccexTrafficController) -> None:
+        super().__init__()
+        self._tc = tc
+        self._unsub = tc.inbound.connect(self._on_message)
+
+    async def set_power(self, state: PowerState) -> None:
+        cmd = "1" if state == PowerState.ON else "0"
+        await self._tc.send(DccexMessage(command=cmd, args=()))
+        await self._set_state(state)
+
+    async def _on_message(self, msg: DccexMessage) -> None:
+        # <p state> -- power state echo. state=1 means on, 0 off.
+        if msg.command != "p" or not msg.args:
+            return
+        with contextlib.suppress(ValueError):
+            wire = int(msg.args[0])
+            await self._set_state(PowerState.ON if wire else PowerState.OFF)
+
+
+# ----- helpers --------------------------------------------------------------
+
+
+def _parse_address(system_name: str, full_prefix: str) -> int:
+    rest = system_name.removeprefix(full_prefix)
+    try:
+        return int(rest)
+    except ValueError as e:
+        raise ValueError(
+            f"DCC-EX system name {system_name!r} must end in a numeric address"
+        ) from e

pmri_dccex/codec.py

@@ -0,0 +1,83 @@
+"""DCC-EX text protocol codec.
+
+DCC-EX (formerly DCC++) is a bracket-delimited ASCII protocol:
+
+    <command arg1 arg2 ...>
+
+Commands and responses both use the same bracket convention. Multiple
+commands can be sent back-to-back; the codec reads one complete bracketed
+message at a time and strips the brackets.
+
+Common commands JMRI uses:
+
+* ``<1>`` / ``<0>`` -- power on / off
+* ``<T id 1|0>`` -- set turnout *id* to closed (1) or thrown (0)
+* ``<S id pin pullup>`` -- define sensor (server-side state only)
+* ``<t cab loco speed dir>`` -- throttle command (legacy form)
+* ``<R cv>`` -- read CV; ``<W cv val>`` -- write CV
+* ``<Q id>`` -- sensor active report (server -> client)
+* ``<q id>`` -- sensor inactive report
+
+Responses follow the same shape; unknown messages decode to
+:class:`DccexUnknown` so listeners don't lose visibility.
+"""
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class DccexMessage:
+    """A parsed message -- command character + space-separated args."""
+
+    command: str          # first token (e.g. "1", "T", "Q")
+    args: tuple[str, ...] # remaining tokens
+
+    @property
+    def raw(self) -> str:
+        if not self.args:
+            return self.command
+        return f"{self.command} {' '.join(self.args)}"
+
+
+@dataclass(frozen=True, slots=True)
+class DccexUnknown(DccexMessage):
+    """Marker subclass: a well-formed bracket message we don't recognize."""
+
+
+def encode(msg: DccexMessage) -> bytes:
+    """Wrap a message in brackets and return as UTF-8 bytes."""
+    return f"<{msg.raw}>".encode()
+
+
+def decode(text: str) -> DccexMessage:
+    """Parse the content *between* the brackets into a :class:`DccexMessage`."""
+    text = text.strip()
+    if not text:
+        raise ValueError("empty DCC-EX message body")
+    tokens = text.split()
+    return DccexMessage(command=tokens[0], args=tuple(tokens[1:]))
+
+
+async def read_message(
+    read_byte: Callable[[], Awaitable[int]],
+) -> str:
+    """Read one bracketed message from the byte stream.
+
+    Bytes outside a ``<...>`` pair are silently discarded (matches DCC-EX
+    convention: newlines and other status text between messages are noise).
+    Returns the *unwrapped* contents (no brackets).
+    """
+    # Wait for opening bracket.
+    while True:
+        b = await read_byte()
+        if b == ord('<'):
+            break
+
+    out = bytearray()
+    while True:
+        b = await read_byte()
+        if b == ord('>'):
+            return out.decode("utf-8", errors="replace")
+        out.append(b)

pmri_dccex/connection.py

@@ -0,0 +1,162 @@
+"""``DccexConnection`` -- SystemConnection subclass for DCC-EX command stations."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, ClassVar
+
+from pmri_core.hal.connection import ConnectionSettings, SystemConnection
+
+from pmri_dccex.beans import DccexPowerManager, DccexSensorManager, DccexTurnoutManager
+from pmri_dccex.codec import DccexMessage
+from pmri_dccex.exrail import DccexExRailManager
+from pmri_dccex.programmer import DccexProgrammer, DccexProgrammerManager
+from pmri_dccex.throttle import DccexThrottleManager
+from pmri_dccex.traffic import DccexTrafficController
+from pmri_dccex.transport import BytePort, LoopbackPort, SerialPort, TcpPort
+
+
+class DccexConnection(SystemConnection):
+    name: ClassVar[str] = "DCC-EX"
+    prefix: ClassVar[str] = "D"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._port: BytePort | None = None
+        self._tc: DccexTrafficController | None = None
+        self._programmer: DccexProgrammer | None = None
+        self._cs_monitor_task: asyncio.Task[None] | None = None
+        self._cs_ping_task: asyncio.Task[None] | None = None
+        self._exrail: DccexExRailManager | None = None
+
+    async def open(self, settings: ConnectionSettings | None = None) -> None:
+        s = settings or {}
+        self._port = await _build_port(s)
+        self._tc = DccexTrafficController(self._port)
+        await self._tc.start()
+
+        self.turnouts = DccexTurnoutManager(self.prefix, tc=self._tc)        # type: ignore[assignment]
+        self.sensors = DccexSensorManager(self.prefix, tc=self._tc)          # type: ignore[assignment]
+        self.throttles = DccexThrottleManager(self.prefix, tc=self._tc)
+        # Rebind the consist manager onto the DCC-EX-aware throttle
+        # manager. Without this the fan-out drives placeholder beans
+        # and no ``<t>`` (throttle) frames reach the CS.
+        self.consists.rebind_throttles(self.throttles)
+        self.power = DccexPowerManager(self._tc)
+        self._programmer = DccexProgrammer(self._tc)
+        self.programmers = DccexProgrammerManager(self._programmer)
+        # Wire advanced-consist CV19 writes onto the DCC-EX programmer.
+        self.consists.rebind_programmers(self.programmers)
+        # EX-RAIL automation client. Routes/automations are compiled
+        # into the CS firmware; we only introspect + trigger.
+        self._exrail = DccexExRailManager(self._tc)
+
+        # CS reachability: DCC-EX doesn't chatter unsolicited, so we
+        # ping ``<s>`` (status query) every 2 seconds and watch for
+        # ANY inbound message within 3 seconds. Status ping response
+        # is ``<p 0>``/``<p 1>`` plus other startup chatter -- any of
+        # which resets the monitor's silence timer. Start pessimistic
+        # (base class default is optimistic True) so a home-page
+        # render during the monitor's startup grace shows "Off" until
+        # we've actually seen a reply, not a false "On".
+        self._cs_reachable = False
+        self._cs_ping_task = asyncio.create_task(
+            self._cs_ping_loop(), name="dccex-cs-ping",
+        )
+        self._cs_monitor_task = asyncio.create_task(
+            self._cs_reachability_loop(), name="dccex-cs-reachability",
+        )
+
+        await super().open(settings)
+
+    async def _cs_ping_loop(self) -> None:
+        """Send ``<s>`` every 2s so the CS keeps replying with status
+        traffic -- that's what the reachability monitor watches for."""
+        import contextlib  # noqa: PLC0415
+        try:
+            while True:
+                await asyncio.sleep(2.0)
+                if self._tc is None:
+                    return
+                try:
+                    await self._tc.send(DccexMessage(command="s", args=()))
+                except Exception:  # noqa: BLE001
+                    # Send may raise on a closed port; the monitor
+                    # loop notices via the silence timer.
+                    pass
+        except asyncio.CancelledError:
+            with contextlib.suppress(Exception):
+                return
+
+    async def _cs_reachability_loop(self) -> None:
+        """3-second silence rule against ``last_inbound_at``."""
+        import contextlib  # noqa: PLC0415
+        try:
+            await asyncio.sleep(3.0)   # startup grace
+            while True:
+                await asyncio.sleep(1.0)
+                if self._tc is None:
+                    return
+                last = self._tc.last_inbound_at
+                if last is None:
+                    await self._set_cs_reachable(False)
+                    continue
+                age = time.monotonic() - last
+                await self._set_cs_reachable(age <= 3.0)
+        except asyncio.CancelledError:
+            with contextlib.suppress(Exception):
+                return
+
+    async def close(self) -> None:
+        for task in (self._cs_ping_task, self._cs_monitor_task):
+            if task is not None:
+                task.cancel()
+                import contextlib  # noqa: PLC0415
+                with contextlib.suppress(asyncio.CancelledError, Exception):
+                    await task
+        self._cs_ping_task = None
+        self._cs_monitor_task = None
+        if self._tc is not None:
+            await self._tc.aclose()
+            self._tc = None
+        self._port = None
+        self._exrail = None
+        await super().close()
+
+    @property
+    def traffic(self) -> DccexTrafficController:
+        if self._tc is None:
+            raise RuntimeError("connection not open")
+        return self._tc
+
+    @property
+    def exrail(self) -> DccexExRailManager:
+        """EX-RAIL manager: inspect compiled routes/automations and
+        trigger them at runtime. Routes/automations are authored in
+        the CS firmware's ``myAutomation.h``; the client can only
+        introspect + control, not upload. Available after :meth:`open`."""
+        if self._exrail is None:
+            raise RuntimeError("connection not open")
+        return self._exrail
+
+
+async def _build_port(settings: dict[str, Any]) -> BytePort:
+    kind = settings.get("kind", "loopback")
+    if kind == "serial":
+        port = settings.get("port")
+        if not port:
+            raise ValueError("serial transport requires 'port'")
+        baud = int(settings.get("baud", 115200))
+        return await SerialPort.open(port=port, baud=baud)
+    if kind == "tcp":
+        host = settings.get("host")
+        tcp_port = settings.get("tcp_port")
+        if not host or tcp_port is None:
+            raise ValueError("tcp transport requires 'host' and 'tcp_port'")
+        return await TcpPort.open(host=host, port=int(tcp_port))
+    if kind == "loopback":
+        lb = settings.get("loopback_port")
+        if not isinstance(lb, LoopbackPort):
+            raise ValueError("loopback transport requires 'loopback_port'")
+        return lb
+    raise ValueError(f"unknown DCC-EX transport kind: {kind!r}")