camcontrol 0.1.0__tar.gz

camcontrol-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: camcontrol
+Version: 0.1.0
+Summary: Python CLI + library for Camlock USB-serial access control devices (CH340).
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+
+# camcontrol
+
+Windows-first Python CLI + library for communicating with Camlock USB serial devices (CH340), including PICO Hub-style line commands.
+
+## Install (editable)
+
+```powershell
+pip install -e .
+```
+
+## CLI usage
+
+```powershell
+camcontrol list
+camcontrol connect
+camcontrol send STATE
+camcontrol send UNLOCK
+camcontrol send TEMP
+camcontrol temp
+camcontrol interactive
+```
+
+Optional multi-channel flag (reserved for ACS200-style devices):
+
+```powershell
+camcontrol send STATE --port 3
+```
+
+## Notes
+
+- Commands are sent as complete lines terminated by `\n` (never character-by-character).
+- Responses are read as line-based text; multi-line responses are collected until a blank line or timeout.
+- Serial speed is fixed at **115200 baud**.
+- Package name on PyPI is `camcontrol`. The import/package name is currently `camlock`.

camcontrol-0.1.0/README.md

@@ -0,0 +1,34 @@
+# camcontrol
+
+Windows-first Python CLI + library for communicating with Camlock USB serial devices (CH340), including PICO Hub-style line commands.
+
+## Install (editable)
+
+```powershell
+pip install -e .
+```
+
+## CLI usage
+
+```powershell
+camcontrol list
+camcontrol connect
+camcontrol send STATE
+camcontrol send UNLOCK
+camcontrol send TEMP
+camcontrol temp
+camcontrol interactive
+```
+
+Optional multi-channel flag (reserved for ACS200-style devices):
+
+```powershell
+camcontrol send STATE --port 3
+```
+
+## Notes
+
+- Commands are sent as complete lines terminated by `\n` (never character-by-character).
+- Responses are read as line-based text; multi-line responses are collected until a blank line or timeout.
+- Serial speed is fixed at **115200 baud**.
+- Package name on PyPI is `camcontrol`. The import/package name is currently `camlock`.

camcontrol-0.1.0/camcontrol.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: camcontrol
+Version: 0.1.0
+Summary: Python CLI + library for Camlock USB-serial access control devices (CH340).
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+
+# camcontrol
+
+Windows-first Python CLI + library for communicating with Camlock USB serial devices (CH340), including PICO Hub-style line commands.
+
+## Install (editable)
+
+```powershell
+pip install -e .
+```
+
+## CLI usage
+
+```powershell
+camcontrol list
+camcontrol connect
+camcontrol send STATE
+camcontrol send UNLOCK
+camcontrol send TEMP
+camcontrol temp
+camcontrol interactive
+```
+
+Optional multi-channel flag (reserved for ACS200-style devices):
+
+```powershell
+camcontrol send STATE --port 3
+```
+
+## Notes
+
+- Commands are sent as complete lines terminated by `\n` (never character-by-character).
+- Responses are read as line-based text; multi-line responses are collected until a blank line or timeout.
+- Serial speed is fixed at **115200 baud**.
+- Package name on PyPI is `camcontrol`. The import/package name is currently `camlock`.

camcontrol-0.1.0/camcontrol.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+camcontrol.egg-info/PKG-INFO
+camcontrol.egg-info/SOURCES.txt
+camcontrol.egg-info/dependency_links.txt
+camcontrol.egg-info/entry_points.txt
+camcontrol.egg-info/requires.txt
+camcontrol.egg-info/top_level.txt
+camlock/__init__.py
+camlock/cli.py
+camlock/device.py
+camlock/discovery.py
+camlock/discovery_windows.py
+camlock/exceptions.py
+camlock/interactive.py
+camlock/serial_manager.py

camcontrol-0.1.0/camcontrol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

camcontrol-0.1.0/camcontrol.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+camcontrol = camlock.cli:main
+camlock = camlock.cli:main

camcontrol-0.1.0/camcontrol.egg-info/requires.txt

@@ -0,0 +1 @@
+pyserial>=3.5

camcontrol-0.1.0/camcontrol.egg-info/top_level.txt

@@ -0,0 +1 @@
+camlock

