serialforge 0.0.1__py3-none-any.whl

serialforge/discovery/baud_cache.py

@@ -0,0 +1,117 @@
+"""Persist successful serial baudrates under a stable device identity."""
+
+from __future__ import annotations
+
+import json
+import threading
+from os import replace as atomic_replace
+from pathlib import Path
+from uuid import uuid4
+
+from loguru import logger
+
+# pylint: disable=no-name-in-module
+from PySide6.QtCore import QStandardPaths
+
+from ..models import DeviceInfo
+from ..settings import LOG_ENABLED
+
+
+class BaudCache:
+    """Keep baudrate hints in memory and optionally in an atomic JSON file."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        """Load a cache; ``None`` keeps fake backend scans in memory."""
+        self._path: Path | None = path
+        self._lock: threading.RLock = threading.RLock()
+        self._rates: dict[str, int] = {}
+        self._load()
+
+    @classmethod
+    def application_cache(cls) -> BaudCache:
+        """Locate persistent baud hints in Qt's application data folder."""
+        root = Path(
+            QStandardPaths.writableLocation(
+                QStandardPaths.StandardLocation.AppLocalDataLocation
+            )
+        )
+        return cls(root / "serialforge" / "baud_cache.json")
+
+    @staticmethod
+    def key(device: DeviceInfo) -> str:
+        """Prefer USB serial, then physical location, then the COM name."""
+        if device.vid is not None and device.pid is not None:
+            prefix = f"{device.vid:04X}:{device.pid:04X}"
+            if device.serial_number:
+                return f"{prefix}:serial:{device.serial_number}"
+            if device.location:
+                return f"{prefix}:location:{device.location}"
+        return f"port:{device.port.upper()}"
+
+    def get(self, device: DeviceInfo) -> int | None:
+        """Return a remembered baudrate for this identity, if any."""
+        with self._lock:
+            return self._rates.get(self.key(device))
+
+    def remember(self, device: DeviceInfo, baudrate: int) -> None:
+        """Persist a successful baudrate when it changes."""
+        with self._lock:
+            key = self.key(device)
+            if self._rates.get(key) == baudrate:
+                return
+            self._rates[key] = baudrate
+            self._save()
+
+    def forget(self, device: DeviceInfo) -> None:
+        """Remove a stale baudrate hint for a device."""
+        with self._lock:
+            if self._rates.pop(self.key(device), None) is not None:
+                self._save()
+
+    def _load(self) -> None:
+        """Ignore a missing or damaged cache without blocking discovery."""
+        path = self._path
+        if path is None:
+            return
+        if not path.exists():
+            return
+        try:
+            document = json.loads(path.read_text(encoding="utf-8-sig"))
+            if not isinstance(document, dict):
+                return
+            self._rates = {
+                key: value
+                for key, value in document.items()
+                if isinstance(key, str)
+                and isinstance(value, int)
+                and not isinstance(value, bool)
+                and value > 0
+            }
+        except (OSError, ValueError, UnicodeError) as exc:
+            if LOG_ENABLED:
+                logger.debug("baud cache unavailable: {}", exc)
+
+    def _save(self) -> None:
+        """Replace the cache atomically so interrupted writes stay safe."""
+        path = self._path
+        if path is None:
+            return
+        temporary = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            temporary.write_text(
+                json.dumps(self._rates, ensure_ascii=False, sort_keys=True),
+                encoding="utf-8",
+            )
+            atomic_replace(temporary, path)
+        except OSError as exc:
+            if LOG_ENABLED:
+                logger.debug("baud cache write failed: {}", exc)
+        finally:
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+__all__ = ["BaudCache"]

serialforge/discovery/baud_prober.py

