embedded-lab-control 0.2.0__py3-none-any.whl

embedded_lab_control-0.2.0.dist-info/RECORD

@@ -0,0 +1,64 @@
+embedded_lab_control-0.2.0.dist-info/licenses/LICENSE,sha256=InonMyQosEL1YAxd1TuJEd8UYdkXvlijEM73AL8Yujs,1066
+labctl/__init__.py,sha256=lkipuZBf71IlMAUSWvssK5yZ7D4g-bHXAubjdm3l2lk,213
+labctl/cli.py,sha256=cbg2oA8aQNDsXq0SWW59gDo1QTS16wryC-oUqx2AuxU,245038
+labctl/extras.py,sha256=zmGSob-AIhAvJ7GWDRT86ZySBXYn3c87LkMJ4yNMQIs,4806
+labctl/mcp_server.py,sha256=Ua_OCQ22JZLPVsKiBufY53aKcfS8W4kGyEKGW2VUG28,189991
+labctl/services.py,sha256=NSGPffs6TOw4l4-chPHRj8SUUNahRnldvxJDQLhKu20,6415
+labctl/actuators/__init__.py,sha256=dm-WGfXSrh7J-RAhC62Z7Zc8ZZi-59Kl308EBnlX2gs,1609
+labctl/actuators/base.py,sha256=16Fl_nhmqE2FdfO78bzYeG8234DZObwtq17xbjqtcX4,6600
+labctl/actuators/lcus1.py,sha256=mcaHCOcbCj3J_-sdL2mL3JB5GZihPx7cq0l-s1h5lX8,8516
+labctl/actuators/mock.py,sha256=PWypSYrmzARgDwd-SlmePsDs2aBZlyo-XgBQcJ6EcBM,2728
+labctl/actuators/runtime.py,sha256=1VPKMQybvmhteSHgq06KtSr37Y_tIOQRtuOU5DYCki4,41556
+labctl/core/__init__.py,sha256=yGq4oYFaFzgd4nhgnhHpitFTO_g__eWw2JDy0NU8nYI,684
+labctl/core/admin_files.py,sha256=s2ZXrqNFSRHRq8LZxyF8aP1uP2bTFyRVtcM2n3Ix5Cw,14401
+labctl/core/audit.py,sha256=xSts3q2ANI9P7vqggstub65n5h35pNYDhQVcY2qTIc4,8129
+labctl/core/claim_keepalive.py,sha256=PGaVniI1bAXOfqVweQYZPrL5hZ4TnM9y164sLPHSpqI,13387
+labctl/core/config.py,sha256=9EIcBX70ZJ9xdgOHN4S_8d4aMAiSMWfPIyHuzL-bFXU,39558
+labctl/core/database.py,sha256=eVOWzR-urzWQViGZM9kCbKgxFnTLhnf5lES_bmbyFMs,37136
+labctl/core/images.py,sha256=Yg9cUHtAj0JMrdIbk8Va94rr6ozVI9oCjzwog2r_w4I,19018
+labctl/core/manager.py,sha256=72mHaUDuHjr5b7FRWYmaQVsJgtTxL04W1SiuHEr0RGk,104260
+labctl/core/models.py,sha256=iO7wWWGd0Bx3WzUlURSLXC24yB82FEfUZNBVx1xrCAg,25929
+labctl/core/safe_open.py,sha256=nzUTgLykOheT6uZOESRlTSx2THImr-Kpa7V3q0tfUyA,4234
+labctl/health/__init__.py,sha256=eUgwHUzufBAlzWN0mDQOG6eyJGzLoPC8jRJ3hwIOYnY,845
+labctl/health/alerts.py,sha256=lQRqr8CvVuh0H0nHMnwHwrFliJPKKdFu4lhBx5ikNdo,7828
+labctl/health/checks.py,sha256=t3dYE4EucG27-N7-yYIQZ3F7H0yf2_Jchzn_xQaGfdg,18551
+labctl/health/daemon.py,sha256=ZgxibyRSZz1MYCkwlRIOQX_OgglV00LjqH0ESjl2TeY,14948
+labctl/power/__init__.py,sha256=-9eud2EnabNgd-ZC_WlWwUJvVGRJ_7oKc37-8g_AqnM,270
+labctl/power/base.py,sha256=HqiyE9LDEEqf7cLqpt32vVRBemnhltYoULKlJIfDHhU,3531
+labctl/power/kasa.py,sha256=pr48q75JZmINI-3PbRXTpEVufM23EwrrNHv3z5gOuZw,17312
+labctl/power/shelly.py,sha256=s30-SkQxc9SLhbdiNehrpGOAwMHtZJCd4aSImHTdo6Q,2424
+labctl/power/tasmota.py,sha256=XXlTrvqTXcPlSpRJ0LLkn7R96oyfNcNoYrz0COc6n94,2556
+labctl/sdwire/__init__.py,sha256=oCgO5CJmIGibCDmsy40EYDicruw-c3QuE5hF4O8UJlY,267
+labctl/sdwire/controller.py,sha256=7WiBgZlpjAkXYgdypqvQOj6M9g7netzqgqXoRXDxKgY,40052
+labctl/sdwire/power_guard.py,sha256=ZQyUCYflCjPvnFtVmpHBPG7zYWcJZOJZnE3Ot8_Ty1g,7035
+labctl/serial/__init__.py,sha256=0nnecD67zY9oUuhBc8JED8R0rRjPTtE9m3BS_9bsGW0,453
+labctl/serial/boot_test.py,sha256=FIp7ToSqQzsCEIAdb0J-A85lHvJCL76D3cONAGcsShY,11564
+labctl/serial/capture.py,sha256=gCmpFkTGpVggQnLCOYqNpDEISVdp80j1K4tvMVXVLgU,13242
+labctl/serial/keys.py,sha256=p-US8NPeuNncSp8hS3WfK13h0GAIy2nHZp5HVIH1PvE,2739
+labctl/serial/proxy.py,sha256=MYYL-Odwv7LtcdjN2ByPsE2FaKpKeFb_ZnGifwKusUU,27266
+labctl/serial/ser2net.py,sha256=ojyayulb7VI-cDgmj2MQhaBAPzYR23tN9Zp4zD9afmo,11246
+labctl/serial/udev.py,sha256=CeCW0sPUvdUIEC2P2TgMos-2nLQJAN6UjDBRr7Bf7No,9204
+labctl/web/__init__.py,sha256=pPEZvBgIr0gpCfB372nVoVBN7cljJhOh6HmRxhSAP_I,172
+labctl/web/activity_broadcaster.py,sha256=MF3ojS5_FIpuwT5S-efxSCq6kzU_8rJNULY1rPAXHUk,6940
+labctl/web/api.py,sha256=sqczdaxOg8SYvKh2BbdqarMfNXemf73-ziR4K8Ipi9Y,32224
+labctl/web/app.py,sha256=A84_WruJ8tcZtO8bN7G2hjB4IH-bbmMon_ZQ4Xtn6Lg,6855
+labctl/web/auth.py,sha256=Ti0FpunkBENy9WVgmR1VJvFJumLeovLjixdFh0sQMZY,2899
+labctl/web/claims.py,sha256=D7HEiRfV0J8J0B4z7bIHzyoF0S3od5RSTxWaW_0DBOA,8214
+labctl/web/views.py,sha256=FZNGVOE39yof0CcZTuiR5FTzVNGMfN-L4AjKDdntL0w,15701
+labctl/web/websocket.py,sha256=gm7U__qovW-vYa8B-GQDjI8lnCMVoeAVE_p7W3tqN5E,6417
+labctl/web/static/css/style.css,sha256=87irVk8NiJ-NQyoI9nAO1a-Ld51J0DmJUnnKnjPe6Y0,8825
+labctl/web/static/js/app.js,sha256=W8pXlJNO0Ln-Oi21TU04zfaYHeEpRv4S2vaLsL2hRAg,1894
+labctl/web/templates/activity.html,sha256=wctjzjJRBOuhmrIgCeDtRwfiRNJ6f7-Zn0mV0ljhqtA,8967
+labctl/web/templates/base.html,sha256=cG8XrbuZmalPcLMvJNGBP99mcH4fOPaq93piJk21v_0,1918
+labctl/web/templates/claim_refused.html,sha256=xxZeGDY6Zvf_J_y1f6wrHM0EmJjzEUObB5I6POlBJk8,1557
+labctl/web/templates/console.html,sha256=rYRTuYLqGZ3gXRCIkDdl3bvpQQ-Betis2lW1hGFlmM0,7226
+labctl/web/templates/dashboard.html,sha256=PVdwfjF--QY7I3bZVKcvgEyjWLW2v1nWkl7i6zzgvaU,4377
+labctl/web/templates/login.html,sha256=nT4BNddBzJOtQ3EE6sFl-ET2p67rxJXUdEPJsdR2CQs,938
+labctl/web/templates/sbc_detail.html,sha256=dWMIFwq_-qVRz4_4OG5fVEV9dtCln3lz9tPNox3j8YY,14741
+labctl/web/templates/settings.html,sha256=duYgyoFmA0eYb1h263RWQKu8_cOOQf6E6CeWGIvoi9k,3764
+labctl/web/templates/status_history.html,sha256=l034wodL8mov9TA0KDo3NyD8s3vi4nenHzNEfod3ve8,1757
+embedded_lab_control-0.2.0.dist-info/METADATA,sha256=ktNFWfoVAhXdMqIt2q0Zan0HS10SMF5Uc7-V9yFxsFI,40839
+embedded_lab_control-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+embedded_lab_control-0.2.0.dist-info/entry_points.txt,sha256=ZhZdQifWTGrL_6F6oq4MFWmgLsfjJ1zpJfpWyoMWsik,43
+embedded_lab_control-0.2.0.dist-info/top_level.txt,sha256=hNHhKmS2AGBs1uJ5U9XASup4_iYWtzqKfBJXqBM91vw,7
+embedded_lab_control-0.2.0.dist-info/RECORD,,

