seymourlib 0.1.0__py3-none-any.whl

seymourlib/cli.py

@@ -0,0 +1,249 @@
+"""Simple CLI utility to exercise the client."""
+
+import logging
+from typing import Annotated
+
+import attrs
+import typer
+from async_typer import AsyncTyper
+from rich import print as rprint
+
+from seymourlib.protocol import DiagnosticOption, MotorID, MovementCode, Ratio
+
+from .client import SeymourClient
+from .transport import SeymourTransport
+
+app = AsyncTyper(help="Seymour controller CLI")
+
+
+@attrs.frozen
+class GlobalOptions:
+    verbose: bool
+    host: str
+    port: int
+    serial_port: str | None
+
+
+_GLOBAL_OPTIONS: GlobalOptions | None = None
+
+
+@app.callback()  # type: ignore
+def handle_global_options(
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose output.",
+        ),
+    ] = False,
+    host: Annotated[
+        str,
+        typer.Option(
+            "--host",
+            "-h",
+            help="Hostname or IP address for TCP transport.",
+            envvar="SEYMOUR_HOST",
+        ),
+    ] = "localhost",
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            "-p",
+            help="Port number for TCP transport.",
+            envvar="SEYMOUR_PORT",
+        ),
+    ] = 4999,
+    serial_port: Annotated[
+        str | None,
+        typer.Option(
+            "--serial-port",
+            "-s",
+            help="Serial port device for Serial transport (overrides host/port).",
+            envvar="SEYMOUR_SERIAL_PORT",
+        ),
+    ] = None,
+) -> None:
+    global _GLOBAL_OPTIONS
+    _GLOBAL_OPTIONS = GlobalOptions(verbose=verbose, host=host, port=port, serial_port=serial_port)
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.WARN)
+
+
+def _get_client() -> SeymourClient:
+    assert _GLOBAL_OPTIONS is not None
+    if _GLOBAL_OPTIONS.serial_port:
+        from .transport import SerialTransport
+
+        transport: SeymourTransport = SerialTransport(_GLOBAL_OPTIONS.serial_port)
+    else:
+        from .transport import TCPTransport
+
+        transport = TCPTransport(_GLOBAL_OPTIONS.host, _GLOBAL_OPTIONS.port)
+
+    return SeymourClient(transport)
+
+
+@app.async_command()  # type: ignore
+async def status() -> None:
+    """Show the current status code."""
+    async with _get_client() as client:
+        status = await client.get_status()
+        rprint(status)
+
+
+@app.async_command()  # type: ignore
+async def calibrate(motor: Annotated[MotorID, typer.Argument()] = MotorID.ALL) -> None:
+    """Calibrate the given motor(s) by moving all the way in & out."""
+    async with _get_client() as client:
+        await client.calibrate(motor)
+
+
+positions_app = AsyncTyper(help="Commands for the motors' absolute positions.")
+app.add_typer(positions_app, name="positions")
+
+
+@positions_app.async_command("get")  # type: ignore
+async def positions_get() -> None:
+    """Show the current motor positions."""
+    async with _get_client() as client:
+        positions = await client.get_positions()
+        for position in positions:
+            rprint(position)
+
+
+@positions_app.async_command("halt")  # type: ignore
+async def positions_halt(motor: Annotated[MotorID, typer.Argument()] = MotorID.ALL) -> None:
+    """Stop the specified motor(s) at their current position."""
+    async with _get_client() as client:
+        await client.halt(motor)
+
+
+@positions_app.async_command("home")  # type: ignore
+async def positions_home(motor: Annotated[MotorID, typer.Argument()] = MotorID.ALL) -> None:
+    """Move the specified motor(s) to their home position."""
+    async with _get_client() as client:
+        await client.home(motor)
+
+
+def _parse_increment(move: bool, jog: bool, until_limit: bool) -> MovementCode:
+    match (move, jog, until_limit):
+        case (True, False, False):
+            return MovementCode.MOVE
+        case (False, True, False):
+            return MovementCode.JOG
+        case (False, False, True):
+            return MovementCode.UNTIL_LIMIT
+        case _:
+            raise typer.BadParameter(
+                "Exactly one of --move, --jog, or --until-limit must be specified."
+            )
+
+
+@positions_app.async_command("in")  # type: ignore
+async def positions_in(
+    motor: Annotated[MotorID, typer.Argument()] = MotorID.ALL,
+    move: bool = True,
+    jog: bool = False,
+    until_limit: bool = False,
+) -> None:
+    """Move the specified motor(s) inward by the given increment."""
+    increment = _parse_increment(move, jog, until_limit)
+    async with _get_client() as client:
+        await client.move_in(motor, increment)
+
+
+@positions_app.async_command("out")  # type: ignore
+async def positions_out(
+    motor: Annotated[MotorID, typer.Argument()] = MotorID.ALL,
+    move: bool = True,
+    jog: bool = False,
+    until_limit: bool = False,
+) -> None:
+    """Move the specified motor(s) outward by the given increment."""
+    increment = _parse_increment(move, jog, until_limit)
+    async with _get_client() as client:
+        await client.move_out(motor, increment)
+
+
+preset_app = AsyncTyper(help="Commands for motor presets.")
+app.add_typer(preset_app, name="preset")
+
+
+def _parse_ratio_id(ratio_id: str) -> Ratio:
+    try:
+        return Ratio(ratio_id)
+    except ValueError as exc:
+        raise typer.BadParameter(f"Invalid ratio ID: {ratio_id}") from exc
+
+
+@preset_app.async_command("apply")  # type: ignore
+async def preset_apply(
+    ratio_id: Annotated[str, typer.Argument(help="3-digit ratio ID, e.g. '235' for 2.35:1")],
+) -> None:
+    """Move motors to the designated ratio preset."""
+    ratio = _parse_ratio_id(ratio_id)
+    async with _get_client() as client:
+        await client.move_to_ratio(ratio)
+
+
+@preset_app.async_command("list")  # type: ignore
+async def preset_list() -> None:
+    """List all stored ratio presets."""
+    async with _get_client() as client:
+        settings = await client.get_ratio_settings()
+        for preset in settings:
+            rprint(preset)
+
+
+@preset_app.async_command("reset")  # type: ignore
+async def preset_reset(
+    ratio_id: Annotated[
+        str | None,
+        typer.Argument(help="3-digit ratio ID, e.g. '235' for 2.35:1.  Default: ALL PRESETS"),
+    ] = None,
+) -> None:
+    """Restore the given ratio preset(s) to their factory default."""
+    ratio = _parse_ratio_id(ratio_id) if ratio_id else None
+    ratio_text = ratio if ratio else "ALL PRESETS"
+    typer.confirm(f"Are you sure you want to reset {ratio_text} to factory default?", abort=True)
+    async with _get_client() as client:
+        await client.reset_factory_default(ratio)
+
+
+@preset_app.async_command("store")  # type: ignore
+async def preset_store(
+    ratio_id: Annotated[str, typer.Argument(help="3-digit ratio ID, e.g. '235' for 2.35:1")],
+) -> None:
+    """Store the current motor positions as the designated ratio preset."""
+    ratio = _parse_ratio_id(ratio_id)
+    async with _get_client() as client:
+        await client.update_ratio(ratio)
+
+
+system_app = AsyncTyper(help="Commands for reading system internals.")
+app.add_typer(system_app, name="system")
+
+
+@system_app.async_command("info")  # type: ignore
+async def system_info() -> None:
+    """Show static information about the Seymour screen system."""
+    async with _get_client() as client:
+        info = await client.get_system_info()
+        for key, value in attrs.asdict(info).items():
+            rprint(f"[bold yellow]{key}[/bold yellow]: {value}")
+
+
+@system_app.async_command()  # type: ignore
+async def diagnostics(option: DiagnosticOption) -> None:
+    """Show diagnostic information from the Seymour screen system."""
+    async with _get_client() as client:
+        diag = await client.get_diagnostics(option)
+        rprint(diag)
+
+
+def main() -> None:
+    app()