camcontrol-0.1.0/camlock/__init__.py

@@ -0,0 +1,7 @@
+from .device import DeviceInfo
+from .discovery import find_devices
+from .serial_manager import SerialManager
+
+__all__ = ["DeviceInfo", "SerialManager", "find_devices"]
+__version__ = "0.1.0"
+

camcontrol-0.1.0/camlock/cli.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from typing import List, Optional
+
+from .discovery import find_devices, pick_default_device
+from .exceptions import CamlockError, ConnectionError, DiscoveryError, ProtocolError
+from .interactive import run_interactive
+from .serial_manager import SerialConfig, SerialManager
+
+
+def _print_devices(devices) -> None:
+    if not devices:
+        print("No serial ports found.")
+        return
+
+    print("PORT   CH340  VID:PID   DESCRIPTION")
+    for d in devices:
+        vp = d.vid_pid or "-"
+        ch = "yes" if d.is_ch340_like else "no"
+        desc = d.description or d.product or "-"
+        print(f"{d.device:<6} {ch:<5} {vp:<8} {desc}")
+
+
+def _resolve_com_port(explicit: Optional[str]) -> str:
+    if explicit:
+        return explicit
+
+    devices = find_devices()
+    if not devices:
+        raise DiscoveryError("No serial ports found.")
+
+    chosen = pick_default_device(devices)
+    if chosen is None:
+        print("Multiple candidate devices found; specify one with --com.")
+        _print_devices(devices)
+        raise DiscoveryError("No default device could be selected.")
+
+    return chosen.device
+
+
+def _build_manager(args) -> SerialManager:
+    port = _resolve_com_port(args.com)
+    cfg = SerialConfig(
+        port=port,
+        read_timeout_s=args.read_timeout,
+        write_timeout_s=args.write_timeout,
+    )
+    return SerialManager(cfg)
+
+
+def cmd_list(_args) -> int:
+    devices = find_devices()
+    _print_devices(devices)
+    return 0
+
+
+def cmd_help(args) -> int:
+    parser = build_parser(_program_name())
+    if not args.topic:
+        parser.print_help()
+        return 0
+
+    topic = args.topic[0]
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            sub = action.choices.get(topic)
+            if sub is None:
+                print(f"Unknown help topic: {topic}", file=sys.stderr)
+                return 2
+            print(sub.format_help())
+            return 0
+
+    parser.print_help()
+    return 0
+
+
+def cmd_connect(args) -> int:
+    manager = _build_manager(args)
+    with manager:
+        print(f"Connected to {manager.port} @ {manager.baudrate} baud.")
+    return 0
+
+
+def _normalize_command(command: str, *, raw: bool) -> str:
+    cmd = command.strip()
+    if not raw:
+        cmd = cmd.upper()
+    return cmd
+
+
+def cmd_send(args) -> int:
+    manager = _build_manager(args)
+    command = _normalize_command(" ".join(args.command), raw=args.raw)
+    with manager:
+        lines = manager.send_and_read_response(
+            command,
+            acs_port=args.port,
+            total_timeout_s=args.total_timeout,
+            idle_timeout_s=args.idle_timeout,
+            clear_input=True,
+        )
+
+    if not lines:
+        print("(no response)")
+        return 0
+
+    for line in lines:
+        print(line)
+    return 0
+
+
+def cmd_temp(args) -> int:
+    args.command = ["TEMP"]
+    return cmd_send(args)
+
+
+def cmd_interactive(args) -> int:
+    manager = _build_manager(args)
+    with manager:
+        return run_interactive(manager, acs_port=args.port)
+
+
+def _program_name() -> str:
+    base = os.path.basename(sys.argv[0] or "camlock")
+    name, _ext = os.path.splitext(base)
+    return name or "camlock"
+
+
+def build_parser(prog: str) -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog=prog,
+        description="Camlock USB-serial CLI (fixed 115200 baud).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            f"  {prog} list\n"
+            f"  {prog} --com COM15 connect\n"
+            f"  {prog} --com COM15 send STATE\n"
+            f"  {prog} --com COM15 send HOLD ON\n"
+            f"  {prog} --com COM15 temp\n"
+            f"  {prog} --com COM15 interactive\n"
+            "\n"
+            "Shortcuts:\n"
+            f"  {prog} COM15 TEMP        (same as: --com COM15 send TEMP)\n"
+            f"  {prog} COM15 HOLD ON     (same as: --com COM15 send HOLD ON)\n"
+            "\n"
+            "Notes:\n"
+            "  - Commands are sent as complete lines terminated with \\n.\n"
+            "  - Interactive mode sends only after ENTER (never per-character).\n"
+        ),
+    )
+    p.add_argument(
+        "--com",
+        help="Serial port (e.g. COM3). If omitted, auto-selects a likely CH340 port.",
+    )
+    p.add_argument(
+        "--read-timeout",
+        type=float,
+        default=0.2,
+        help="Per-read timeout in seconds (default: 0.2).",
+    )
+    p.add_argument(
+        "--write-timeout",
+        type=float,
+        default=1.0,
+        help="Write timeout in seconds (default: 1.0).",
+    )
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("help", help="Show help for a command.")
+    sp.add_argument("topic", nargs="*", help="Command to show help for (e.g. send).")
+    sp.set_defaults(func=cmd_help)
+
+    sp = sub.add_parser("list", help="List available serial ports.")
+    sp.set_defaults(func=cmd_list)
+
+    sp = sub.add_parser("connect", help="Open and close a serial connection (smoke test).")
+    sp.set_defaults(func=cmd_connect)
+
+    sp = sub.add_parser("send", help="Send a command and print the response.")
+    sp.add_argument(
+        "command",
+        nargs="+",
+        help="Command to send (e.g. STATE, UNLOCK, TEMP, HOLD ON).",
+    )
+    sp.add_argument(
+        "--raw",
+        action="store_true",
+        help="Send exactly as provided (do not auto-uppercase).",
+    )
+    sp.add_argument(
+        "--port",
+        type=int,
+        help="Reserved for multi-channel devices (e.g. ACS200).",
+    )
+    sp.add_argument(
+        "--total-timeout",
+        type=float,
+        default=2.0,
+        help="Max time to wait for the full response (default: 2.0).",
+    )
+    sp.add_argument(
+        "--idle-timeout",
+        type=float,
+        default=0.35,
+        help="Stop after this much response silence (default: 0.35).",
+    )
+    sp.set_defaults(func=cmd_send)
+
+    sp = sub.add_parser("temp", help="Shortcut for: send TEMP.")
+    sp.add_argument(
+        "--raw",
+        action="store_true",
+        help="Send exactly as provided (do not auto-uppercase).",
+    )
+    sp.add_argument(
+        "--port",
+        type=int,
+        help="Reserved for multi-channel devices (e.g. ACS200).",
+    )
+    sp.add_argument(
+        "--total-timeout",
+        type=float,
+        default=2.0,
+        help="Max time to wait for the full response (default: 2.0).",
+    )
+    sp.add_argument(
+        "--idle-timeout",
+        type=float,
+        default=0.35,
+        help="Stop after this much response silence (default: 0.35).",
+    )
+    sp.set_defaults(func=cmd_temp)
+
+    sp = sub.add_parser("interactive", help="Interactive mode (line-based; sends only after ENTER).")
+    sp.add_argument(
+        "--port",
+        type=int,
+        help="Reserved for multi-channel devices (e.g. ACS200).",
+    )
+    sp.set_defaults(func=cmd_interactive)
+
+    return p
+
+
+_SUBCOMMANDS = {"help", "list", "connect", "send", "temp", "interactive"}
+
+
+def _preprocess_argv(argv: List[str]) -> List[str]:
+    if not argv:
+        return argv
+
+    out = list(argv)
+
+    # Allow: camlock COM15 <...>
+    if re.fullmatch(r"COM\d+", out[0], flags=re.IGNORECASE):
+        out = ["--com", out[0], *out[1:]]
+
+    # Allow: camlock [--com COM15] TEMP|STATE|HOLD ON  (default to send)
+    # Find first positional token after known options and their values.
+    options_with_values = {"--com", "--read-timeout", "--write-timeout"}
+    i = 0
+    insert_at: Optional[int] = None
+    while i < len(out):
+        t = out[i]
+        if t in options_with_values:
+            i += 2
+            continue
+        if t.startswith("-"):
+            i += 1
+            continue
+        insert_at = i
+        break
+
+    if insert_at is not None:
+        token = out[insert_at]
+        is_subcommand = token.lower() in _SUBCOMMANDS and token == token.lower()
+        if not is_subcommand:
+            out = out[:insert_at] + ["send"] + out[insert_at:]
+
+    # Allow: camlock help  (common muscle-memory)
+    if out and out[0].lower() == "help":
+        out = ["help", *out[1:]]
+
+    return out
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser(_program_name())
+    args = parser.parse_args(
+        _preprocess_argv(list(argv)) if argv is not None else _preprocess_argv(sys.argv[1:])
+    )
+    try:
+        return int(args.func(args))
+    except (DiscoveryError, ConnectionError, ProtocolError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except CamlockError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

camcontrol-0.1.0/camlock/device.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class DeviceInfo:
+    device: str  # e.g. "COM3"
+    description: str = ""
+    hwid: str = ""
+    manufacturer: str = ""
+    product: str = ""
+    serial_number: str = ""
+    vid: Optional[int] = None
+    pid: Optional[int] = None
+    is_ch340_like: bool = False
+
+    @property
+    def vid_pid(self) -> str:
+        if self.vid is None or self.pid is None:
+            return ""
+        return f"{self.vid:04X}:{self.pid:04X}"
+

camcontrol-0.1.0/camlock/discovery.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from .device import DeviceInfo
+from .exceptions import DiscoveryError
+
+
+def find_devices() -> List[DeviceInfo]:
+    """
+    Windows-only in Phase 1.
+
+    Kept as a thin dispatcher so Linux/macOS backends can be added later without
+    leaking platform-specific logic into the rest of the package.
+    """
+    if sys.platform != "win32":
+        raise DiscoveryError("Device discovery is currently supported on Windows only.")
+    from .discovery_windows import find_devices as impl
+
+    return impl()
+
+
+def pick_default_device(devices: List[DeviceInfo]) -> Optional[DeviceInfo]:
+    if sys.platform != "win32":
+        return None
+    from .discovery_windows import pick_default_device as impl
+
+    return impl(devices)
+

camcontrol-0.1.0/camlock/discovery_windows.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .device import DeviceInfo
+from .exceptions import DiscoveryError
+
+try:
+    from serial.tools import list_ports
+except Exception as exc:  # pragma: no cover
+    list_ports = None  # type: ignore[assignment]
+    _IMPORT_ERROR = exc
+else:
+    _IMPORT_ERROR = None
+
+
+_CH340_VIDS = {0x1A86}
+_CH340_PIDS = {
+    0x7523,  # CH340/CH341
+    0x5523,  # CH341 variant
+}
+
+
+def _is_ch340_like(
+    *,
+    description: str,
+    hwid: str,
+    manufacturer: str,
+    vid: Optional[int],
+    pid: Optional[int],
+) -> bool:
+    text = f"{description} {hwid} {manufacturer}".upper()
+    if "CH340" in text or "CH341" in text:
+        return True
+    if vid is not None and vid in _CH340_VIDS:
+        return True
+    if vid is not None and pid is not None and vid in _CH340_VIDS and pid in _CH340_PIDS:
+        return True
+    if "VID:PID=1A86" in text:
+        return True
+    return False
+
+
+def find_devices() -> List[DeviceInfo]:
+    if list_ports is None:  # pragma: no cover
+        raise DiscoveryError(
+            f"pyserial is required for discovery but could not be imported: {_IMPORT_ERROR}"
+        )
+
+    devices: List[DeviceInfo] = []
+    try:
+        ports = list(list_ports.comports())
+    except Exception as exc:
+        raise DiscoveryError(f"Failed to enumerate serial ports: {exc}") from exc
+
+    for p in ports:
+        vid = getattr(p, "vid", None)
+        pid = getattr(p, "pid", None)
+        manufacturer = getattr(p, "manufacturer", "") or ""
+        product = getattr(p, "product", "") or ""
+        serial_number = getattr(p, "serial_number", "") or ""
+        description = getattr(p, "description", "") or ""
+        hwid = getattr(p, "hwid", "") or ""
+
+        devices.append(
+            DeviceInfo(
+                device=getattr(p, "device", "") or "",
+                description=description,
+                hwid=hwid,
+                manufacturer=manufacturer,
+                product=product,
+                serial_number=serial_number,
+                vid=vid,
+                pid=pid,
+                is_ch340_like=_is_ch340_like(
+                    description=description,
+                    hwid=hwid,
+                    manufacturer=manufacturer,
+                    vid=vid,
+                    pid=pid,
+                ),
+            )
+        )
+
+    return devices
+
+
+def pick_default_device(devices: List[DeviceInfo]) -> Optional[DeviceInfo]:
+    """
+    Choose a sensible default:
+    - Prefer CH340-like ports.
+    - Otherwise, if only one port exists, return it.
+    """
+    ch340 = [d for d in devices if d.is_ch340_like]
+    if len(ch340) == 1:
+        return ch340[0]
+    if len(ch340) > 1:
+        def key(d: DeviceInfo) -> tuple:
+            name = d.device.upper()
+            if name.startswith("COM"):
+                try:
+                    return (0, int(name[3:]))
+                except ValueError:
+                    return (1, name)
+            return (2, name)
+
+        return sorted(ch340, key=key)[0]
+
+    if len(devices) == 1:
+        return devices[0]
+
+    return None
+

camcontrol-0.1.0/camlock/exceptions.py

@@ -0,0 +1,15 @@
+class CamlockError(Exception):
+    """Base exception for camlock."""
+
+
+class DiscoveryError(CamlockError):
+    """Raised when device discovery fails."""
+
+
+class ConnectionError(CamlockError):
+    """Raised when serial connection cannot be established or is lost."""
+
+
+class ProtocolError(CamlockError):
+    """Raised for malformed commands/responses."""
+

camcontrol-0.1.0/camlock/interactive.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from typing import Optional
+
+from .serial_manager import SerialManager
+
+
+def run_interactive(
+    manager: SerialManager,
+    *,
+    acs_port: Optional[int] = None,
+) -> int:
+    """
+    Interactive REPL:
+    - Reads user input line-by-line (only sends after ENTER).
+    - Displays device responses in (near) real-time from a background reader.
+    """
+    stop = threading.Event()
+
+    def on_disconnect(exc: BaseException) -> None:
+        if stop.is_set():
+            return
+        print(f"\n[disconnected] {exc}")
+        print("[reconnecting] attempting to reopen the port...")
+        while not stop.is_set():
+            try:
+                manager.reopen(delay_s=0.5)
+                manager.start_reader(on_disconnect=on_disconnect)
+                print("[reconnected]")
+                return
+            except Exception as e:
+                print(f"[reconnect failed] {e}")
+                time.sleep(1.0)
+
+    rx = manager.start_reader(on_disconnect=on_disconnect)
+
+    def printer() -> None:
+        while not stop.is_set():
+            try:
+                line = rx.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            print(line)
+
+    t = threading.Thread(target=printer, name="camlock-interactive-printer", daemon=True)
+    t.start()
+
+    print("Interactive mode. Type commands and press ENTER. Ctrl+C or 'exit' to quit.")
+    try:
+        while True:
+            try:
+                user = input("camlock> ")
+            except EOFError:
+                break
+            cmd = user.strip()
+            if not cmd:
+                continue
+            if cmd.lower() in {"exit", "quit"}:
+                break
+            manager.send_line(cmd, acs_port=acs_port, clear_input=False)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        stop.set()
+        manager.stop_reader()
+
+    return 0
+

camcontrol-0.1.0/camlock/serial_manager.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import queue
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+import serial
+
+from .exceptions import ConnectionError, ProtocolError
+
+
+def _normalize_port_name(port: str) -> str:
+    port = port.strip()
+    if sys.platform == "win32":
+        up = port.upper()
+        if up.startswith("COM"):
+            # COM10+ sometimes requires the Win32 device prefix.
+            try:
+                n = int(up[3:])
+            except ValueError:
+                return port
+            if n >= 10 and not port.startswith("\\\\.\\"):
+                return f"\\\\.\\{up}"
+            return up
+    return port
+
+
+def _build_command_line(command: str, *, acs_port: Optional[int] = None) -> str:
+    cmd = command.strip()
+    if not cmd:
+        raise ProtocolError("Command cannot be empty.")
+    if "\n" in cmd or "\r" in cmd:
+        raise ProtocolError("Command must be a single line (no embedded newlines).")
+    if acs_port is not None:
+        if acs_port < 1:
+            raise ProtocolError("--port must be >= 1.")
+        # Reserved format for multi-channel devices. Protocol may vary by device.
+        cmd = f"{cmd} {acs_port}"
+    return f"{cmd}\n"
+
+
+@dataclass(frozen=True)
+class SerialConfig:
+    port: str
+    read_timeout_s: float = 0.2
+    write_timeout_s: float = 1.0
+    encoding: str = "utf-8"
+
+
+class SerialManager:
+    """
+    Robust line-oriented serial manager.
+
+    - Writes are always full-line (single write call, terminated with '\\n').
+    - Reads use line-based decoding and support multi-line responses.
+    - Optional background reader thread for interactive mode.
+    """
+
+    def __init__(self, config: SerialConfig):
+        self._config = SerialConfig(
+            port=_normalize_port_name(config.port),
+            read_timeout_s=config.read_timeout_s,
+            write_timeout_s=config.write_timeout_s,
+            encoding=config.encoding,
+        )
+        self._baudrate = 115200
+        self._ser: Optional[serial.Serial] = None
+        self._io_lock = threading.RLock()
+
+        self._rx_queue: "queue.Queue[str]" = queue.Queue()
+        self._reader_thread: Optional[threading.Thread] = None
+        self._reader_stop = threading.Event()
+        self._reader_error: Optional[BaseException] = None
+        self._on_disconnect: Optional[Callable[[BaseException], None]] = None
+
+    @property
+    def port(self) -> str:
+        return self._config.port
+
+    @property
+    def baudrate(self) -> int:
+        return self._baudrate
+
+    def is_open(self) -> bool:
+        s = self._ser
+        return bool(s and s.is_open)
+
+    def open(self) -> None:
+        with self._io_lock:
+            if self.is_open():
+                return
+            try:
+                self._ser = serial.Serial(
+                    port=self._config.port,
+                    baudrate=self._baudrate,
+                    timeout=self._config.read_timeout_s,
+                    write_timeout=self._config.write_timeout_s,
+                )
+            except (serial.SerialException, OSError) as exc:
+                raise ConnectionError(f"Failed to open {self._config.port}: {exc}") from exc
+
+    def close(self) -> None:
+        self.stop_reader()
+        with self._io_lock:
+            if self._ser is None:
+                return
+            try:
+                self._ser.close()
+            except Exception:
+                pass
+            self._ser = None
+
+    def reopen(self, *, delay_s: float = 0.25) -> None:
+        self.close()
+        if delay_s > 0:
+            time.sleep(delay_s)
+        self.open()
+
+    def __enter__(self) -> "SerialManager":
+        self.open()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        self.close()
+
+    def start_reader(
+        self,
+        *,
+        on_disconnect: Optional[Callable[[BaseException], None]] = None,
+    ) -> "queue.Queue[str]":
+        """
+        Start a background reader thread that pushes received lines to a queue.
+        """
+        if self._reader_thread and self._reader_thread.is_alive():
+            return self._rx_queue
+
+        self._on_disconnect = on_disconnect
+        self._reader_error = None
+        self._reader_stop.clear()
+
+        def run() -> None:
+            while not self._reader_stop.is_set():
+                try:
+                    line = self._readline_once()
+                except BaseException as exc:  # includes SerialException/OSError
+                    self._reader_error = exc
+                    if self._on_disconnect:
+                        try:
+                            self._on_disconnect(exc)
+                        except Exception:
+                            pass
+                    return
+
+                if line is None:
+                    continue
+                if line == "":
+                    continue
+                self._rx_queue.put(line)
+
+        self._reader_thread = threading.Thread(
+            target=run, name="camlock-serial-reader", daemon=True
+        )
+        self._reader_thread.start()
+        return self._rx_queue
+
+    def stop_reader(self) -> None:
+        t = self._reader_thread
+        if not t:
+            return
+        self._reader_stop.set()
+        t.join(timeout=1.0)
+        self._reader_thread = None
+
+    def get_reader_error(self) -> Optional[BaseException]:
+        return self._reader_error
+
+    def send_line(
+        self,
+        command: str,
+        *,
+        acs_port: Optional[int] = None,
+        clear_input: bool = True,
+    ) -> None:
+        """
+        Send exactly one full-line command (single write call, with trailing '\\n').
+        """
+        line = _build_command_line(command, acs_port=acs_port)
+        data = line.encode(self._config.encoding)
+
+        with self._io_lock:
+            if not self.is_open():
+                raise ConnectionError("Serial port is not open.")
+            assert self._ser is not None
+            try:
+                if clear_input:
+                    self._ser.reset_input_buffer()
+                written = self._ser.write(data)
+                self._ser.flush()
+            except (serial.SerialException, OSError) as exc:
+                raise ConnectionError(f"Failed to write to {self._config.port}: {exc}") from exc
+
+        if written != len(data):
+            raise ConnectionError(
+                f"Partial write to {self._config.port}: {written}/{len(data)} bytes."
+            )
+
+    def send_and_read_response(
+        self,
+        command: str,
+        *,
+        acs_port: Optional[int] = None,
+        total_timeout_s: float = 2.0,
+        idle_timeout_s: float = 0.35,
+        clear_input: bool = True,
+    ) -> List[str]:
+        """
+        Send a command, then collect response lines.
+
+        Collection stops when:
+        - A blank line is received (common end-of-response marker), OR
+        - No new line arrives for `idle_timeout_s` after at least one line, OR
+        - `total_timeout_s` elapses.
+        """
+        self.send_line(command, acs_port=acs_port, clear_input=clear_input)
+        return self.read_response_lines(
+            total_timeout_s=total_timeout_s, idle_timeout_s=idle_timeout_s
+        )
+
+    def read_response_lines(
+        self,
+        *,
+        total_timeout_s: float = 2.0,
+        idle_timeout_s: float = 0.35,
+    ) -> List[str]:
+        if total_timeout_s <= 0:
+            raise ValueError("total_timeout_s must be > 0")
+        if idle_timeout_s <= 0:
+            raise ValueError("idle_timeout_s must be > 0")
+
+        deadline = time.monotonic() + total_timeout_s
+        last_line_at: Optional[float] = None
+        lines: List[str] = []
+
+        while time.monotonic() < deadline:
+            line = self._readline_once()
+            if line is None:
+                continue
+
+            # Blank line terminator (common in PICO Hub tooling).
+            if line == "":
+                if lines:
+                    break
+                continue
+
+            lines.append(line)
+            now = time.monotonic()
+            last_line_at = now
+
+            # If we got at least one line and then go idle, stop.
+            while time.monotonic() < deadline:
+                if last_line_at is not None and (time.monotonic() - last_line_at) >= idle_timeout_s:
+                    return lines
+                nxt = self._readline_once()
+                if nxt is None:
+                    continue
+                if nxt == "":
+                    return lines
+                lines.append(nxt)
+                last_line_at = time.monotonic()
+
+        return lines
+
+    def _readline_once(self) -> Optional[str]:
+        with self._io_lock:
+            if not self.is_open():
+                raise ConnectionError("Serial port is not open.")
+            assert self._ser is not None
+            try:
+                raw = self._ser.readline()
+            except (serial.SerialException, OSError) as exc:
+                raise ConnectionError(f"Failed to read from {self._config.port}: {exc}") from exc
+
+        if raw is None or raw == b"":
+            return None  # timeout
+
+        # Normalize CRLF/LF and decode.
+        raw = raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+        text = raw.decode(self._config.encoding, errors="replace")
+        text = text.rstrip("\n")
+        return text

camcontrol-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "camcontrol"
+version = "0.1.0"
+description = "Python CLI + library for Camlock USB-serial access control devices (CH340)."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["pyserial>=3.5"]
+
+[project.scripts]
+camcontrol = "camlock.cli:main"
+camlock = "camlock.cli:main"
+
+[tool.setuptools]
+packages = ["camlock"]

camcontrol-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+