pycentauri 0.1.0__py3-none-any.whl

pycentauri/client.py

@@ -0,0 +1,328 @@
+"""High-level async client for the Elegoo Centauri Carbon.
+
+Opens a single WebSocket to ``ws://<host>:3030/websocket``, routes responses
+back to the requesting coroutines by ``RequestID``, and publishes status /
+attribute pushes to any number of subscribers. Control actions are gated
+behind ``enable_control=True`` — attempting a write without it raises
+:class:`ControlDisabledError` before anything is sent over the wire.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Any
+
+import websockets
+from typing_extensions import Self
+from websockets.asyncio.client import ClientConnection, connect
+
+from pycentauri import camera as camera_module
+from pycentauri import sdcp
+from pycentauri.models import Attributes, Status
+
+log = logging.getLogger(__name__)
+
+
+WS_PORT = 3030
+WS_PATH = "/websocket"
+DEFAULT_CONNECT_TIMEOUT = 10.0
+DEFAULT_REQUEST_TIMEOUT = 15.0
+DEFAULT_PUSH_PERIOD_MS = sdcp.DEFAULT_PUSH_PERIOD_MS
+
+
+class PrinterError(RuntimeError):
+    """Base for all client-side printer errors."""
+
+
+class ControlDisabledError(PrinterError):
+    """Raised when a control action is attempted without ``enable_control``."""
+
+
+class RequestTimeoutError(PrinterError):
+    """Raised when a request to the printer does not receive a response in time."""
+
+
+class Printer:
+    """Async client for a single Centauri Carbon.
+
+    Usage::
+
+        async with await Printer.connect("192.168.1.209") as printer:
+            status = await printer.status()
+
+    Or without the context manager::
+
+        printer = await Printer.connect("192.168.1.209")
+        try:
+            ...
+        finally:
+            await printer.close()
+    """
+
+    def __init__(
+        self,
+        host: str,
+        *,
+        enable_control: bool = False,
+        push_period_ms: int = DEFAULT_PUSH_PERIOD_MS,
+    ) -> None:
+        self.host = host
+        self.enable_control = enable_control
+        self.push_period_ms = push_period_ms
+
+        self._ws: ClientConnection | None = None
+        self._reader: asyncio.Task[None] | None = None
+        self._mainboard_id: str | None = None
+
+        self._mainboard_event = asyncio.Event()
+        self._latest_status: Status | None = None
+        self._latest_status_event = asyncio.Event()
+        self._latest_attributes: Attributes | None = None
+        self._latest_attributes_event = asyncio.Event()
+
+        self._pending: dict[str, asyncio.Future[sdcp.ParsedMessage]] = {}
+        self._status_queues: set[asyncio.Queue[Status]] = set()
+        self._closed = False
+
+    @classmethod
+    async def connect(
+        cls,
+        host: str,
+        *,
+        enable_control: bool = False,
+        push_period_ms: int = DEFAULT_PUSH_PERIOD_MS,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+    ) -> Self:
+        """Open a WebSocket to the printer and start the reader task."""
+        self = cls(host, enable_control=enable_control, push_period_ms=push_period_ms)
+        url = f"ws://{host}:{WS_PORT}{WS_PATH}"
+        self._ws = await asyncio.wait_for(connect(url, max_size=None), timeout=connect_timeout)
+        self._reader = asyncio.create_task(self._read_loop(), name=f"pycentauri-reader-{host}")
+        return self
+
+    # --- context-manager sugar -------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    # --- public high-level API -------------------------------------------------
+
+    @property
+    def mainboard_id(self) -> str | None:
+        """Mainboard ID learned from the printer (set once the first Attributes push arrives)."""
+        return self._mainboard_id
+
+    async def wait_for_mainboard(self, timeout: float = 5.0) -> str:
+        """Block until the printer has reported its mainboard ID."""
+        if self._mainboard_id:
+            return self._mainboard_id
+        # The printer sends an Attributes push shortly after connect; a fresh
+        # GET_PRINTER_ATTRIBUTES also triggers one. Fire one off just in case.
+        with contextlib.suppress(Exception):
+            await self._send_raw(
+                sdcp.encode(
+                    sdcp.build_request(
+                        sdcp.Cmd.GET_PRINTER_ATTRIBUTES, None, self._mainboard_id or ""
+                    )
+                )
+            )
+        await asyncio.wait_for(self._mainboard_event.wait(), timeout=timeout)
+        assert self._mainboard_id is not None
+        return self._mainboard_id
+
+    async def status(self, timeout: float = DEFAULT_REQUEST_TIMEOUT) -> Status:
+        """Get the current printer status.
+
+        If we've already received a push, return it immediately. Otherwise
+        subscribe briefly (Cmd 512) and wait for the first push.
+        """
+        if self._latest_status is not None:
+            return self._latest_status
+        await self._ensure_subscribed()
+        await asyncio.wait_for(self._latest_status_event.wait(), timeout=timeout)
+        assert self._latest_status is not None
+        return self._latest_status
+
+    async def attributes(self, timeout: float = DEFAULT_REQUEST_TIMEOUT) -> Attributes:
+        """Return the printer's attributes (model, firmware, capabilities)."""
+        if self._latest_attributes is not None:
+            return self._latest_attributes
+        mid = await self.wait_for_mainboard(timeout=timeout)
+        await self._request(sdcp.Cmd.GET_PRINTER_ATTRIBUTES, None, mid, timeout=timeout)
+        await asyncio.wait_for(self._latest_attributes_event.wait(), timeout=timeout)
+        assert self._latest_attributes is not None
+        return self._latest_attributes
+
+    async def watch(self) -> AsyncIterator[Status]:
+        """Yield status updates as they arrive from the printer."""
+        await self._ensure_subscribed()
+        queue: asyncio.Queue[Status] = asyncio.Queue(maxsize=64)
+        self._status_queues.add(queue)
+        try:
+            if self._latest_status is not None:
+                queue.put_nowait(self._latest_status)
+            while not self._closed:
+                yield await queue.get()
+        finally:
+            self._status_queues.discard(queue)
+
+    async def snapshot(self, *, timeout: float = camera_module.DEFAULT_TIMEOUT) -> bytes:
+        """Return a single JPEG frame from the built-in webcam."""
+        return await camera_module.snapshot(self.host, timeout=timeout)
+
+    # --- control actions (gated) ----------------------------------------------
+
+    async def start_print(
+        self,
+        filename: str,
+        *,
+        storage: str = "local",
+        auto_leveling: bool = True,
+        timelapse: bool = False,
+    ) -> sdcp.ParsedMessage:
+        """Start a print of an existing file on the printer.
+
+        ``storage`` is either ``"local"`` (internal storage) or ``"udisk"``
+        (USB). The filename is the name used by the printer, not a local path.
+        """
+        self._require_control("start_print")
+        path_prefix = "/usb" if storage == "udisk" else "/local"
+        data: dict[str, Any] = {
+            "Filename": filename,
+            "StartLayer": 0,
+            "Calibration_switch": 1 if auto_leveling else 0,
+            "PrintPlatformType": 0,
+            "Tlp_Switch": 1 if timelapse else 0,
+            "slot_map": [],
+            "path_prefix": path_prefix,
+        }
+        mid = await self.wait_for_mainboard()
+        return await self._request(sdcp.Cmd.START_PRINT, data, mid)
+
+    async def pause(self) -> sdcp.ParsedMessage:
+        self._require_control("pause")
+        mid = await self.wait_for_mainboard()
+        return await self._request(sdcp.Cmd.PAUSE_PRINT, None, mid)
+
+    async def resume(self) -> sdcp.ParsedMessage:
+        self._require_control("resume")
+        mid = await self.wait_for_mainboard()
+        return await self._request(sdcp.Cmd.RESUME_PRINT, None, mid)
+
+    async def stop(self) -> sdcp.ParsedMessage:
+        self._require_control("stop")
+        mid = await self.wait_for_mainboard()
+        return await self._request(sdcp.Cmd.STOP_PRINT, None, mid)
+
+    # --- lifecycle -------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Close the WebSocket and stop the reader."""
+        if self._closed:
+            return
+        self._closed = True
+        if self._reader is not None and not self._reader.done():
+            self._reader.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await self._reader
+        if self._ws is not None:
+            with contextlib.suppress(Exception):
+                await self._ws.close()
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(PrinterError("connection closed"))
+
+    # --- internals -------------------------------------------------------------
+
+    def _require_control(self, action: str) -> None:
+        if not self.enable_control:
+            raise ControlDisabledError(
+                f"{action!r} requires enable_control=True; "
+                "Printer.connect(..., enable_control=True) to allow write actions"
+            )
+
+    async def _send_raw(self, text: str) -> None:
+        if self._ws is None:
+            raise PrinterError("not connected")
+        await self._ws.send(text)
+
+    async def _ensure_subscribed(self) -> None:
+        mid = await self.wait_for_mainboard()
+        pkt = sdcp.build_subscribe(mid, period_ms=self.push_period_ms)
+        await self._send_raw(sdcp.encode(pkt))
+
+    async def _request(
+        self,
+        cmd: int,
+        data: dict[str, Any] | None,
+        mainboard_id: str,
+        *,
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ) -> sdcp.ParsedMessage:
+        pkt = sdcp.build_request(cmd, data, mainboard_id)
+        request_id = pkt["Data"]["RequestID"]
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[sdcp.ParsedMessage] = loop.create_future()
+        self._pending[request_id] = fut
+        try:
+            await self._send_raw(sdcp.encode(pkt))
+            return await asyncio.wait_for(fut, timeout=timeout)
+        except asyncio.TimeoutError as err:
+            raise RequestTimeoutError(f"cmd {cmd} timed out after {timeout}s") from err
+        finally:
+            self._pending.pop(request_id, None)
+
+    async def _read_loop(self) -> None:
+        assert self._ws is not None
+        try:
+            async for raw in self._ws:
+                try:
+                    self._handle_frame(raw)
+                except Exception:
+                    log.exception("failed to handle frame: %r", raw[:200] if raw else raw)
+        except websockets.ConnectionClosed:
+            log.debug("ws closed by peer")
+        except Exception:
+            log.exception("ws reader crashed")
+        finally:
+            self._closed = True
+            for fut in self._pending.values():
+                if not fut.done():
+                    fut.set_exception(PrinterError("connection closed"))
+
+    def _handle_frame(self, raw: str | bytes) -> None:
+        msg = sdcp.parse_message(raw)
+
+        if msg.mainboard_id and self._mainboard_id is None:
+            self._mainboard_id = msg.mainboard_id
+            self._mainboard_event.set()
+            log.debug("learned mainboard id: %s", msg.mainboard_id)
+
+        if msg.type == sdcp.MessageType.STATUS and msg.status is not None:
+            status = Status.from_payload(msg.status)
+            self._latest_status = status
+            self._latest_status_event.set()
+            for q in list(self._status_queues):
+                with contextlib.suppress(asyncio.QueueFull):
+                    q.put_nowait(status)
+
+        elif msg.type == sdcp.MessageType.ATTRIBUTES and msg.attributes is not None:
+            self._latest_attributes = Attributes.from_payload(msg.attributes)
+            self._latest_attributes_event.set()
+
+        if msg.request_id and msg.request_id in self._pending:
+            fut = self._pending[msg.request_id]
+            if not fut.done():
+                fut.set_result(msg)