seymourlib/client.py

@@ -0,0 +1,270 @@
+"""Main async client for interacting with the Seymour controller."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from tenacity import (
+    AsyncRetrying,
+    after_log,
+    before_sleep_log,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from . import protocol
+from .exceptions import SeymourConnectionError, SeymourProtocolError, SeymourTransportError
+from .transport import SeymourTransport
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_REQUEST_TIMEOUT = 10.0
+HEALTH_CHECK_INTERVAL = 90.0
+HEALTH_CHECK_TIMEOUT = 3.0
+
+
+class SeymourClient:
+    def __init__(
+        self,
+        transport: SeymourTransport,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ):
+        self.transport = transport
+        self._lock = asyncio.Lock()
+        self._connected = False
+        self.max_retries = max_retries
+        self.request_timeout = request_timeout
+        self._last_successful_operation = 0.0
+        self._health_check_task: asyncio.Task[None] | None = None
+
+    async def _connect_with_retry(self) -> None:
+        """Connect with tenacity-managed retry logic."""
+        retryer = AsyncRetrying(
+            stop=stop_after_attempt(self.max_retries),
+            wait=wait_exponential(multiplier=1, min=1, max=30),
+            retry=retry_if_exception_type((SeymourTransportError, ConnectionError, OSError)),
+            before_sleep=before_sleep_log(_LOGGER, logging.WARNING),
+            after=after_log(_LOGGER, logging.INFO),
+        )
+
+        async for attempt in retryer:
+            with attempt:
+                await self.transport.connect()
+                self._connected = True
+                self._last_successful_operation = time.time()
+
+    async def connect(self) -> None:
+        async with self._lock:
+            if self._connected:
+                return
+
+            try:
+                await self._connect_with_retry()
+            except Exception as exc:
+                self._connected = False
+                raise SeymourConnectionError("Failed to connect after all retries") from exc
+
+    async def close(self) -> None:
+        async with self._lock:
+            # Stop health checking
+            if self._health_check_task and not self._health_check_task.done():
+                self._health_check_task.cancel()
+                try:
+                    await self._health_check_task
+                except asyncio.CancelledError:
+                    pass
+                self._health_check_task = None
+
+            # Close transport
+            if self._connected:
+                await self.transport.close()
+                self._connected = False
+                _LOGGER.info("Closed Seymour transport")
+
+    async def start_health_monitoring(self, interval: float = HEALTH_CHECK_INTERVAL) -> None:
+        """Start background health monitoring for long-running applications like Home Assistant."""
+        if self._health_check_task and not self._health_check_task.done():
+            return  # Already running
+
+        self._health_check_task = asyncio.create_task(self._health_check_loop(interval))
+        _LOGGER.info("Started health monitoring (interval=%.1fs)", interval)
+
+    async def _health_check_loop(self, interval: float) -> None:
+        """Background task that periodically checks connection health."""
+        while True:
+            try:
+                await asyncio.sleep(interval)
+
+                # Skip health check if we've had recent successful operations
+                if time.time() - self._last_successful_operation < interval / 2:
+                    continue
+
+                # Perform lightweight health check
+                if self._connected:
+                    try:
+                        await self._health_check()
+                        _LOGGER.debug("Health check passed")
+                    except Exception as exc:
+                        _LOGGER.warning("Health check failed, marking disconnected: %s", exc)
+                        self._connected = False
+
+            except asyncio.CancelledError:
+                _LOGGER.debug("Health monitoring cancelled")
+                break
+            except Exception as exc:
+                _LOGGER.error("Unexpected error in health monitoring: %s", exc)
+                await asyncio.sleep(interval)  # Continue monitoring despite errors
+
+    async def _health_check(self) -> None:
+        """Perform a lightweight health check by requesting status."""
+        # Use a shorter timeout for health checks
+        original_timeout = self.request_timeout
+        self.request_timeout = min(HEALTH_CHECK_TIMEOUT, original_timeout)
+        try:
+            await self.get_status()
+        finally:
+            self.request_timeout = original_timeout
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if the client believes it's connected."""
+        return self._connected
+
+    @property
+    def connection_stats(self) -> dict[str, float]:
+        """Get connection statistics for monitoring."""
+        return {
+            "last_successful_operation": self._last_successful_operation,
+            "time_since_last_success": (
+                time.time() - self._last_successful_operation
+                if self._last_successful_operation > 0
+                else -1
+            ),
+        }
+
+    async def __aenter__(self) -> SeymourClient:
+        """Async context manager entry."""
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object | None,
+    ) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    async def _execute_operation(self, frame: bytes, receive: bool = True) -> bytes | None:
+        """Execute a single transport operation with retry logic."""
+        retryer = AsyncRetrying(
+            stop=stop_after_attempt(self.max_retries),
+            wait=wait_exponential(multiplier=0.5, min=0.5, max=10),
+            retry=retry_if_exception_type(
+                (SeymourTransportError, TimeoutError, ConnectionError, OSError)
+            ),
+            before_sleep=before_sleep_log(_LOGGER, logging.WARNING),
+        )
+
+        async for attempt in retryer:
+            with attempt:
+                # Ensure connection before operation
+                if not self._connected:
+                    await self.connect()
+
+                # Execute with timeout
+                async with asyncio.timeout(self.request_timeout):
+                    await self.transport.send(frame)
+                    if receive:
+                        response = await self.transport.receive()
+                        self._last_successful_operation = time.time()
+                        return response
+                    else:
+                        self._last_successful_operation = time.time()
+                        return None
+
+        # This should never be reached due to retry logic, but satisfy type checker
+        return None
+
+    async def _send_and_maybe_receive(self, frame: bytes, receive: bool = True) -> bytes | None:
+        """Send frame and optionally receive response with automatic reconnection."""
+        try:
+            logging.debug("Sending frame: %s", frame)
+            return await self._execute_operation(frame, receive)
+        except Exception as exc:
+            # Mark disconnected for any transport error
+            self._connected = False
+            if isinstance(exc, SeymourTransportError | TimeoutError | ConnectionError | OSError):
+                raise SeymourConnectionError("Transport operation failed after retries") from exc
+            else:
+                raise SeymourProtocolError("Protocol or unexpected error") from exc
+
+    async def _send(self, frame: bytes) -> None:
+        """Low-level: send frame without awaiting reply."""
+        await self._send_and_maybe_receive(frame, receive=False)
+
+    async def _send_and_receive(self, frame: bytes) -> bytes:
+        """Low-level: send frame and await reply frame."""
+        raw = await self._send_and_maybe_receive(frame, receive=True)
+        logging.debug("Received frame: %s", raw)
+        assert raw is not None
+        return raw
+
+    # Public API
+    async def get_status(self) -> protocol.MaskStatus:
+        raw = await self._send_and_receive(protocol.encode_status())
+        return protocol.decode_status(raw)
+
+    async def get_positions(self) -> list[protocol.MaskPosition]:
+        raw = await self._send_and_receive(protocol.encode_positions())
+        return protocol.decode_positions(raw)
+
+    async def get_system_info(self) -> protocol.SystemInfo:
+        raw = await self._send_and_receive(protocol.encode_read_sysinfo())
+        return protocol.decode_system_info(raw)
+
+    async def get_ratio_settings(self) -> list[protocol.RatioSetting]:
+        raw = await self._send_and_receive(protocol.encode_read_settings())
+        return protocol.decode_settings(raw)
+
+    async def get_diagnostics(self, option: protocol.DiagnosticOption) -> str:
+        raw = await self._send_and_receive(protocol.encode_diagnostics(option))
+        return raw.decode("ascii")
+
+    async def move_out(self, motor: protocol.MotorID, movement: protocol.MovementCode) -> None:
+        frame = protocol.encode_move_out(motor, movement)
+        await self._send(frame)
+
+    async def move_in(self, motor: protocol.MotorID, movement: protocol.MovementCode) -> None:
+        frame = protocol.encode_move_in(motor, movement)
+        await self._send(frame)
+
+    async def move_to_ratio(self, ratio: protocol.Ratio) -> None:
+        frame = protocol.encode_move_ratio(ratio)
+        await self._send(frame)
+
+    async def home(self, motor: protocol.MotorID) -> None:
+        frame = protocol.encode_home(motor)
+        await self._send(frame)
+
+    async def halt(self, motor: protocol.MotorID) -> None:
+        frame = protocol.encode_halt(motor)
+        await self._send(frame)
+
+    async def calibrate(self, motor: protocol.MotorID) -> None:
+        frame = protocol.encode_calibrate(motor)
+        await self._send(frame)
+
+    async def update_ratio(self, ratio: protocol.Ratio) -> None:
+        frame = protocol.encode_update_ratio(ratio)
+        await self._send(frame)
+
+    async def reset_factory_default(self, ratio: protocol.Ratio | None) -> None:
+        frame = protocol.encode_clear_settings(ratio)
+        await self._send(frame)

