educelab-devices 0.1.0__py3-none-any.whl

educelab/devices/__init__.py

@@ -0,0 +1,25 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from educelab.devices.device import (
+    Device,
+    DeviceEvent,
+    DeviceInfo,
+    Disconnected,
+    Listener,
+    synchronized,
+)
+
+__all__ = [
+    "Device",
+    "DeviceEvent",
+    "DeviceInfo",
+    "Disconnected",
+    "Listener",
+    "__version__",
+    "synchronized",
+]
+
+try:
+    __version__ = version("educelab-devices")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

educelab/devices/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from educelab.devices.app.cli import main
+
+sys.exit(main())

educelab/devices/_serial.py

@@ -0,0 +1,310 @@
+"""Serial transport shared by the lab's serial drivers (MISHA, XLC, X-Carve).
+
+Internal: drivers build on it, consumers don't. pyserial is imported only
+when a port is listed or opened.
+"""
+
+import logging
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from educelab.devices.errors import (
+    DeviceNotFound,
+    DeviceTimeout,
+    NotConnected,
+    import_optional,
+)
+
+__all__ = [
+    "PortInfo",
+    "PortMatch",
+    "SerialTransport",
+    "find_ports",
+    "handshake",
+    "list_ports",
+]
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# Opens a port and returns an object with the parts of serial.Serial's API the
+# transport uses. Tests pass one that returns a fake.
+Opener = Callable[[str, int, float], Any]
+
+
+@dataclass(frozen=True)
+class PortInfo:
+    """A serial port as the host's USB stack describes it.
+
+    Attributes:
+        device: The name to open, e.g. ``"COM3"`` or ``"/dev/ttyUSB0"``.
+        vid: USB vendor ID, if the port is a USB device.
+        pid: USB product ID, if the port is a USB device.
+        serial_number: USB serial number, if the device reports one.
+        description: The host's human-readable description of the port.
+    """
+
+    device: str
+    vid: int | None = None
+    pid: int | None = None
+    serial_number: str | None = None
+    description: str | None = None
+
+
+def list_ports() -> list[PortInfo]:
+    """Every serial port on the host.
+
+    Raises:
+        ImportError: pyserial isn't installed.
+    """
+    pyserial_list_ports = import_optional("serial.tools.list_ports", extra="serial")
+    return [
+        PortInfo(
+            device=port.device,
+            vid=port.vid,
+            pid=port.pid,
+            serial_number=port.serial_number,
+            description=port.description,
+        )
+        for port in pyserial_list_ports.comports()
+    ]
+
+
+@dataclass(frozen=True)
+class PortMatch:
+    """Criteria that pick a device's port out of the host's serial ports.
+
+    A port matches only if it meets every criterion given, and criteria that
+    aren't given are ignored. With no criteria at all, nothing matches.
+
+    Attributes:
+        vid: USB vendor ID, or a collection of acceptable IDs.
+        pid: USB product ID, or a collection of acceptable IDs.
+        serial_number: Text the port's serial number must contain, ignoring
+            case.
+        description: Text the port's description must contain, ignoring case.
+    """
+
+    vid: int | Iterable[int] | None = None
+    pid: int | Iterable[int] | None = None
+    serial_number: str | None = None
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("vid", "pid"):
+            value = getattr(self, name)
+            if value is not None and not isinstance(value, int):
+                object.__setattr__(self, name, frozenset(value))
+
+    def matches(self, port: PortInfo) -> bool:
+        """Whether ``port`` meets every criterion given."""
+        checks = [
+            _id_matches(self.vid, port.vid),
+            _id_matches(self.pid, port.pid),
+            _text_matches(self.serial_number, port.serial_number),
+            _text_matches(self.description, port.description),
+        ]
+        given = [check for check in checks if check is not None]
+        return bool(given) and all(given)
+
+    def matching(self, ports: Iterable[PortInfo]) -> list[PortInfo]:
+        """The ports that match, in the order given."""
+        return [port for port in ports if self.matches(port)]
+
+
+def find_ports(match: PortMatch) -> list[PortInfo]:
+    """The host's serial ports that meet ``match``.
+
+    Raises:
+        ImportError: pyserial isn't installed.
+    """
+    return match.matching(list_ports())
+
+
+# Each returns None when the criterion wasn't given.
+def _id_matches(want: int | Iterable[int] | None, have: int | None) -> bool | None:
+    if want is None:
+        return None
+    if have is None:
+        return False
+    return have == want if isinstance(want, int) else have in want
+
+
+def _text_matches(want: str | None, have: str | None) -> bool | None:
+    if want is None:
+        return None
+    return have is not None and want.casefold() in have.casefold()
+
+
+class SerialTransport:
+    """A line-oriented connection to one serial port.
+
+    Lines are ASCII and end with ``\\n`` on the way out; on the way in, the
+    line ending and surrounding whitespace are stripped and blank lines are
+    skipped.
+
+    Args:
+        port: The port to open, e.g. ``"COM3"`` or ``"/dev/ttyUSB0"``.
+        baudrate: Baud rate.
+        timeout: Default time to wait for a line, in seconds.
+        reset_settle: Time to wait after opening, in seconds. Boards that
+            reset when the port opens (DTR) ignore commands until they've
+            booted; output from the boot is discarded.
+        opener: Opens the port. Defaults to pyserial; tests pass a fake.
+    """
+
+    def __init__(
+        self,
+        port: str,
+        *,
+        baudrate: int,
+        timeout: float = 1.0,
+        reset_settle: float = 0.0,
+        opener: Opener | None = None,
+    ) -> None:
+        self.port = port
+        self.baudrate = baudrate
+        self.timeout = timeout
+        self.reset_settle = reset_settle
+        self._opener = opener or _open_pyserial
+        self._conn: Any = None
+        self._partial = b""
+
+    @property
+    def is_open(self) -> bool:
+        return self._conn is not None
+
+    def open(self) -> None:
+        """Open the port and wait for the board to finish resetting.
+
+        Raises:
+            DeviceNotFound: The port couldn't be opened.
+            ImportError: The default opener needs pyserial, which isn't
+                installed.
+        """
+        if self._conn is not None:
+            return
+        try:
+            conn = self._opener(self.port, self.baudrate, self.timeout)
+        except OSError as exc:
+            raise DeviceNotFound(
+                f"could not open serial port {self.port!r}: {exc}"
+            ) from exc
+        self._conn = conn
+        self._partial = b""
+        if self.reset_settle:
+            time.sleep(self.reset_settle)
+        self.reset_input()
+
+    def close(self) -> None:
+        """Close the port. Does nothing if it isn't open."""
+        conn, self._conn = self._conn, None
+        if conn is None:
+            return
+        try:
+            conn.close()
+        except OSError as exc:
+            # The port is gone either way; there's nothing left to release.
+            logger.debug("closing %s failed: %s", self.port, exc)
+
+    def reset_input(self) -> None:
+        """Discard anything received but not yet read."""
+        conn = self._require_open()
+        self._partial = b""
+        try:
+            conn.reset_input_buffer()
+        except OSError as exc:
+            raise self._lost(exc) from exc
+
+    def write_line(self, line: str) -> None:
+        """Send ``line`` followed by a newline.
+
+        Raises:
+            NotConnected: The port isn't open or the connection was lost.
+        """
+        conn = self._require_open()
+        logger.debug("%s > %s", self.port, line)
+        try:
+            conn.write(f"{line}\n".encode("ascii"))
+            conn.flush()
+        except OSError as exc:
+            raise self._lost(exc) from exc
+
+    def read_line(self, timeout: float | None = None) -> str:
+        """Wait for the next non-blank line.
+
+        Args:
+            timeout: Seconds to wait. Defaults to the transport's timeout.
+
+        Raises:
+            DeviceTimeout: No complete line arrived in time.
+            NotConnected: The port isn't open or the connection was lost.
+        """
+        conn = self._require_open()
+        deadline = time.monotonic() + (self.timeout if timeout is None else timeout)
+        while (remaining := deadline - time.monotonic()) > 0:
+            conn.timeout = remaining
+            try:
+                chunk = conn.readline()
+            except OSError as exc:
+                raise self._lost(exc) from exc
+            # readline() returns what it has so far when it times out.
+            self._partial += chunk
+            if not self._partial.endswith(b"\n"):
+                continue
+            line = self._partial.decode("ascii", errors="replace").strip()
+            self._partial = b""
+            if line:
+                logger.debug("%s < %s", self.port, line)
+                return line
+        raise DeviceTimeout(f"no reply from serial port {self.port!r}")
+
+    def _require_open(self) -> Any:
+        if self._conn is None:
+            raise NotConnected(f"serial port {self.port!r} is not open")
+        return self._conn
+
+    def _lost(self, exc: OSError) -> NotConnected:
+        self.close()
+        return NotConnected(f"lost serial port {self.port!r}: {exc}")
+
+
+def handshake(
+    transport: SerialTransport,
+    command: str,
+    parse: Callable[[str], T | None],
+    timeout: float | None = None,
+) -> T | None:
+    """Send an identification command and wait for a reply that parses.
+
+    Lines that ``parse`` rejects (boot chatter, another device's output) are
+    skipped until the timeout.
+
+    Args:
+        transport: An open transport.
+        command: The identification command, e.g. ``"ID"``.
+        parse: Returns the parsed reply, or ``None`` for a line that isn't one.
+        timeout: Seconds to wait. Defaults to the transport's timeout.
+
+    Returns:
+        The first parsed reply, or ``None`` if none arrived in time.
+    """
+    transport.reset_input()
+    transport.write_line(command)
+    deadline = time.monotonic() + (transport.timeout if timeout is None else timeout)
+    while (remaining := deadline - time.monotonic()) > 0:
+        try:
+            line = transport.read_line(remaining)
+        except DeviceTimeout:
+            return None
+        if (reply := parse(line)) is not None:
+            return reply
+    return None
+
+
+def _open_pyserial(port: str, baudrate: int, timeout: float) -> Any:
+    pyserial = import_optional("serial", extra="serial")
+    return pyserial.Serial(port, baudrate, timeout=timeout, write_timeout=timeout)