pycentauri/discovery.py

@@ -0,0 +1,96 @@
+"""LAN discovery for Elegoo Centauri Carbon printers.
+
+The original Centauri Carbon listens on UDP port 3000 and responds to the
+magic probe string ``M99999`` with a JSON payload describing itself. The
+newer Centauri Carbon 2 uses a different JSON-RPC probe and is not supported
+here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+from dataclasses import dataclass
+from typing import Any
+
+DISCOVERY_PORT = 3000
+DISCOVERY_PROBE = b"M99999"
+DEFAULT_TIMEOUT = 3.0
+
+
+@dataclass(slots=True)
+class DiscoveredPrinter:
+    """A printer that answered a discovery broadcast."""
+
+    host: str
+    mainboard_id: str | None
+    name: str | None
+    machine_name: str | None
+    firmware_version: str | None
+    raw: dict[str, Any]
+
+
+def _parse_response(data: bytes, host: str) -> DiscoveredPrinter | None:
+    try:
+        obj = json.loads(data.decode("utf-8", "replace"))
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if not isinstance(obj, dict):
+        return None
+    inner_raw = obj.get("Data")
+    inner: dict[str, Any] = inner_raw if isinstance(inner_raw, dict) else {}
+    return DiscoveredPrinter(
+        host=host,
+        mainboard_id=inner.get("MainboardID") or obj.get("MainboardID"),
+        name=inner.get("Name"),
+        machine_name=inner.get("MachineName"),
+        firmware_version=inner.get("FirmwareVersion"),
+        raw=obj,
+    )
+
+
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    def __init__(self) -> None:
+        self.results: dict[str, DiscoveredPrinter] = {}
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        host = addr[0]
+        if host in self.results:
+            return
+        parsed = _parse_response(data, host)
+        if parsed is not None:
+            self.results[host] = parsed
+
+
+async def discover(
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    broadcast_address: str = "255.255.255.255",
+    port: int = DISCOVERY_PORT,
+) -> list[DiscoveredPrinter]:
+    """Broadcast the SDCP discovery probe and collect responders.
+
+    Blocks for ``timeout`` seconds. Returns one entry per responding printer,
+    de-duplicated by source IP. Safe to call concurrently from multiple
+    tasks; each call uses its own UDP socket.
+    """
+    loop = asyncio.get_running_loop()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("", 0))
+    sock.setblocking(False)
+
+    transport, protocol = await loop.create_datagram_endpoint(
+        _DiscoveryProtocol,
+        sock=sock,
+    )
+    try:
+        transport.sendto(DISCOVERY_PROBE, (broadcast_address, port))
+        await asyncio.sleep(timeout)
+    finally:
+        transport.close()
+
+    return list(protocol.results.values())

pycentauri/mcp/__main__.py

@@ -0,0 +1,4 @@
+from pycentauri.mcp.server import _cli
+
+if __name__ == "__main__":
+    _cli()

pycentauri/mcp/server.py

@@ -0,0 +1,211 @@
+"""FastMCP server exposing the printer to MCP-speaking agents.
+
+Register with an agent as a stdio server. Examples:
+
+.. code-block:: sh
+
+    # Read-only tools only:
+    claude mcp add pycentauri -- python -m pycentauri.mcp
+
+    # With control actions (start/pause/resume/stop):
+    claude mcp add pycentauri -- python -m pycentauri.mcp --enable-control
+
+The printer host is read from ``PYCENTAURI_HOST`` (preferred) or from a
+``--host`` argument at launch time — it is **not** a per-tool parameter, so
+an LLM cannot be tricked into targeting an arbitrary IP through prompt
+injection.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP, Image
+
+from pycentauri.client import Printer
+from pycentauri.discovery import discover as _lan_discover
+
+_HOST_ENV = "PYCENTAURI_HOST"
+
+
+def _resolve_host() -> str:
+    host = os.environ.get(_HOST_ENV)
+    if not host:
+        raise RuntimeError(
+            f"{_HOST_ENV} is not set; launch the server with --host IP or "
+            "export PYCENTAURI_HOST first"
+        )
+    return host
+
+
+def build_server(*, enable_control: bool = False) -> FastMCP:
+    """Construct the FastMCP server, registering tools per the control flag.
+
+    Control tools are not registered at all when ``enable_control=False`` —
+    they never appear in the tool list the LLM sees.
+    """
+    mcp = FastMCP("pycentauri")
+
+    @mcp.tool()
+    async def get_status() -> dict[str, Any]:
+        """Return the current printer status.
+
+        Includes state code, job filename, progress %, layer, temperatures
+        (nozzle / bed / chamber), fan speeds, and the raw SDCP payload.
+        """
+        host = _resolve_host()
+        async with await Printer.connect(host) as printer:
+            st = await printer.status()
+        return {
+            "host": host,
+            "state": st.state,
+            "print_status": st.print_status,
+            "progress": st.progress,
+            "filename": st.filename,
+            "layer": {
+                "current": st.print_info.current_layer if st.print_info else None,
+                "total": st.print_info.total_layer if st.print_info else None,
+            },
+            "temperatures": {
+                "nozzle": {"actual": st.temp_nozzle, "target": st.temp_nozzle_target},
+                "bed": {"actual": st.temp_bed, "target": st.temp_bed_target},
+                "chamber": {"actual": st.temp_chamber, "target": st.temp_chamber_target},
+            },
+            "position": st.coord,
+            "z_offset": st.z_offset,
+            "fans": st.fan_speed,
+            "raw": st.raw,
+        }
+
+    @mcp.tool()
+    async def get_attributes() -> dict[str, Any]:
+        """Return printer attributes: model, firmware, mainboard ID, capabilities."""
+        host = _resolve_host()
+        async with await Printer.connect(host) as printer:
+            attrs = await printer.attributes()
+        return {
+            "host": host,
+            "mainboard_id": attrs.mainboard_id,
+            "name": attrs.name,
+            "machine_name": attrs.machine_name,
+            "firmware_version": attrs.firmware_version,
+            "capabilities": attrs.capabilities,
+            "raw": attrs.raw,
+        }
+
+    @mcp.tool()
+    async def get_snapshot() -> Image:
+        """Return a JPEG snapshot of the built-in webcam.
+
+        The image is returned inline so the agent can see what the printer
+        is currently doing (e.g. to spot layer shifts or spaghetti).
+        """
+        host = _resolve_host()
+        async with await Printer.connect(host) as printer:
+            jpeg = await printer.snapshot()
+        return Image(data=jpeg, format="jpeg")
+
+    @mcp.tool()
+    async def discover_printers() -> list[dict[str, Any]]:
+        """Broadcast the SDCP discovery probe and return responding printers.
+
+        Useful to verify the configured host matches what's actually on the
+        LAN, or to find a newly-added printer's IP.
+        """
+        found = await _lan_discover(timeout=2.5)
+        return [
+            {
+                "host": p.host,
+                "mainboard_id": p.mainboard_id,
+                "name": p.name,
+                "machine_name": p.machine_name,
+                "firmware_version": p.firmware_version,
+            }
+            for p in found
+        ]
+
+    if not enable_control:
+        return mcp
+
+    # --- Control tools (registered only when explicitly enabled) --------------
+
+    @mcp.tool()
+    async def start_print(
+        filename: str,
+        storage: str = "local",
+        auto_leveling: bool = True,
+        timelapse: bool = False,
+    ) -> dict[str, Any]:
+        """DESTRUCTIVE. Start a print of ``filename`` (already on the printer).
+
+        Requires a file that has been uploaded to the printer. ``storage`` is
+        ``"local"`` (default) or ``"udisk"``. Ask the user for confirmation
+        before invoking — running a print unattended is the user's risk.
+        """
+        host = _resolve_host()
+        async with await Printer.connect(host, enable_control=True) as printer:
+            result = await printer.start_print(
+                filename,
+                storage=storage,
+                auto_leveling=auto_leveling,
+                timelapse=timelapse,
+            )
+        return {"ok": True, "response": result.inner}
+
+    @mcp.tool()
+    async def pause_print() -> dict[str, Any]:
+        """DESTRUCTIVE. Pause the current print. Ask the user before invoking."""
+        host = _resolve_host()
+        async with await Printer.connect(host, enable_control=True) as printer:
+            result = await printer.pause()
+        return {"ok": True, "response": result.inner}
+
+    @mcp.tool()
+    async def resume_print() -> dict[str, Any]:
+        """Resume a paused print."""
+        host = _resolve_host()
+        async with await Printer.connect(host, enable_control=True) as printer:
+            result = await printer.resume()
+        return {"ok": True, "response": result.inner}
+
+    @mcp.tool()
+    async def stop_print() -> dict[str, Any]:
+        """DESTRUCTIVE. Stop the current print. Ask the user before invoking."""
+        host = _resolve_host()
+        async with await Printer.connect(host, enable_control=True) as printer:
+            result = await printer.stop()
+        return {"ok": True, "response": result.inner}
+
+    return mcp
+
+
+def run_stdio(*, enable_control: bool = False) -> None:
+    """Run the MCP server over stdio until the transport closes."""
+    mcp = build_server(enable_control=enable_control)
+    mcp.run()
+
+
+def _cli() -> None:
+    parser = argparse.ArgumentParser(
+        prog="python -m pycentauri.mcp",
+        description="MCP server for pycentauri (stdio transport)",
+    )
+    parser.add_argument(
+        "--enable-control",
+        action="store_true",
+        help="Register destructive tools (start/pause/resume/stop).",
+    )
+    parser.add_argument(
+        "--host",
+        help="Printer host/IP. Overrides $PYCENTAURI_HOST for this process.",
+    )
+    args = parser.parse_args()
+    if args.host:
+        os.environ[_HOST_ENV] = args.host
+    run_stdio(enable_control=args.enable_control)
+
+
+if __name__ == "__main__":
+    _cli()