seymourlib/exceptions.py

@@ -0,0 +1,14 @@
+class SeymourError(Exception):
+    pass
+
+
+class SeymourConnectionError(SeymourError):
+    pass
+
+
+class SeymourProtocolError(SeymourError):
+    pass
+
+
+class SeymourTransportError(Exception):
+    pass

seymourlib/protocol.py

@@ -0,0 +1,388 @@
+"""
+Implementation for the Seymour RS232 protocol version 01.
+"""
+
+from __future__ import annotations
+
+import enum
+import re
+
+import attrs
+
+FRAME_START = b"["
+FRAME_END = b"]"
+PROTOCOL_VERSION = b"01"
+
+
+class SingleByte(enum.StrEnum):
+    """
+    Base class for enums that represent a 1-byte code.
+    """
+
+    @classmethod
+    def regex(cls, n: int | None = None) -> bytes:
+        """
+        Regular expression that parses exactly one code value into a capture group named after the class.
+        """
+        all_commands = "".join(code.value for code in cls)
+        capture_group_suffix = str(n) if n is not None else ""
+        return rf"(?P<{cls.__name__}{capture_group_suffix}>[{all_commands}])".encode("ascii")
+
+
+class CommandCode(SingleByte):
+    MOVE_OUT = "O"
+    MOVE_IN = "I"
+    MOVE_TO_RATIO = "M"
+    HOME = "A"
+    HALT = "H"
+    CALIBRATE = "C"
+    STATUS = "S"
+    POSITIONS = "P"
+    UPDATE_RATIO = "U"
+    READ_SYSTEM_INFO = "Y"
+    READ_SETTINGS = "R"
+    CLEAR_SETTINGS = "X"
+    DIAGNOSTICS = "@"
+
+
+class MotorID(SingleByte):
+    TOP = "T"
+    BOTTOM = "B"
+    LEFT = "L"
+    RIGHT = "R"
+    VERTICAL = "V"
+    HORIZONTAL = "H"
+    ALL = "A"
+
+
+class MovementCode(enum.StrEnum):
+    UNTIL_LIMIT = ""
+    JOG = "J"  # smallest increment (<0.1%)
+    MOVE = "M"  # 1% of the motor's range (ignored if not calibrated)
+
+
+class StatusCode(SingleByte):
+    STOPPED_AT_RATIO = "P"
+    MOVING_TO_RATIO = "M"
+    HALTED = "H"
+    HOMING = "A"
+    CALIBRATING = "C"
+    MOVING_OUTWARD = "O"
+    MOVING_INWARD = "I"
+    ERROR = "E"
+
+
+@attrs.frozen
+class Ratio:
+    id: str = attrs.field()
+
+    @id.validator
+    def check(self, _attribute: attrs.Attribute[str], value: str) -> None:
+        if len(value) != 3:
+            raise ValueError("ratio_id must be three digits long")
+        if not value.isdigit():
+            raise ValueError("ratio_id must be numeric")
+
+    @classmethod
+    def regex(cls) -> bytes:
+        """
+        Regular expression that parses a ratio ID into a capture group named 'Ratio'.
+        """
+        return rb"(?P<Ratio>[0-9]{3})"
+
+
+@attrs.frozen
+class MaskStatus:
+    code: StatusCode
+    ratio: Ratio | None = None
+
+
+@attrs.frozen
+class MaskPosition:
+    motor_id: MotorID
+    position_pct: float
+
+
+@attrs.frozen
+class Serial:
+    model_code: str
+    month: int
+    year: int
+    production_number: str
+
+    def to_serial_number(self) -> str:
+        return f"{self.model_code}-{self.month:02d}{self.year:02d}-{self.production_number}"
+
+    PARSER_RE = re.compile(
+        rb"(?P<model_code>.{2})-(?P<month>[0-9]{2})(?P<year>[0-9]{2})-(?P<production_number>.{5})"
+    )
+
+    @staticmethod
+    def from_serial_number(serial_number: bytes) -> Serial:
+        """
+        Parse a serial number bytestring into a Serial object.
+
+        The expected format is "XX-MMYY-PPPPP", where XX is the model code and PPPPP is the
+        production number. The hyphens are required.
+        """
+        match = Serial.PARSER_RE.fullmatch(serial_number)
+        if not match:
+            raise ValueError(f"Malformed serial number: {serial_number!r}")
+
+        model_code = match.group("model_code").decode("ascii")
+        month = int(match.group("month"))
+        year = int(match.group("year"))
+        production_number = match.group("production_number").decode("ascii")
+        return Serial(
+            model_code=model_code,
+            month=month,
+            year=year,
+            production_number=production_number,
+        )
+
+
+@attrs.frozen
+class SystemInfo:
+    screen_model: str
+    width_inches: float
+    height_inches: float
+    serial_number: Serial
+    mask_ids: list[MotorID]
+
+
+@attrs.frozen
+class RatioSetting:
+    ratio: Ratio
+    label: str
+    width_inches: float
+    height_inches: float
+    motor_positions_pct: list[float]
+    motor_adjustments_pct: list[float]
+
+    @staticmethod
+    def from_response_entry(entry: bytes, num_motors: int) -> RatioSetting:
+        """
+        Parse a ratio setting info string into a RatioSetting object.
+
+        The expected format is:
+        - 3 bytes: ratio ID
+        - 8 bytes: label (ASCII, space-padded)
+        - 6 bytes: width in inches (ASCII float)
+        - 6 bytes: height in inches (ASCII float)
+        - For each motor:
+          - 4 bytes: position percentage (ASCII float)
+        - For each motor:
+          - 4 bytes: position adjustment percentage (ASCII float)
+        """
+        base_pattern = Ratio.regex() + rb"(?P<label>.{8})(?P<width>[0-9.]{6})(?P<height>[0-9.]{6})"
+
+        pattern = base_pattern + _ASCII_PCT_RE * num_motors * 2
+
+        match = re.fullmatch(pattern, entry)
+        if not match:
+            raise ValueError(f"Malformed ratio setting entry for pattern {pattern!r}: {entry!r}")
+
+        ratio_id = match.group("Ratio").decode("ascii")
+        label = match.group("label").decode("ascii").strip()
+        width = float(match.group("width"))
+        height = float(match.group("height"))
+
+        # parse the motor positions and adjustments
+        motor_positions_pct: list[float] = []
+        motor_adjustments_pct: list[float] = []
+        position_group_start = 5  # after ratio, label, width, height
+        for i in range(num_motors):
+            pos_str = match.group(position_group_start + i)
+            adj_str = match.group(position_group_start + num_motors + i)
+            motor_positions_pct.append(float(pos_str))
+            motor_adjustments_pct.append(float(adj_str))
+
+        return RatioSetting(
+            ratio=Ratio(ratio_id),
+            label=label,
+            width_inches=width,
+            height_inches=height,
+            motor_positions_pct=motor_positions_pct,
+            motor_adjustments_pct=motor_adjustments_pct,
+        )
+
+    @staticmethod
+    def expected_entry_length(num_motors: int) -> int:
+        """
+        Calculate the expected length of a ratio setting entry for the given number of motors.
+        """
+        # 3 (ratio ID) + 8 (label) + 6 (width) + 6 (height) + N * 4 (positions) + N * 4 (adjustments)
+        return 3 + 8 + 6 + 6 + num_motors * 4 + num_motors * 4
+
+
+class DiagnosticCommand(SingleByte):
+    DEBUG_LOG = "D"
+
+
+class DiagnosticOption(enum.StrEnum):
+    LIST_FS = "00"
+    LIST_SETTINGS_JSON = "10"
+    LIST_SYSTEM_JSON = "20"
+
+
+def _frame(payload: str) -> bytes:
+    return FRAME_START + PROTOCOL_VERSION + payload.encode("ascii") + FRAME_END
+
+
+def encode_move_out(motor_id: MotorID, movement: MovementCode) -> bytes:
+    return _frame(f"{CommandCode.MOVE_OUT}{motor_id}{movement}")
+
+
+def encode_move_in(motor_id: MotorID, movement: MovementCode) -> bytes:
+    return _frame(f"{CommandCode.MOVE_IN}{motor_id}{movement}")
+
+
+def encode_move_ratio(ratio: Ratio) -> bytes:
+    return _frame(f"{CommandCode.MOVE_TO_RATIO}{ratio.id}")
+
+
+def encode_home(motor_id: MotorID) -> bytes:
+    return _frame(f"{CommandCode.HOME}{motor_id}")
+
+
+def encode_halt(motor_id: MotorID) -> bytes:
+    return _frame(f"{CommandCode.HALT}{motor_id}")
+
+
+def encode_calibrate(motor_id: MotorID) -> bytes:
+    return _frame(f"{CommandCode.CALIBRATE}{motor_id}")
+
+
+def encode_status() -> bytes:
+    return _frame(CommandCode.STATUS)
+
+
+def encode_positions() -> bytes:
+    return _frame(CommandCode.POSITIONS)
+
+
+def encode_update_ratio(ratio: Ratio) -> bytes:
+    return _frame(f"{CommandCode.UPDATE_RATIO}{ratio.id}")
+
+
+def encode_clear_settings(ratio: Ratio | None) -> bytes:
+    id = ratio.id if ratio is not None else ""
+    return _frame(f"{CommandCode.CLEAR_SETTINGS}{id}")
+
+
+def encode_read_sysinfo() -> bytes:
+    return _frame(CommandCode.READ_SYSTEM_INFO)
+
+
+def encode_read_settings() -> bytes:
+    return _frame(CommandCode.READ_SETTINGS)
+
+
+def encode_diagnostics(option: DiagnosticOption) -> bytes:
+    return _frame(f"{CommandCode.DIAGNOSTICS}{DiagnosticCommand.DEBUG_LOG}{option}")
+
+
+def _frame_re(regex_body: bytes) -> re.Pattern[bytes]:
+    regex = b"^\\" + FRAME_START + PROTOCOL_VERSION + regex_body + b"\\" + FRAME_END + b"$"
+    return re.compile(regex)
+
+
+_STATUS_RE = _frame_re(StatusCode.regex() + Ratio.regex() + rb"?")
+
+
+def decode_status(raw: bytes) -> MaskStatus:
+    match = _STATUS_RE.match(raw)
+    if not match:
+        raise ValueError(f"Malformed status response: {raw!r}")
+    status_code = match.group("StatusCode").decode("ascii")
+    maybe_ratio_str = match.group("Ratio")
+    ratio = Ratio(maybe_ratio_str.decode("ascii")) if maybe_ratio_str is not None else None
+    return MaskStatus(code=StatusCode(status_code), ratio=ratio)
+
+
+_POSITIONS_RE = _frame_re(rb"(?P<num_motors>[1-4])(?P<entries>.+)")
+_ASCII_PCT_RE = rb"([0-9.\-]{4})"
+
+
+def decode_positions(raw: bytes) -> list[MaskPosition]:
+    match = _POSITIONS_RE.match(raw)
+    if not match:
+        raise ValueError(f"Malformed positions response: {raw!r}")
+    num_motors = int(match.group("num_motors"))
+    entries_str = match.group("entries")
+
+    pattern = b"".join(MotorID.regex(i) + _ASCII_PCT_RE for i in range(num_motors))
+    match = re.fullmatch(pattern, entries_str)
+    if not match:
+        raise ValueError(f"Malformed motor position entries: {entries_str!r}")
+    if len(match.groups()) != num_motors * 2:
+        raise ValueError(f"Expected {num_motors} motor entries, got: {entries_str!r}")
+    positions: list[MaskPosition] = []
+    for i in range(num_motors):
+        motor_id_str = match.group(1 + i * 2).decode("ascii")
+        position_str = match.group(2 + i * 2).decode("ascii")
+        positions.append(
+            MaskPosition(
+                motor_id=MotorID(motor_id_str),
+                position_pct=float(position_str),
+            )
+        )
+    return positions
+
+
+_SYSTEM_INFO_RE = _frame_re(
+    rb"(?P<model>.{20})(?P<width>[0-9.]{6})(?P<height>[0-9.]{6})(?P<serial>.{13})(?P<mask_ids>[LRTB]{1,5})"
+)
+
+
+def decode_system_info(raw: bytes) -> SystemInfo:
+    match = _SYSTEM_INFO_RE.match(raw)
+    if not match:
+        raise ValueError(f"Malformed system info response: {raw!r}")
+    model = match.group("model").decode("ascii").strip()
+
+    width = float(match.group("width"))
+    height = float(match.group("height"))
+
+    serial_str = match.group("serial")
+    serial = Serial.from_serial_number(serial_str)
+
+    mask_ids_str = match.group("mask_ids").decode("ascii")
+    mask_ids = [MotorID(c) for c in mask_ids_str]
+
+    return SystemInfo(
+        screen_model=model,
+        width_inches=width,
+        height_inches=height,
+        serial_number=serial,
+        mask_ids=mask_ids,
+    )
+
+
+_SETTINGS_RE = _frame_re(rb"(?P<num_motors>[0-9])(?P<num_ratios>[0-9]{2})(?P<entries>.+)")
+
+
+def decode_settings(raw: bytes) -> list[RatioSetting]:
+    match = _SETTINGS_RE.match(raw)
+    if not match:
+        raise ValueError(f"Malformed settings response: {raw!r}")
+    num_motors = int(match.group("num_motors"))
+    num_ratios = int(match.group("num_ratios"))
+    entries_str = match.group("entries")
+
+    expected_length_per_entry = RatioSetting.expected_entry_length(num_motors)
+    if len(entries_str) != expected_length_per_entry * num_ratios:
+        raise ValueError(
+            f"Expected {num_ratios} ratio entries of length {expected_length_per_entry}, "
+            f"got total length {len(entries_str)}: {entries_str!r}"
+        )
+
+    settings: list[RatioSetting] = []
+    for i in range(num_ratios):
+        entry_bytes = entries_str[
+            i * expected_length_per_entry : (i + 1) * expected_length_per_entry
+        ]
+        setting = RatioSetting.from_response_entry(entry_bytes, num_motors)
+        settings.append(setting)
+
+    return settings