educelab/devices/app/__init__.py

@@ -0,0 +1 @@
+"""The ``el-devices`` command-line tool."""

educelab/devices/app/cli.py

@@ -0,0 +1,51 @@
+"""Entry point for ``el-devices``.
+
+Each subcommand is a module in this package with a ``register(subparsers)``
+function that adds its parser and sets ``func``. Subcommand modules import
+their backends inside ``func``, so the CLI starts without any vendor SDK.
+"""
+
+import argparse
+import importlib
+import logging
+import sys
+from collections.abc import Sequence
+
+from educelab.devices import __version__
+from educelab.devices.errors import DeviceError
+
+SUBCOMMANDS = ("discover", "dslr", "foldio", "hub", "misha", "simulate", "spinnaker")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="el-devices",
+        description="Check EduceLab imaging hardware from the command line.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="log device traffic"
+    )
+    subparsers = parser.add_subparsers(
+        title="commands", dest="command", metavar="COMMAND", required=True
+    )
+    for name in SUBCOMMANDS:
+        importlib.import_module(f"educelab.devices.app.{name}").register(subparsers)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+    try:
+        return int(args.func(args) or 0)
+    except DeviceError as exc:
+        print(f"el-devices: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130

educelab/devices/app/discover.py

@@ -0,0 +1,74 @@
+"""``el-devices discover``: list devices the installed backends can find."""
+
+import argparse
+import importlib
+from dataclasses import dataclass
+
+from educelab.devices.device import Device
+from educelab.devices.errors import DeviceError
+
+
+@dataclass(frozen=True)
+class Backend:
+    """A driver whose `discover()` this command calls.
+
+    Attributes:
+        name: Label shown in the output.
+        module: Module that defines the driver. It must import without the
+            vendor SDK.
+        device_class: Name of the driver class in ``module``.
+    """
+
+    name: str
+    module: str
+    device_class: str
+
+
+# Each driver track adds its backend here.
+BACKENDS: tuple[Backend, ...] = (
+    Backend("acroname", "educelab.devices.hubs.acroname", "AcronameHub"),
+    Backend("foldio360", "educelab.devices.stages.foldio360", "Foldio360"),
+    Backend("gphoto2", "educelab.devices.cameras.gphoto2", "GPhoto2Camera"),
+    Backend("misha", "educelab.devices.lights.misha", "MishaLight"),
+    Backend("spinnaker", "educelab.devices.cameras.spinnaker", "SpinnakerCamera"),
+)
+
+
+def register(subparsers: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = subparsers.add_parser(
+        "discover",
+        help="list devices the installed backends can find",
+        description="List devices that the installed backends can find, "
+        "without opening them.",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    found = 0
+    for backend in BACKENDS:
+        try:
+            module = importlib.import_module(backend.module)
+            device_class: type[Device] = getattr(module, backend.device_class)
+            infos = device_class.discover()
+        except ImportError as exc:
+            print(f"{backend.name}: unavailable. {exc}")
+            continue
+        except DeviceError as exc:
+            print(f"{backend.name}: discovery failed. {exc}")
+            continue
+        except Exception as exc:  # noqa: BLE001
+            # One broken backend shouldn't hide the others.
+            print(f"{backend.name}: discovery failed. {type(exc).__name__}: {exc}")
+            continue
+        for info in infos:
+            found += 1
+            details = [f"{info.model} at {info.address or 'unknown address'}"]
+            if info.serial_number:
+                details.append(f"serial {info.serial_number}")
+            if info.firmware_version:
+                details.append(f"firmware {info.firmware_version}")
+            print(f"{backend.name}: {', '.join(details)}")
+    if not found:
+        print("No devices found.")
+    return 0

educelab/devices/app/dslr.py

@@ -0,0 +1,123 @@
+"""``el-devices dslr``: check a camera driven through libgphoto2."""
+
+import argparse
+import sys
+from pathlib import Path, PurePath
+from typing import TYPE_CHECKING
+
+# Imported where it's used, so other subcommands don't load the driver.
+if TYPE_CHECKING:
+    from educelab.devices.cameras.gphoto2 import GPhoto2Camera
+    from educelab.devices.settings import Setting
+
+
+def register(subparsers: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = subparsers.add_parser(
+        "dslr",
+        help="detect a gphoto2 camera, list its settings, capture, and step focus",
+        description="Open a camera through libgphoto2, list its settings and "
+        "whether it has a focus drive, then run whichever checks are asked for. "
+        "Without --port, uses the only camera attached.",
+    )
+    parser.add_argument("--port", help="libgphoto2 port, e.g. usb:020,007")
+    parser.add_argument(
+        "--exposure",
+        type=float,
+        metavar="SECONDS",
+        help="set exposure_time to the shutter speed nearest this many seconds",
+    )
+    parser.add_argument(
+        "--capture",
+        type=Path,
+        metavar="DIR",
+        help="capture once and save every file to this directory, created if needed, "
+        "under the camera's file names",
+    )
+    parser.add_argument(
+        "--preview", action="store_true", help="grab one live-view frame"
+    )
+    parser.add_argument(
+        "--focus-steps",
+        type=int,
+        metavar="N",
+        help="move focus N steps: positive toward far, negative toward near",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    from educelab.devices.cameras import EXPOSURE_TIME
+    from educelab.devices.cameras.gphoto2 import GPhoto2Camera
+
+    camera = GPhoto2Camera(args.port)
+    try:
+        camera.open()
+    except ImportError as exc:
+        print(f"el-devices: {exc}", file=sys.stderr)
+        return 1
+    with camera:
+        print(f"{camera.info.model} at {camera.info.address}")
+        for setting in camera.settings().values():
+            print(f"  {_describe(setting)}")
+        print(f"  focus drive: {'yes' if camera.focus is not None else 'no'}")
+
+        if args.exposure is not None:
+            nearest = camera.setting(EXPOSURE_TIME).nearest(args.exposure)
+            camera.set_setting(EXPOSURE_TIME, nearest)
+            print(f"exposure_time set to {nearest:.4g} s")
+        if args.capture is not None and not _capture(camera, args.capture):
+            return 1
+        if args.preview:
+            height, width = camera.preview_frame().shape[:2]
+            print(f"preview: {width}x{height}")
+        if args.focus_steps is not None and not _step_focus(camera, args.focus_steps):
+            return 1
+    return 0
+
+
+def _describe(setting: "Setting") -> str:
+    value = setting.value
+    if value is None:
+        # e.g. exposure_time with the shutter at Bulb
+        text = f"{setting.name} = no number"
+    else:
+        shown = f"{value:.4g}" if isinstance(value, float) else repr(value)
+        text = f"{setting.name} = {shown}"
+        if setting.unit:
+            text += f" {setting.unit}"
+    if setting.read_only:
+        text += " (read-only)"
+    elif setting.choices is not None:
+        text += f" ({len(setting.choices)} choices)"
+    elif setting.minimum is not None and setting.maximum is not None:
+        text += f" ({setting.minimum:g} to {setting.maximum:g})"
+    return text
+
+
+def _capture(camera: "GPhoto2Camera", directory: Path) -> bool:
+    directory.mkdir(parents=True, exist_ok=True)
+    files = camera.capture_files()
+    for file in files:
+        try:
+            path = file.save(directory, PurePath(file.name).stem)
+        except FileExistsError as exc:
+            print(f"el-devices: {exc}", file=sys.stderr)
+            return False
+        print(f"saved {path} ({len(file.data)} bytes)")
+    return True
+
+
+def _step_focus(camera: "GPhoto2Camera", steps: int) -> bool:
+    from educelab.devices.errors import FocusLimitReached
+
+    focus = camera.focus
+    if focus is None:
+        print(f"el-devices: {camera.info.model} has no focus drive", file=sys.stderr)
+        return False
+    try:
+        focus.step(steps)
+    except FocusLimitReached as exc:
+        print(f"focus reached the {exc.limit} limit before moving {steps:+d} steps")
+        return True
+    print(f"focus moved {steps:+d} steps")
+    return True