embedded_lab_control-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

embedded_lab_control-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+labctl = labctl.cli:main

embedded_lab_control-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Jezl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

embedded_lab_control-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+labctl

labctl/__init__.py

@@ -0,0 +1,8 @@
+"""
+Embedded Lab Control (labctl).
+
+Centralized management system for embedded development lab resources.
+Provides deterministic USB serial access, power control, and resource tracking.
+"""
+
+__version__ = "0.2.0"

labctl/actuators/__init__.py

@@ -0,0 +1,56 @@
+"""Actuator drivers and runtime layer.
+
+The :class:`RelayDriver` ABC defines the small protocol every concrete
+driver implements (LCUS-1, Numato, etc.). The runtime layer (added in
+later phases) sits between the manager's persistent state and the
+driver's transport; this package is the driver-side boundary.
+
+Use :func:`get_driver` rather than importing concrete driver modules
+directly so deferred drivers aren't paid for at import time.
+"""
+
+from typing import TYPE_CHECKING
+
+from labctl.actuators.base import (
+    DriverError,
+    ProbeOutcome,
+    ProbeResult,
+    RelayDriver,
+    Transport,
+    WriteOutcome,
+)
+
+if TYPE_CHECKING:
+    from labctl.core.models import DriverName
+
+__all__ = [
+    "DriverError",
+    "ProbeOutcome",
+    "ProbeResult",
+    "RelayDriver",
+    "Transport",
+    "WriteOutcome",
+    "get_driver",
+]
+
+
+def get_driver(
+    driver_name: "DriverName",
+    *,
+    expected_channel_count: int | None = None,
+) -> RelayDriver:
+    """Return a fresh, unopened driver instance for ``driver_name``.
+
+    The returned driver still needs an :meth:`~RelayDriver.open` call
+    with a :class:`Transport` before any I/O.
+
+    Drivers other than ``LCUS1_SERIAL`` are placeholders in v1 and
+    raise :class:`NotImplementedError` until their implementations land.
+    """
+    from labctl.core.models import DriverName
+
+    if driver_name is DriverName.LCUS1_SERIAL:
+        from labctl.actuators.lcus1 import Lcus1SerialDriver
+
+        return Lcus1SerialDriver(expected_channel_count=expected_channel_count)
+    raise NotImplementedError(f"driver {driver_name.value!r} is not implemented yet")