@@ -0,0 +1,187 @@
+"""Probe candidate baudrates with bounded reads and byte framing."""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import replace
+
+from loguru import logger
+
+from ..advanced import FramingConfig, ProbeSpec, SerialConfig
+from ..enums import FramingMode
+from ..errors import FramingError, PortBusyError
+from ..models import CommandSpec, DeviceInfo, DeviceProfile
+from ..protocols import PortBackend, TransportProtocol
+from ..settings import LOG_ENABLED
+from ..transport import FrameSplitter, PortOptions, PortRegistry
+from .baud_cache import BaudCache
+
+# Probe state is deliberately kept together while each rate owns one handle.
+# pylint: disable=too-many-locals
+
+
+class BaudProber:
+    """Try allowed baudrates serially on one port and validate its reply."""
+
+    def __init__(
+        self, profile: DeviceProfile, backend: PortBackend, cache: BaudCache
+    ) -> None:
+        """Retain the profile, backend, and per-device baud hint cache."""
+        self._profile: DeviceProfile = profile
+        self._backend: PortBackend = backend
+        self._cache: BaudCache = cache
+
+    def probe(
+        self,
+        device: DeviceInfo,
+        cancel: threading.Event,
+        deadline: float,
+        progress: Callable[[str, int], None],
+    ) -> DeviceInfo | None:
+        """Return the first validated baudrate or no result for this port."""
+        started = time.monotonic()
+        cached = self._cache.get(device)
+        rates = list(self._profile.baudrates)
+        if cached in rates:
+            rates.remove(cached)
+            rates.insert(0, cached)
+        for baudrate in rates:
+            if cancel.is_set() or time.monotonic() >= deadline:
+                return None
+            progress(device.port, baudrate)
+            try:
+                response = self.try_rate(device, baudrate, cancel, deadline)
+            except (OSError, RuntimeError, FramingError, PortBusyError) as exc:
+                if LOG_ENABLED:
+                    logger.debug(
+                        "probe failed on {} at {}: {}",
+                        device.port,
+                        baudrate,
+                        exc,
+                    )
+                if isinstance(exc, PortBusyError):
+                    return None
+                continue
+            if response is not None:
+                result = replace(
+                    device,
+                    baudrate=baudrate,
+                    response=response,
+                    elapsed_s=time.monotonic() - started,
+                )
+                self._cache.remember(result, baudrate)
+                return result
+        return None
+
+    def try_rate(
+        self,
+        device: DeviceInfo,
+        baudrate: int,
+        cancel: threading.Event,
+        total_deadline: float,
+    ) -> bytes | None:
+        """Open, probe, and always close one baudrate attempt."""
+        config = self._profile.serial
+        assert isinstance(config, SerialConfig)
+        owner = object()
+        with PortRegistry.lease(device.port, owner):
+            transport = self._backend.open(
+                device.port, PortOptions.build(config, baudrate)
+            )
+            try:
+                transport.set_control_lines(dtr=config.dtr, rts=config.rts)
+                if config.rx_buffer_size is not None:
+                    transport.set_buffer_size(config.rx_buffer_size)
+                probe = self._profile.probe
+                assert isinstance(probe, (CommandSpec, ProbeSpec))
+                settle = (
+                    probe.settle_time_s
+                    if isinstance(probe, ProbeSpec)
+                    and probe.settle_time_s is not None
+                    else config.settle_time_s
+                )
+                if cancel.wait(
+                    min(settle, max(0.0, total_deadline - time.monotonic()))
+                ):
+                    return None
+                if time.monotonic() >= total_deadline:
+                    return None
+                transport.reset_input_buffer()
+                request = (
+                    probe.request.rstrip("\r\n") + self._profile.terminator
+                ).encode(self._profile.encoding)
+                if transport.write(request) != len(request):
+                    return None
+                timeout = probe.timeout_s
+                seconds = (
+                    float(timeout) if isinstance(timeout, (int, float)) else 1.0
+                )
+                deadline = min(total_deadline, time.monotonic() + seconds)
+                return self.read_reply(transport, request, cancel, deadline)
+            finally:
+                try:
+                    transport.close()
+                except (OSError, RuntimeError) as exc:
+                    if LOG_ENABLED:
+                        logger.debug(
+                            "probe close failed on {}: {}", device.port, exc
+                        )
+
+    def read_reply(
+        self,
+        transport: TransportProtocol,
+        request: bytes,
+        cancel: threading.Event,
+        deadline: float,
+    ) -> bytes | None:
+        """Validate framed responses until success, cancellation, or timeout."""
+        profile = self._profile
+        framing = profile.framing or FramingConfig(
+            mode=FramingMode.LINE,
+            terminator=profile.terminator.encode(profile.encoding),
+        )
+        splitter = FrameSplitter(framing)
+        sent_text = request.decode(profile.encoding, errors="replace").strip()
+        while not cancel.is_set():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            chunk = transport.read(1, min(0.02, remaining))
+            if cancel.is_set():
+                return None
+            frames: list[bytes] = []
+            if chunk:
+                parts = [chunk]
+                while True:
+                    extra = transport.read(4096, 0.0)
+                    if not extra:
+                        break
+                    parts.append(extra)
+                frames.extend(splitter.feed(b"".join(parts)))
+            frames.extend(splitter.flush())
+            for frame in frames:
+                text = frame.decode(profile.encoding, errors="replace")
+                if text == sent_text:
+                    continue
+                if self.matches(text):
+                    return frame
+        return None
+
+    def matches(self, text: str) -> bool:
+        """Require the probe's regex or predicate, never mere activity."""
+        probe = self._profile.probe
+        if isinstance(probe, CommandSpec):
+            return (
+                probe.pattern is not None
+                and re.fullmatch(probe.pattern, text) is not None
+            )
+        assert isinstance(probe, ProbeSpec)
+        if isinstance(probe.expect, str):
+            return re.fullmatch(probe.expect, text) is not None
+        return bool(probe.expect(text))
+
+
+__all__ = ["BaudProber"]