seymourlib/transport.py

@@ -0,0 +1,87 @@
+"""Transport abstraction: TCPTransport (for IP2SL) + SerialTransport (local serial)."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import abstractmethod
+
+from .exceptions import SeymourTransportError
+
+SEYMOUR_BAUD_RATE = 115200
+ITACH_SERIAL_PORT = 4999
+
+
+class SeymourTransport:
+    """Abstract transport used by the SeymourClient."""
+
+    def __init__(self) -> None:
+        self.reader: asyncio.StreamReader | None = None
+        self.writer: asyncio.StreamWriter | None = None
+        self._lock = asyncio.Lock()
+
+    @abstractmethod
+    async def connect(self) -> None:
+        raise NotImplementedError
+
+    async def close(self) -> None:
+        try:
+            if self.writer:
+                self.writer.close()
+                await self.writer.wait_closed()
+        finally:
+            self.writer = None
+            self.reader = None
+
+    async def send(self, data: bytes) -> None:
+        """Send one data frame to transport, blocking until the complete frame is sent."""
+        assert data.startswith(b"["), "Frame must start with '['"
+        assert data.endswith(b"]"), "Frame must end with ']'"
+
+        if not self.writer:
+            raise SeymourTransportError("Not connected")
+
+        async with self._lock:
+            self.writer.write(data)
+            await self.writer.drain()
+
+    async def receive(self) -> bytes:
+        """
+        Get one data frame from transport, blocking until frame end (']') is received.
+
+        Note: no timeout here; caller should use structured concurrency if desired.
+        """
+        if not self.reader:
+            raise SeymourTransportError("Not connected")
+
+        try:
+            data = await asyncio.wait_for(self.reader.readuntil(b"]"), timeout=None)
+            return data
+        except asyncio.IncompleteReadError as exc:
+            raise SeymourTransportError("Connection closed") from exc
+
+
+class TCPTransport(SeymourTransport):
+    def __init__(self, host: str, port: int = ITACH_SERIAL_PORT) -> None:
+        super().__init__()
+        self.host = host
+        self.port = port
+
+    async def connect(self) -> None:
+        self.reader, self.writer = await asyncio.open_connection(self.host, self.port)
+
+
+class SerialTransport(SeymourTransport):
+    def __init__(self, port: str, baudrate: int = SEYMOUR_BAUD_RATE) -> None:
+        super().__init__()
+        self.port = port
+        self.baudrate = baudrate
+
+    async def connect(self) -> None:
+        try:
+            import serial_asyncio
+        except Exception as exc:
+            raise SeymourTransportError("serial_asyncio not installed") from exc
+
+        self.reader, self.writer = await serial_asyncio.open_serial_connection(
+            url=self.port, baudrate=self.baudrate
+        )

seymourlib-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: seymourlib
+Version: 0.1.0
+Summary: Python client for Seymour masking screens, connected via direct serial or Global Caché iTach IP2SL
+Author-email: Richard Berg <ars@richardberg.net>
+License-Expression: MIT
+Project-URL: omepage, https://github.com/richard-berg/seymourlib
+Project-URL: source, https://github.com/richard-berg/seymourlib.git
+Project-URL: issues, https://github.com/richard-berg/seymourlib/issues
+Keywords: seymour,masking,screen,serial,itach,ip2sl,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anyio>=3.4
+Requires-Dist: attrs>=25.4.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: async-typer>=0.1.10
+Provides-Extra: serial
+Requires-Dist: pyserial_asyncio>=0.6; extra == "serial"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: pyserial_asyncio>=0.6; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-timeout>=2; extra == "test"
+Requires-Dist: coverage>=7; extra == "test"
+Requires-Dist: pyserial_asyncio>=0.6; extra == "test"
+Dynamic: license-file
+
+# seymourlib
+
+[![CI](https://img.shields.io/github/actions/workflow/status/richard-berg/seymourlib/ci.yml?label=CI&logo=github)](https://github.com/richard-berg/seymourlib/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/richard-berg/seymourlib?logo=codecov)](https://codecov.io/gh/richard-berg/seymourlib)
+[![PyPI](https://img.shields.io/pypi/v/seymourlib?logo=pypi)](https://pypi.org/project/seymourlib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Python client for Seymour masking screens, connected via direct serial or Global Caché iTach IP2SL. Built for rock-solid control loops, [Home Assistant](https://www.home-assistant.io/) integrations, and quick bench testing. 😎
+
+---
+
+## Highlights
+
+- Async-first client and transport abstractions (TCP/IP2SL vs native serial) with consistent APIs.
+- Protocol helpers that mirror the official Seymour RS232 spec, including parsing/validation utilities.
+- `seymourctl` CLI for one-off commands, scripting, and smoke tests in CI.
+- Batteries-included retry logic (`tenacity`), timeout handling, and graceful cancellation via `anyio`.
+
+## Architecture at a Glance
+
+```mermaid
+flowchart TB
+     App[Your automation / HA stack] -->|async API| Client[SeymourClient]
+     Client --> Protocol[Protocol helpers]
+     Client --> Transport
+     Transport -->|TCP 4999| IP2SL[Global Caché IP2SL]
+     Transport -->|RS232| Screen[Seymour Masking Screen]
+     IP2SL -->|RS232| Screen
+```
+
+## Installation
+
+### Requirements
+
+- Python 3.11+
+- `uv` >= 0.2 (recommended) or classic `pip`
+
+### Using uv (dev + extras)
+
+```bash
+uv sync --all-extras
+```
+
+### Using pip (runtime only)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install "seymourlib[serial]"
+```
+
+> 💡 The optional `serial` extra pulls in `pyserial-asyncio` so the same client works over USB/RS232 without the IP bridge.
+
+---
+
+## First-Time Setup Checklist
+
+1. **Clone & bootstrap**
+    - `git clone https://github.com/richard-berg/seymourlib && cd seymourlib`
+    - `uv sync --all-extras`
+2. **Sanity-test the library**
+    - `uv run pytest` for local regression.
+    - `uv run seymourctl -v status` to hit your target once hardware is reachable.
+3. **Wire up hardware**
+    - Confirm straight-through RS232 between IP2SL and the Seymour control port.
+    - For direct USB serial, a FTDI-based adapter keeps timing stable.
+4. **Pick your transport**
+    - `TCPTransport(host, port=4999)` for IP2SL.
+    - `SerialTransport(port="COM5")` for direct connection (requires `[serial]`).
+
+---
+
+## Usage Examples
+
+### Python API
+
+```python
+import asyncio
+from seymourlib.client import SeymourClient
+from seymourlib.transport import TCPTransport
+
+async def main() -> None:
+     async with SeymourClient(TCPTransport("192.168.1.70")) as client:
+          status = await client.get_status()
+          print(status)
+
+asyncio.run(main())
+```
+
+### CLI
+
+```bash
+uv run seymourctl --host 192.168.1.70 status
+uv run seymourctl --host 192.168.1.70 preset apply 235
+uv run seymourctl --help
+```
+
+---
+
+## IP2SL Setup & Diagnostics
+
+### 1. Test direct serial first
+
+- Connect a laptop directly to the Seymour RS232 port with a known-good USB adapter.
+- Use `RealTerm`, `CoolTerm`, or any tty tool (115200 8N1 by default - verify via Seymour docs) to send a `PS?` (position status) command.
+- Once commands succeed locally, you know the projector + cable + command syntax are correct before adding the network hop.
+
+### 2. Discover the IP2SL via iHelp
+
+- Download [Global Caché iHelp](https://www.globalcache.com/files/software/iHelp.zip) and run it on the same subnet.
+- Press **Scan** to locate the IP2SL; note the MAC, firmware, and current IP.
+- If nothing shows up, temporarily disable host firewalls or plug directly into a laptop + small DHCP scope.
+
+### 3. Pin the network configuration
+
+- Point a browser at `http://<your-ip>/` (from step 2) if you want a point-and-click GUI for DHCP/static IP, firmware, and reboot controls.
+- Otherwise, install [Global Caché iTest](https://www.globalcache.com/files/software/iTest.zip).
+  - Use iTest or telnet into port **4998** (the configuration/control port).
+  - Send `set dhcp 0`, `set ip <static>`, `set mask <subnet>`, `set gateway <gw>`, then `save` to burn settings.
+- Reboot (power cycle or `reboot` command) and confirm the device responds on the static IP.
+- Document the MAC/IP in your DHCP reservations to avoid future collisions.
+
+### 4. Lock the serial parameters
+
+- Open the IP2SL web UI and switch to the **Serial** tab, or telnet/iTest into port **4998** for command-line configuration.
+- Ensure the port is set to **115200 baud, 8 data bits, no parity, 1 stop bit** to match Seymour’s RS232 spec.
+- Saving via the UI writes immediately; if you used the control port, run `set baud 115200`, `set data 8`, `set parity 0`, `set stop 1`, then `save` and reboot so the bridge always boots with the correct framing.
+
+### 5. Exercise the serial bridge with iTest
+
+- Open iTest (or `telnet`)
+- Target port **4999** on the static IP, choose **RAW** mode, and click **Connect**.
+- Send a few simple commands (e.g. `[01S]`, `[01P]`). The response should echo immediately.
+- If latency creeps in, verify telnet keep-alives/device busy LEDs. Keep the window open while you walk through automation flows to watch the live traffic.
+
+### 6. Promote to seymourlib
+
+- Update your `.env` / config with the same host/port verified above.
+- Start with `uv run seymourctl -v status` (verbose logging shows full request/response frames).
+- Flip to automation ([Home Assistant](https://www.home-assistant.io/), Homebridge, etc.) once CLI calls are boringly reliable.
+
+---
+
+## Troubleshooting & Field Notes
+
+- ⚡ **No response over TCP but serial works** - Ensure port 4999 is open on local firewalls and that the IP2SL LED blinks on connect; if not, recheck the static IP settings from step 3.
+- 🔌 **Commands hang after a day** - The IP2SL can queue stale sockets; send `set rs232disconnect 1` over port 4998 so idle TCP clients auto-close.
+- 🔁 **Race conditions from HA automations** - Wrap your automations with seymourlib's async context manager so only one command pipeline exists per transport.
+- 🧪 **Need deeper diagnostics** - Add `--verbose` to `seymourctl` to dump protocol frames, or [enable debug logging](https://docs.python.org/3/library/logging.html) to capture per-request timestamps.
+- 🛠️ **Firmware drift** - Global Caché publishes release notes; mismatched firmware sometimes defaults back to DHCP on reboot. Always export a config snapshot in iHelp after upgrades.
+
+---
+
+## Related Docs & Inspiration
+
+- [Seymour Screen Excellence RS232 Protocol PDF](https://www.seymourscreenexcellence.com/) (request via dealer portal).
+- [Global Caché Knowledge Base](https://globalcache.zendesk.com/).
+- [Home Assistant Template Switch Cookbook](https://www.home-assistant.io/integrations/template/) for inspiration on wiring seymourlib into HA.
+- [CoolTerm Serial Terminal](https://freeware.the-meiers.org/) - handy for the direct-serial smoke test.
+
+---
+
+## Contributing
+
+- Fork, create a feature branch, and open a PR (tests + type checks 🚦 required).
+- `pre-commit run` before pushing.
+- Issues and hardware findings are welcome - real-world serial logs are gold for regression tests.
+
+Need something else? Open a discussion or ping via Issues and we’ll figure it out together. 🙌

seymourlib-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+seymourlib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+seymourlib/cli.py,sha256=2sNzNukIZ8GA_kZ2IZKgeGF6nxPFVGp1C_YHLxyzEw4,7714
+seymourlib/client.py,sha256=WyNxGKotXgwvj-K1m5101_rHfg40pTrC4S-LMFrhAR4,10520
+seymourlib/exceptions.py,sha256=JQYPKsZbZwQBnb-rqbsyz7EXbIE7KGPMYaaiOM0LaR0,199
+seymourlib/protocol.py,sha256=UclH9n6-9-XkywZCDh8efmj8jnEudEELlq1iGJIf4GU,11483
+seymourlib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+seymourlib/transport.py,sha256=fKOQygWm0m5bNTdMJL_hWX6W6yT9aAQ-SY82sl2t9dI,2751
+seymourlib-0.1.0.dist-info/licenses/LICENSE,sha256=cgMk0mtLXy8D5VnPG7la5aC7X6qYqMWAEFIRMlE56V8,1089
+seymourlib-0.1.0.dist-info/METADATA,sha256=J6O5lCXpazMdlyVQbTWVpUXv0dpwdHZbRKX2XDTR8aM,9564
+seymourlib-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+seymourlib-0.1.0.dist-info/entry_points.txt,sha256=CSBM6mD3Ooa3QJ7tZBWmnyN19IRHyJTwZ8jsUcrhHjE,51
+seymourlib-0.1.0.dist-info/top_level.txt,sha256=ScOirVLXTyJ1kjsC_7coaFFJvlHsDETK76Wpysw3CIg,11
+seymourlib-0.1.0.dist-info/RECORD,,

seymourlib-0.1.0.dist-info/WHEEL

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

seymourlib-0.1.0.dist-info/entry_points.txt

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

seymourlib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Richard Berg
+
+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.

seymourlib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+seymourlib