labctl/actuators/base.py

@@ -0,0 +1,183 @@
+"""Base classes for relay/actuator drivers.
+
+Every concrete driver (LCUS-1, Numato, HID, sysfs-GPIO, …) implements
+:class:`RelayDriver`. The runtime layer never imports a concrete
+driver directly — it asks the registry for a driver matching the
+:class:`labctl.core.models.DriverName` recorded on the actuator row.
+
+Outcome enums (:class:`WriteOutcome`, :class:`ProbeResult`) are the
+contract that lets composite operations like ``enter_recovery`` make
+safe decisions when the underlying USB transport flakes mid-sequence
+— see ``docs/SPEC_actuators.md`` ("USB disconnect mid-composite").
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class WriteOutcome(Enum):
+    """Structured result for a single :meth:`RelayDriver.set_channel` call."""
+
+    OK = "ok"  # write completed and was acknowledged (or believed-acked)
+    WRITE_FAILED = "write_failed"  # device responded but rejected the command
+    DEVICE_GONE = "device_gone"  # USB disconnect / port closed mid-write
+
+
+class ProbeResult(Enum):
+    """Coarse health classification returned by :meth:`RelayDriver.probe`."""
+
+    OK = "ok"
+    UNREACHABLE = "unreachable"  # cannot open the transport at all
+    AUTH_ERROR = "auth_error"  # placeholder for driver families that need it
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class ProbeOutcome:
+    """Read-only health probe response.
+
+    Probes are explicitly **side-effect-free** — they MUST NOT toggle
+    a channel even on write-only hardware. This avoids drops of held
+    pre-power straps mid-flash. See SPEC_actuators.md §"Health probes".
+    """
+
+    result: ProbeResult
+    detail: Optional[str] = None  # human-readable extra info
+
+
+@dataclass(frozen=True)
+class Transport:
+    """Connection parameters passed to :meth:`RelayDriver.open`.
+
+    Only the fields a given driver needs are populated; extras are
+    ignored. Captured as a dataclass so future drivers can grow new
+    fields without breaking the ABC signature.
+    """
+
+    device_path: Optional[str] = None
+    vid: Optional[str] = None
+    pid: Optional[str] = None
+    serial_no: Optional[str] = None
+    baud: int = 9600
+    open_timeout_seconds: float = 2.0
+
+
+def device_permission_hint(device_path: str) -> str:
+    """What to do when this process may not open ``device_path``.
+
+    Recommends joining the device's group only when that group grants
+    read/write and isn't root's; says when the account is already in it
+    but this process isn't (a login or service restart is missing).
+    """
+    import grp
+    import pwd
+    import stat
+
+    try:
+        account = pwd.getpwuid(os.geteuid())
+        user, primary_gid = account.pw_name, account.pw_gid
+    except KeyError:
+        user, primary_gid = None, None  # no account to name in usermod
+    generic = (
+        f"check that {user or f'uid {os.geteuid()}'} may read and write "
+        f"{device_path} "
+        "(ls -lL shows its owner, group and mode; for USB serial relays a "
+        "udev rule normally gives the dialout group read/write)"
+    )
+    try:
+        st = os.stat(device_path)
+        group = grp.getgrgid(st.st_gid)
+    except (OSError, KeyError):
+        return generic
+    group_rw = stat.S_IRGRP | stat.S_IWGRP
+    if user is None or st.st_gid == 0 or st.st_mode & group_rw != group_rw:
+        return generic
+    name = group.gr_name
+    if st.st_gid in os.getgroups() or st.st_gid == os.getegid():
+        return (
+            f"this process is already in the '{name}' group that owns it, so "
+            f"something else denies access; {generic}"
+        )
+    takes_effect = (
+        f"it takes effect in processes started after that: log out and back "
+        f"in (or run newgrp {name} in this shell), and restart any service "
+        "or MCP client that runs labctl"
+    )
+    if user in group.gr_mem or primary_gid == st.st_gid:
+        return (
+            f"{user} is in the '{name}' group that owns the device, but this "
+            f"process started before it was added; {takes_effect}"
+        )
+    return (
+        f"{user} needs to be in the '{name}' group that owns the device "
+        f"(check with: id -nG). To add it: sudo usermod -aG {name} {user}; "
+        + takes_effect
+    )
+
+
+class DriverError(Exception):
+    """Raised by drivers for unrecoverable errors (bad config, etc.).
+
+    Transient I/O issues should be reported as :class:`WriteOutcome`
+    or :class:`ProbeOutcome` instead, not raised — the runtime relies
+    on the structured outcome to decide whether to abort a composite.
+    """
+
+
+class RelayDriver(ABC):
+    """Minimal contract every concrete actuator driver implements.
+
+    Lifecycle:
+        1. Construct (cheap, no I/O).
+        2. :meth:`open` once with a :class:`Transport`.
+        3. Any number of :meth:`set_channel` / :meth:`get_channel` /
+           :meth:`probe` calls.
+        4. :meth:`close` to release the transport.
+
+    Concrete drivers MUST be safe to instantiate without an event loop
+    or any I/O so the manager can construct them lazily during config
+    loading. All I/O happens inside :meth:`open` and later calls.
+    """
+
+    @abstractmethod
+    def open(self, transport: Transport) -> None:
+        """Acquire the transport. Idempotent if already open."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release the transport. Idempotent on a closed driver."""
+
+    @abstractmethod
+    def set_channel(self, index: int, *, closed: bool) -> WriteOutcome:
+        """Drive a channel to ``closed`` (True) or ``open`` (False).
+
+        Returns a :class:`WriteOutcome`. Drivers SHOULD NOT raise on
+        I/O errors — return ``DEVICE_GONE`` or ``WRITE_FAILED`` instead
+        so callers can make composite-safe decisions.
+        """
+
+    @abstractmethod
+    def get_channel(self, index: int) -> Optional[bool]:
+        """Return ``True`` if closed, ``False`` if open, ``None`` if not queryable.
+
+        LCUS-1 returns ``None`` here; Numato can read back actual state.
+        """
+
+    @abstractmethod
+    def channel_count(self) -> Optional[int]:
+        """Return the device's channel count, or ``None`` if not enumerable.
+
+        For non-enumerable drivers (LCUS-1), the manager's provisioning
+        ``--channels`` hint is authoritative. For enumerable drivers
+        (Numato), this overrides the hint and a mismatch is rejected
+        at provisioning time.
+        """
+
+    @abstractmethod
+    def probe(self) -> ProbeOutcome:
+        """Read-only health check. MUST NOT toggle a channel."""