serialforge/discovery/device_finder.py

@@ -0,0 +1,161 @@
+"""QtCore facade for bounded serial discovery and baudrate probing."""
+
+from __future__ import annotations
+
+import threading
+import time
+from concurrent.futures import (
+    ThreadPoolExecutor,
+    TimeoutError as FutureTimeoutError,
+    as_completed,
+)
+
+from loguru import logger
+
+# pylint: disable=no-name-in-module
+from PySide6.QtCore import QCoreApplication, QObject, Signal
+
+from ..advanced import RuntimeConfig
+from ..enums import ScanMode
+from ..errors import ProbeError, SerialForgeError
+from ..models import DeviceInfo, DeviceProfile
+from ..protocols import PortBackend
+from ..settings import LOG_ENABLED
+from ..transport import BackendSwitch, SerialTransport
+from .async_scan_thread import AsyncScanThread
+from .baud_cache import BaudCache
+from .baud_prober import BaudProber
+from .port_scanner import PortScanner
+
+# The finder coordinates cache, cancellation, and Qt worker ownership.
+# pylint: disable=too-many-instance-attributes
+
+
+class DeviceFinder(QObject):
+    """Find matching serial devices and remember their working baudrates."""
+
+    probe_progress = Signal(str, int)
+    probe_finished = Signal(object)
+
+    def __init__(self, profile: DeviceProfile) -> None:
+        """Create a finder without enumerating or opening any port."""
+        application = QCoreApplication.instance()
+        if application is None:
+            raise SerialForgeError("DeviceFinder requires a QCoreApplication")
+        super().__init__()
+        self._profile: DeviceProfile = profile
+        self._backend: PortBackend = BackendSwitch.current()
+        self._cache: BaudCache = (
+            BaudCache.application_cache()
+            if isinstance(self._backend, SerialTransport)
+            else BaudCache()
+        )
+        self._cancel: threading.Event = threading.Event()
+        self._lock: threading.RLock = threading.RLock()
+        self._active: bool = False
+        self._thread: AsyncScanThread | None = None
+        self._shutdown_hooked: bool = False
+
+    def find(
+        self, mode: ScanMode = ScanMode.ALL, *, port: str | None = None
+    ) -> list[DeviceInfo]:
+        """Scan synchronously while keeping enumeration on a worker thread."""
+        self._begin()
+        return self.run_find(mode, port)
+
+    def find_async(
+        self, mode: ScanMode = ScanMode.ALL, *, port: str | None = None
+    ) -> None:
+        """Start one background scan and publish its eventual result."""
+        self._begin()
+        thread = AsyncScanThread(self, mode, port)
+        self._thread = thread
+        application = QCoreApplication.instance()
+        assert application is not None
+        application.aboutToQuit.connect(self._shutdown)
+        self._shutdown_hooked = True
+        thread.start()
+
+    def cancel(self) -> None:
+        """Request cooperative cancellation of an active scan."""
+        self._cancel.set()
+
+    def _shutdown(self) -> None:
+        """Join an asynchronous scan before Qt destroys its thread."""
+        self.cancel()
+        thread = self._thread
+        if thread is not None and thread.isRunning():
+            thread.wait(5000)
+
+    def forget(self, device: DeviceInfo) -> None:
+        """Discard one remembered baudrate hint."""
+        self._cache.forget(device)
+
+    def _begin(self) -> None:
+        """Reject overlapping scans and reset cancellation state."""
+        with self._lock:
+            if self._active:
+                raise ProbeError("a device scan is already active")
+            self._active = True
+            self._cancel.clear()
+
+    def run_find(self, mode: ScanMode, port: str | None) -> list[DeviceInfo]:
+        """Run the coordinator and publish exactly one completion signal."""
+        result: list[DeviceInfo] = []
+        try:
+            with ThreadPoolExecutor(max_workers=1) as coordinator:
+                result = coordinator.submit(self._scan, mode, port).result()
+        except (OSError, RuntimeError) as exc:
+            if LOG_ENABLED:
+                logger.debug("device scan failed: {}", exc)
+        finally:
+            with self._lock:
+                self._active = False
+            if self._shutdown_hooked:
+                application = QCoreApplication.instance()
+                if application is not None:
+                    application.aboutToQuit.disconnect(self._shutdown)
+                self._shutdown_hooked = False
+            self.probe_finished.emit(result)
+        return result
+
+    def _scan(self, mode: ScanMode, port: str | None) -> list[DeviceInfo]:
+        """Probe separate ports concurrently and stop on the first match."""
+        runtime = self._profile.runtime
+        assert isinstance(runtime, RuntimeConfig)
+        deadline = time.monotonic() + runtime.probe_total_timeout_s
+        candidates = PortScanner(self._profile, self._backend).scan(port)
+        prober = BaudProber(self._profile, self._backend, self._cache)
+        results: list[DeviceInfo] = []
+        with ThreadPoolExecutor(max_workers=runtime.probe_pool_size) as pool:
+            futures = [
+                pool.submit(
+                    prober.probe,
+                    candidate,
+                    self._cancel,
+                    deadline,
+                    self.probe_progress.emit,
+                )
+                for candidate in candidates
+            ]
+            try:
+                for future in as_completed(
+                    futures, timeout=max(0.001, deadline - time.monotonic())
+                ):
+                    try:
+                        device = future.result()
+                    except (OSError, RuntimeError) as exc:
+                        if LOG_ENABLED:
+                            logger.debug("device probe worker failed: {}", exc)
+                        continue
+                    if device is not None:
+                        results.append(device)
+                        if mode is ScanMode.FIRST_MATCH:
+                            self._cancel.set()
+                            break
+            except FutureTimeoutError:
+                self._cancel.set()
+        return results[:1] if mode is ScanMode.FIRST_MATCH else results
+
+
+__all__ = ["DeviceFinder"]