labctl/actuators/lcus1.py

@@ -0,0 +1,232 @@
+"""LCUS-1 (CH340-based USB relay) driver.
+
+Hardware notes
+==============
+LCUS-1 boards are the cheap CH340-clone single-channel USB relays
+(also branded "USR-IO" or unbranded). They speak a 4-byte fixed-frame
+protocol at 9600/8N1; there is no acknowledgement and no state
+read-back. Relay state must be tracked in software.
+
+Frame layout (no spaces in the wire bytes):
+
+    AA  CC  SS  KK
+    │   │   │   └─ checksum: low byte of (AA + CC + SS)
+    │   │   └──── state: 0x00 = open, 0x01 = close
+    │   └──────── channel index, 1-based (typically 0x01)
+    └──────────── start byte 0xA0
+
+Examples:
+
+    A0 01 01 A2   →   channel 1 close
+    A0 01 00 A1   →   channel 1 open
+    A0 02 01 A3   →   channel 2 close (multi-channel clones)
+
+Probe semantics
+---------------
+We deliberately do NOT toggle a channel during ``probe`` — see
+``docs/SPEC_actuators.md`` §"Health probes". A held ``recovery_mode``
+strap mid-flash must survive a probe cycle. Probe = "open the serial
+port, verify it opens, close" — that's it.
+
+Concurrency
+-----------
+The driver itself is not thread-safe across multiple ``set_channel``
+calls; the manager-level per-channel lock (added in Phase 4) is what
+serializes writes. ``open`` and ``close`` are idempotent.
+"""
+
+from __future__ import annotations
+
+import errno
+import logging
+from typing import Optional
+
+from labctl.actuators.base import (
+    DriverError,
+    ProbeOutcome,
+    ProbeResult,
+    RelayDriver,
+    Transport,
+    WriteOutcome,
+    device_permission_hint,
+)
+from labctl.extras import broken_extra_message, is_missing, missing_extra_message
+
+logger = logging.getLogger(__name__)
+
+
+# Frame layout constants. Documented inline in the module docstring above.
+LCUS1_START_BYTE = 0xA0
+LCUS1_STATE_CLOSED = 0x01
+LCUS1_STATE_OPEN = 0x00
+LCUS1_FRAME_LEN = 4
+
+
+def _build_frame(channel_index: int, *, closed: bool) -> bytes:
+    """Build a 4-byte LCUS-1 command frame."""
+    state = LCUS1_STATE_CLOSED if closed else LCUS1_STATE_OPEN
+    checksum = (LCUS1_START_BYTE + channel_index + state) & 0xFF
+    return bytes([LCUS1_START_BYTE, channel_index, state, checksum])
+
+
+class Lcus1SerialDriver(RelayDriver):
+    """LCUS-1 / generic CH340 single-channel USB relay driver."""
+
+    def __init__(self, *, expected_channel_count: Optional[int] = None):
+        """Construct the driver. Hardware I/O happens in :meth:`open`.
+
+        Args:
+            expected_channel_count: hint from provisioning. LCUS-1 has
+                no enumeration protocol, so this value is what
+                :meth:`channel_count` returns. The manager treats this
+                as authoritative for non-enumerable drivers.
+        """
+        self._port = None  # type: Optional[object]  # serial.Serial
+        self._transport: Optional[Transport] = None
+        self._expected_channels = expected_channel_count
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def open(self, transport: Transport) -> None:
+        """Open the serial port. Idempotent if already open."""
+        if self._port is not None:
+            return
+        try:
+            import serial  # type: ignore
+        except ImportError as e:
+            if not is_missing(e, "serial"):
+                raise DriverError(
+                    f"lcus1_serial driver: {broken_extra_message('actuators', e)}"
+                ) from e
+            raise DriverError(
+                f"lcus1_serial driver: {missing_extra_message('actuators')}"
+            ) from e
+
+        if not transport.device_path:
+            raise DriverError("lcus1_serial driver requires transport.device_path")
+
+        try:
+            self._port = serial.Serial(
+                port=transport.device_path,
+                baudrate=transport.baud or 9600,
+                bytesize=8,
+                parity=serial.PARITY_NONE,
+                stopbits=1,
+                timeout=transport.open_timeout_seconds,
+                write_timeout=transport.open_timeout_seconds,
+            )
+        except (OSError, serial.SerialException) as e:
+            self._port = None
+            if getattr(e, "errno", None) in (errno.EACCES, errno.EPERM):
+                raise DriverError(
+                    f"permission denied opening {transport.device_path}: "
+                    + device_permission_hint(transport.device_path)
+                ) from e
+            raise DriverError(f"failed to open {transport.device_path}: {e}") from e
+        self._transport = transport
+        logger.debug("LCUS-1 opened %s", transport.device_path)
+
+    def close(self) -> None:
+        """Close the serial port. Idempotent on a closed driver."""
+        if self._port is None:
+            return
+        try:
+            self._port.close()
+        except Exception as e:  # noqa: BLE001
+            logger.debug("LCUS-1 close raised %s; ignoring", e)
+        finally:
+            self._port = None
+
+    def _require_open(self) -> None:
+        if self._port is None:
+            raise DriverError("driver not open; call open(transport) first")
+
+    # -- I/O ---------------------------------------------------------------
+
+    def set_channel(self, index: int, *, closed: bool) -> WriteOutcome:
+        """Drive a channel; return a structured outcome.
+
+        Returns ``DEVICE_GONE`` for transport-level failures (USB
+        disconnect, port closed) and ``WRITE_FAILED`` for short writes
+        or other recoverable error paths.
+        """
+        self._require_open()
+        if index < 1:
+            return WriteOutcome.WRITE_FAILED
+        if self._expected_channels is not None and index > self._expected_channels:
+            return WriteOutcome.WRITE_FAILED
+
+        frame = _build_frame(index, closed=closed)
+        try:
+            written = self._port.write(frame)
+            self._port.flush()
+        except Exception as e:  # noqa: BLE001 — pyserial raises a zoo of these
+            # Any transport-level failure is reported as DEVICE_GONE so
+            # composite operations abort safely instead of retrying onto
+            # a vanished device.
+            logger.warning(
+                "LCUS-1 write to channel %d failed: %s: %s",
+                index,
+                type(e).__name__,
+                e,
+            )
+            return WriteOutcome.DEVICE_GONE
+
+        if written != LCUS1_FRAME_LEN:
+            logger.warning(
+                "LCUS-1 short write to channel %d: %d/%d bytes",
+                index,
+                written,
+                LCUS1_FRAME_LEN,
+            )
+            return WriteOutcome.WRITE_FAILED
+        return WriteOutcome.OK
+
+    def get_channel(self, index: int) -> Optional[bool]:
+        """LCUS-1 has no read-back; always returns None."""
+        return None
+
+    def channel_count(self) -> Optional[int]:
+        """No enumeration protocol — return the provisioning hint."""
+        return self._expected_channels
+
+    # -- probe -------------------------------------------------------------
+
+    def probe(self) -> ProbeOutcome:
+        """Read-only probe: try opening the port if not already open.
+
+        MUST NOT toggle a channel even on write-only hardware — a held
+        pre_power strap during a flash must survive probes.
+        """
+        if self._port is not None:
+            return ProbeOutcome(result=ProbeResult.OK)
+
+        # Opening transiently to verify reachability without writing.
+        if self._transport is None:
+            return ProbeOutcome(
+                result=ProbeResult.UNKNOWN,
+                detail="probe before first open() — no transport hint",
+            )
+
+        try:
+            import serial  # type: ignore
+        except ImportError as e:
+            if not is_missing(e, "serial"):
+                return ProbeOutcome(
+                    result=ProbeResult.UNKNOWN,
+                    detail=broken_extra_message("actuators", e),
+                )
+            return ProbeOutcome(
+                result=ProbeResult.UNKNOWN, detail=missing_extra_message("actuators")
+            )
+
+        try:
+            test = serial.Serial(
+                port=self._transport.device_path,
+                baudrate=self._transport.baud or 9600,
+                timeout=self._transport.open_timeout_seconds,
+            )
+            test.close()
+        except (OSError, serial.SerialException) as e:
+            return ProbeOutcome(result=ProbeResult.UNREACHABLE, detail=str(e))
+        return ProbeOutcome(result=ProbeResult.OK)