serialforge/discovery/port_scanner.py

@@ -0,0 +1,48 @@
+"""Filter backend port descriptors by a device profile's USB identity."""
+
+from __future__ import annotations
+
+from ..models import DeviceInfo, DeviceProfile
+from ..protocols import PortBackend
+from ..transport import PortRegistry
+
+# The scanner is a small stateless adapter with one public operation.
+# pylint: disable=too-few-public-methods
+
+
+class PortScanner:
+    """Enumerate only available ports allowed by one device profile."""
+
+    def __init__(self, profile: DeviceProfile, backend: PortBackend) -> None:
+        """Retain a profile and the selected serial backend."""
+        self._profile: DeviceProfile = profile
+        self._backend: PortBackend = backend
+
+    def scan(self, port: str | None = None) -> list[DeviceInfo]:
+        """Return matching descriptors without opening any serial port."""
+        matches: list[DeviceInfo] = []
+        allowed = set(self._profile.vid_pid)
+        for descriptor in self._backend.list_ports():
+            name = getattr(descriptor, "device", None)
+            vid = getattr(descriptor, "vid", None)
+            pid = getattr(descriptor, "pid", None)
+            if not isinstance(name, str) or (vid, pid) not in allowed:
+                continue
+            if port is not None and name.upper() != port.upper():
+                continue
+            if PortRegistry.is_owned(name):
+                continue
+            matches.append(
+                DeviceInfo(
+                    port=name,
+                    vid=vid,
+                    pid=pid,
+                    serial_number=getattr(descriptor, "serial_number", None),
+                    location=getattr(descriptor, "location", None),
+                    description=getattr(descriptor, "description", None),
+                )
+            )
+        return matches
+
+
+__all__ = ["PortScanner"]

serialforge/enums.py

@@ -0,0 +1,129 @@
+"""Enumerations shared by the serialforge public API."""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+
+
+class CommandStatus(StrEnum):
+    """Terminal status reported for a command."""
+
+    OK = "ok"
+    TIMEOUT = "timeout"
+    DISCONNECTED = "disconnected"
+    CANCELLED = "cancelled"
+    PARSE_ERROR = "parse_error"
+    DEVICE_ERROR = "device_error"
+    BUSY = "busy"
+
+
+class ConnectionState(StrEnum):
+    """Connection lifecycle state."""
+
+    DISCONNECTED = "disconnected"
+    PROBING = "probing"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    FAILED = "failed"
+
+
+class ResponseMode(StrEnum):
+    """Expected response shape for a command."""
+
+    NO_REPLY = "no_reply"
+    SINGLE = "single"
+    MULTI = "multi"
+    STREAM = "stream"
+
+
+class Correlation(StrEnum):
+    """How responses are associated with in-flight commands."""
+
+    EXCLUSIVE = "exclusive"
+    TAGGED = "tagged"
+
+
+class ScanMode(StrEnum):
+    """Device scan completion policy."""
+
+    ALL = "all"
+    FIRST_MATCH = "first_match"
+
+
+class DataBits(IntEnum):
+    """Number of data bits in a serial frame."""
+
+    FIVE = 5
+    SIX = 6
+    SEVEN = 7
+    EIGHT = 8
+
+
+class Parity(StrEnum):
+    """Serial parity mode."""
+
+    NONE = "N"
+    EVEN = "E"
+    ODD = "O"
+    MARK = "M"
+    SPACE = "S"
+
+
+class StopBits(StrEnum):
+    """Number of stop bits."""
+
+    ONE = "1"
+    ONE_POINT_FIVE = "1.5"
+    TWO = "2"
+
+
+class FlowControl(StrEnum):
+    """Serial flow-control mode."""
+
+    NONE = "none"
+    XON_XOFF = "xon_xoff"
+    RTS_CTS = "rts_cts"
+    DSR_DTR = "dsr_dtr"
+
+
+class FramingMode(StrEnum):
+    """Byte framing strategy."""
+
+    LINE = "line"
+    DELIMITED = "delimited"
+    LENGTH_PREFIX = "length_prefix"
+    SILENCE_GAP = "silence_gap"
+
+
+class Checksum(StrEnum):
+    """Checksum algorithm selected for binary frames."""
+
+    NONE = "none"
+    SUM8 = "sum8"
+    XOR = "xor"
+    CRC16_MODBUS = "crc16_modbus"
+    CRC16_CCITT = "crc16_ccitt"
+    CRC32 = "crc32"
+
+
+class CommandPriority(IntEnum):
+    """Priority used by the command queue."""
+
+    NORMAL = 0
+    HIGH = 1
+    URGENT = 2
+
+
+class SendRoute(StrEnum):
+    """How a send target was resolved."""
+
+    SPEC = "spec"
+    MATCHED = "matched"
+    RAW = "raw"
+
+
+class TimeoutPolicy(StrEnum):
+    """Special timeout policies accepted by command declarations."""
+
+    AUTO = "auto"

serialforge/errors.py

@@ -0,0 +1,47 @@
+"""Exception hierarchy for serialforge."""
+
+from __future__ import annotations
+
+
+class SerialForgeError(Exception):
+    """Base class for all serialforge errors."""
+
+
+class PortBusyError(SerialForgeError):
+    """Raised when a serial port is already owned by this process."""
+
+
+class PortNotFoundError(SerialForgeError):
+    """Raised when a requested serial port cannot be found."""
+
+
+class PermissionDeniedError(SerialForgeError):
+    """Raised when Windows denies access to a serial port."""
+
+
+class ProbeError(SerialForgeError):
+    """Raised when device probing fails."""
+
+
+class FramingError(SerialForgeError):
+    """Raised when a frame cannot be split or validated."""
+
+
+class CommandError(SerialForgeError):
+    """Raised for invalid command declarations or usage."""
+
+
+class ConfigError(SerialForgeError):
+    """Raised for invalid device or transport configuration."""
+
+
+__all__ = [
+    "SerialForgeError",
+    "PortBusyError",
+    "PortNotFoundError",
+    "PermissionDeniedError",
+    "ProbeError",
+    "FramingError",
+    "CommandError",
+    "ConfigError",
+]