labctl/actuators/mock.py

@@ -0,0 +1,81 @@
+"""In-memory mock driver for tests.
+
+Programmable failure modes let tests exercise the
+:class:`~labctl.actuators.base.WriteOutcome` paths (composite abort
+on ``DEVICE_GONE``, etc.) without requiring real hardware.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from labctl.actuators.base import (
+    DriverError,
+    ProbeOutcome,
+    ProbeResult,
+    RelayDriver,
+    Transport,
+    WriteOutcome,
+)
+
+
+class MockRelayDriver(RelayDriver):
+    """Deterministic, in-memory relay used by tests and dry-runs.
+
+    State for each channel is kept in a dict; reads return the cached
+    value (so :meth:`get_channel` returns the truth post-write).
+
+    Failure-mode toggles:
+        * ``next_write_outcome`` — if set, the next ``set_channel`` call
+          returns this outcome and clears the override. Useful for
+          driving composite-abort paths.
+        * ``probe_result`` — what :meth:`probe` returns. Default OK.
+        * ``queryable`` — when False, :meth:`get_channel` returns None
+          (LCUS-1-like behavior).
+    """
+
+    def __init__(self, *, channel_count: int = 1, queryable: bool = True):
+        self._configured_count = channel_count
+        self._queryable = queryable
+        self._states: dict[int, bool] = {}
+        self._open = False
+        self.next_write_outcome: Optional[WriteOutcome] = None
+        self.probe_result: ProbeResult = ProbeResult.OK
+        self.write_log: list[tuple[int, bool, WriteOutcome]] = []
+
+    def open(self, transport: Transport) -> None:
+        self._open = True
+
+    def close(self) -> None:
+        self._open = False
+
+    def _require_open(self) -> None:
+        if not self._open:
+            raise DriverError("driver not open")
+
+    def set_channel(self, index: int, *, closed: bool) -> WriteOutcome:
+        self._require_open()
+        if index < 1 or index > self._configured_count:
+            return WriteOutcome.WRITE_FAILED
+        if self.next_write_outcome is not None:
+            outcome = self.next_write_outcome
+            self.next_write_outcome = None
+            self.write_log.append((index, closed, outcome))
+            if outcome is WriteOutcome.OK:
+                self._states[index] = closed
+            return outcome
+        self._states[index] = closed
+        self.write_log.append((index, closed, WriteOutcome.OK))
+        return WriteOutcome.OK
+
+    def get_channel(self, index: int) -> Optional[bool]:
+        self._require_open()
+        if not self._queryable:
+            return None
+        return self._states.get(index)
+
+    def channel_count(self) -> Optional[int]:
+        return self._configured_count
+
+    def probe(self) -> ProbeOutcome:
+        return ProbeOutcome(result=self.probe_result)