pycentauri 0.1.0__tar.gz → 0.2.0__tar.gz

pycentauri-0.2.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) and [Keep a
+Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-04-22
+
+### Added
+- **HTTP + SSE server.** `centauri server [--host IP] [--bind 127.0.0.1]
+  [--port 8787] [--enable-control]` runs a FastAPI app that wraps the
+  same client library used by the CLI and MCP server:
+  - `GET /` — health, version, connection state
+  - `GET /status` — latest status snapshot (JSON)
+  - `GET /attributes` — printer attributes (JSON)
+  - `GET /snapshot` — single JPEG frame from the webcam
+  - `GET /discover` — UDP LAN scan
+  - `GET /events/status` — Server-Sent Events stream of live status pushes
+  - `POST /print/{start,pause,resume,stop}` — only registered with
+    `--enable-control` (mirrors the MCP security posture — the routes
+    literally don't exist without the flag)
+- New optional extra: `pip install 'pycentauri[server]'` pulls in
+  FastAPI + uvicorn + sse-starlette.
+- The server holds a single long-lived WebSocket for its lifetime with
+  auto-reconnect and exponential backoff, so it never bumps against the
+  printer's 5-slot limit and HTTP requests return cached pushes instantly.
+
+## [0.1.1] - 2026-04-22
+
+### Fixed
+- `Printer.status()`, `attributes()`, and all control methods hung
+  indefinitely when the printer was in a paused or errored state. The
+  firmware doesn't push `Attributes` spontaneously outside idle/active
+  states, and every SDCP command needs a `MainboardID` in its envelope,
+  so the client would deadlock waiting for a push that never comes.
+- The CLI and MCP server now pre-discover the printer over UDP before
+  opening the WebSocket and pass the mainboard ID into `Printer.connect()`.
+
+### Added
+- `Printer.connect(..., mainboard_id=...)` — pre-seed the mainboard ID
+  (e.g. from a prior `discover()`) so the client can send commands
+  immediately, without waiting for the printer's first `Attributes` push.
+- `Printer.wait_for_mainboard()` now raises a `PrinterError` with a
+  pointer at the `mainboard_id=` workaround instead of a bare
+  `asyncio.TimeoutError`.
+
+### Changed
+- `discover()` retransmits the probe multiple times within the timeout
+  window, improving reliability on busy or lossy networks. Also binds
+  explicitly to `0.0.0.0` so loopback delivery works on macOS.
+
+### Known limits
+- Elegoo firmware accepts at most **5 concurrent WebSocket connections**
+  on port 3030. The 6th attempt is rejected at the HTTP upgrade with
+  `HTTP 500 "too many client"`. Slots release immediately on close.
+
+## [0.1.0] - 2026-04-22
+
+### Added
+- Async Python client for Elegoo Centauri Carbon printers speaking SDCP v3 over
+  WebSocket (`ws://<host>:3030/websocket`).
+- UDP broadcast discovery on port 3000 with the `M99999` probe.
+- MJPEG snapshot grabber for the built-in webcam
+  (`/network-device-manager/network/camera`).
+- `centauri` CLI with `discover`, `status`, `watch`, `snapshot`, `attributes`,
+  `files`, `print {start,pause,resume,stop}`, `upload`, `mcp`.
+- Optional MCP server (`python -m pycentauri.mcp`) with read-only tools by
+  default; control tools registered only when `--enable-control` is set.
+- Apache-2.0 license.

{pycentauri-0.1.0 → pycentauri-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycentauri
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python client and MCP server for Elegoo Centauri Carbon 3D printers
 Project-URL: Homepage, https://github.com/bjan/pycentauri
 Project-URL: Repository, https://github.com/bjan/pycentauri
@@ -28,13 +28,22 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: typer>=0.12
 Requires-Dist: websockets>=12.0
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mcp>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: sse-starlette>=2.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: sse-starlette>=2.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
 Description-Content-Type: text/markdown
 
 # pycentauri
@@ -43,12 +52,14 @@ Python client, CLI, and MCP server for the [Elegoo Centauri
 Carbon](https://www.elegoo.com/) 3D printer.
 
 `pycentauri` speaks the printer's native SDCP v3 protocol over its local
-WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
+WebSocket (port 3030) — no cloud account required. It exposes four surfaces:
 
 1. An **async Python library** for direct integration.
 2. A **`centauri` CLI** for quick status checks, snapshots, and control.
 3. An **MCP server** so AI agents (Claude Code, Claude Desktop, Cursor, any
    MCP-compatible client) can monitor and drive the printer as a tool.
+4. An **HTTP + SSE server** for dashboards, reverse-proxy integration, and
+   anything that wants a plain REST API.
 
 > **Status:** alpha. The protocol has been reverse-engineered from the official
 > [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK and the
@@ -59,8 +70,10 @@ WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
 ## Install
 
 ```sh
-pip install pycentauri            # library + CLI
-pip install "pycentauri[mcp]"     # + MCP server dependencies
+pip install pycentauri                    # library + CLI
+pip install "pycentauri[mcp]"             # + MCP server
+pip install "pycentauri[server]"          # + HTTP REST/SSE server
+pip install "pycentauri[mcp,server]"      # everything
 ```
 
 ## Quick start — CLI
@@ -112,6 +125,31 @@ async def main():
 asyncio.run(main())
 ```
 
+## Quick start — HTTP server
+
+```sh
+# Read-only, bound to loopback so only this box can hit it:
+centauri server --host 192.168.1.209 --port 8787
+
+# Read + write, bound to all interfaces (put a reverse proxy in front):
+centauri server --host 192.168.1.209 --bind 0.0.0.0 --port 8787 --enable-control
+```
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/` | Health + version |
+| `GET` | `/status` | Latest status push (cached; updates every ~5s) |
+| `GET` | `/attributes` | Printer attributes |
+| `GET` | `/snapshot` | `image/jpeg` response |
+| `GET` | `/discover` | LAN scan |
+| `GET` | `/events/status` | Server-Sent Events stream of pushes |
+| `POST` | `/print/start` | Body: `{"filename": "cube.gcode"}`. Requires `--enable-control`. |
+| `POST` | `/print/{pause,resume,stop}` | Requires `--enable-control`. |
+
+The server holds a single long-lived WebSocket to the printer and reuses
+it for every request — no per-request reconnect, and it won't bump into
+the firmware's 5-slot limit.
+
 ## Quick start — MCP
 
 Register the server with your agent. With Claude Code:
@@ -145,6 +183,21 @@ Control actions are gated behind an explicit `enable_control=True` (library) or
 registered when the flag is off, so an LLM never sees them. Still: leaving a
 printer running unattended with write-capable agents is your responsibility.
 
+## Known firmware quirks
+
+- **5 concurrent WebSocket connections max.** The printer's SDCP server
+  accepts up to 5 open WebSockets on port 3030; the 6th returns HTTP 500
+  with body `"too many client"`. Slots release immediately when a
+  connection closes — the CLI and MCP server each open/close one per
+  invocation, so this is almost never a problem in practice.
+- **Paused / errored states don't auto-push Attributes.** The printer only
+  sends its `Attributes` frame spontaneously while idle or printing. In
+  paused and errored states it stays silent until asked. Since every SDCP
+  command needs the printer's `MainboardID`, the client takes care of this
+  by pre-seeding the mainboard ID from a UDP discovery on every connect
+  (as of v0.1.1). If you call `Printer.connect()` directly without
+  discovery, pass `mainboard_id=` yourself.
+
 ## Credits & licensing
 
 - Protocol reference: [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link)

{pycentauri-0.1.0 → pycentauri-0.2.0}/README.md

@@ -4,12 +4,14 @@ Python client, CLI, and MCP server for the [Elegoo Centauri
 Carbon](https://www.elegoo.com/) 3D printer.
 
 `pycentauri` speaks the printer's native SDCP v3 protocol over its local
-WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
+WebSocket (port 3030) — no cloud account required. It exposes four surfaces:
 
 1. An **async Python library** for direct integration.
 2. A **`centauri` CLI** for quick status checks, snapshots, and control.
 3. An **MCP server** so AI agents (Claude Code, Claude Desktop, Cursor, any
    MCP-compatible client) can monitor and drive the printer as a tool.
+4. An **HTTP + SSE server** for dashboards, reverse-proxy integration, and
+   anything that wants a plain REST API.
 
 > **Status:** alpha. The protocol has been reverse-engineered from the official
 > [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK and the
@@ -20,8 +22,10 @@ WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
 ## Install
 
 ```sh
-pip install pycentauri            # library + CLI
-pip install "pycentauri[mcp]"     # + MCP server dependencies
+pip install pycentauri                    # library + CLI
+pip install "pycentauri[mcp]"             # + MCP server
+pip install "pycentauri[server]"          # + HTTP REST/SSE server
+pip install "pycentauri[mcp,server]"      # everything
 ```
 
 ## Quick start — CLI
@@ -73,6 +77,31 @@ async def main():
 asyncio.run(main())
 ```
 
+## Quick start — HTTP server
+
+```sh
+# Read-only, bound to loopback so only this box can hit it:
+centauri server --host 192.168.1.209 --port 8787
+
+# Read + write, bound to all interfaces (put a reverse proxy in front):
+centauri server --host 192.168.1.209 --bind 0.0.0.0 --port 8787 --enable-control
+```
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/` | Health + version |
+| `GET` | `/status` | Latest status push (cached; updates every ~5s) |
+| `GET` | `/attributes` | Printer attributes |
+| `GET` | `/snapshot` | `image/jpeg` response |
+| `GET` | `/discover` | LAN scan |
+| `GET` | `/events/status` | Server-Sent Events stream of pushes |
+| `POST` | `/print/start` | Body: `{"filename": "cube.gcode"}`. Requires `--enable-control`. |
+| `POST` | `/print/{pause,resume,stop}` | Requires `--enable-control`. |
+
+The server holds a single long-lived WebSocket to the printer and reuses
+it for every request — no per-request reconnect, and it won't bump into
+the firmware's 5-slot limit.
+
 ## Quick start — MCP
 
 Register the server with your agent. With Claude Code:
@@ -106,6 +135,21 @@ Control actions are gated behind an explicit `enable_control=True` (library) or
 registered when the flag is off, so an LLM never sees them. Still: leaving a
 printer running unattended with write-capable agents is your responsibility.
 
+## Known firmware quirks
+
+- **5 concurrent WebSocket connections max.** The printer's SDCP server
+  accepts up to 5 open WebSockets on port 3030; the 6th returns HTTP 500
+  with body `"too many client"`. Slots release immediately when a
+  connection closes — the CLI and MCP server each open/close one per
+  invocation, so this is almost never a problem in practice.
+- **Paused / errored states don't auto-push Attributes.** The printer only
+  sends its `Attributes` frame spontaneously while idle or printing. In
+  paused and errored states it stays silent until asked. Since every SDCP
+  command needs the printer's `MainboardID`, the client takes care of this
+  by pre-seeding the mainboard ID from a UDP discovery on every connect
+  (as of v0.1.1). If you call `Printer.connect()` directly without
+  discovery, pass `mainboard_id=` yourself.
+
 ## Credits & licensing
 
 - Protocol reference: [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link)

{pycentauri-0.1.0 → pycentauri-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycentauri"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python client and MCP server for Elegoo Centauri Carbon 3D printers"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,12 +35,15 @@ dependencies = [
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.2"]
+server = ["fastapi>=0.110", "uvicorn[standard]>=0.29", "sse-starlette>=2.0"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "ruff>=0.5",
     "mypy>=1.10",
     "pytest-cov>=5.0",
+    "httpx>=0.27",
+    "pycentauri[mcp,server]",
 ]
 
 [project.scripts]
@@ -63,6 +66,10 @@ target-version = "py310"
 select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
 ignore = ["E501"]
 
+[tool.ruff.lint.per-file-ignores]
+# FastAPI's idiomatic DI uses `Depends()` in default values; that's B008.
+"src/pycentauri/server.py" = ["B008"]
+
 [tool.mypy]
 python_version = "3.10"
 strict = true

{pycentauri-0.1.0 → pycentauri-0.2.0}/src/pycentauri/__init__.py

@@ -15,4 +15,4 @@ __all__ = [
     "discover",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{pycentauri-0.1.0 → pycentauri-0.2.0}/src/pycentauri/cli.py

@@ -55,9 +55,21 @@ def _echo_err(msg: str) -> None:
     typer.echo(msg, err=True)
 
 
-async def _resolve_host(host: str | None) -> str:
+async def _resolve_target(host: str | None) -> tuple[str, str | None]:
+    """Return (host, mainboard_id). Mainboard_id may be None if discovery failed.
+
+    Always runs a brief UDP discovery so we can pre-seed the mainboard ID on
+    ``Printer.connect()`` — the printer doesn't push Attributes in paused/
+    errored states, and without a mainboard ID every command would hang.
+    """
     if host:
-        return host
+        # Short discovery to learn the mainboard; don't fail if it times out.
+        found = await discover_printers(timeout=1.0, retries=2)
+        for p in found:
+            if p.host == host and p.mainboard_id:
+                return host, p.mainboard_id
+        return host, None
+
     found = await discover_printers(timeout=2.5)
     if not found:
         _echo_err("No printers found on the LAN. Pass --host explicitly.")
@@ -67,7 +79,7 @@ async def _resolve_host(host: str | None) -> str:
         for p in found:
             _echo_err(f"  {p.host}  {p.machine_name or '?'}  {p.firmware_version or '?'}")
         raise typer.Exit(code=2)
-    return found[0].host
+    return found[0].host, found[0].mainboard_id
 
 
 def _run(coro: asyncio.coroutines.Coroutine[object, object, object]) -> object:  # type: ignore[name-defined]
@@ -128,8 +140,8 @@ def cmd_status(host: HostOpt = None, as_json: JsonOpt = False) -> None:
     """Print the printer's current status once and exit."""
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, mainboard_id=mid) as printer:
             st = await printer.status()
         if as_json:
             typer.echo(json.dumps(st.raw, indent=2, default=str))
@@ -178,8 +190,8 @@ def cmd_watch(
     """Stream live status updates until interrupted (Ctrl-C)."""
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h, push_period_ms=period_ms) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, push_period_ms=period_ms, mainboard_id=mid) as printer:
             async for st in printer.watch():
                 if as_json:
                     typer.echo(json.dumps(st.raw, default=str))
@@ -201,8 +213,8 @@ def cmd_attributes(host: HostOpt = None, as_json: JsonOpt = False) -> None:
     """Print the printer's attributes (model, firmware, capabilities)."""
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, mainboard_id=mid) as printer:
             attrs = await printer.attributes()
         if as_json:
             typer.echo(json.dumps(attrs.raw, indent=2, default=str))
@@ -226,8 +238,8 @@ def cmd_snapshot(
     """Save a JPEG snapshot from the built-in webcam."""
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, mainboard_id=mid) as printer:
             jpeg = await printer.snapshot(timeout=timeout)
         if str(out) == "-":
             sys.stdout.buffer.write(jpeg)
@@ -266,8 +278,8 @@ def cmd_print_start(
         raise typer.Exit(code=2)
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h, enable_control=True) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, enable_control=True, mainboard_id=mid) as printer:
             result = await printer.start_print(
                 filename, storage=storage, auto_leveling=auto_leveling, timelapse=timelapse
             )
@@ -284,8 +296,8 @@ def cmd_print_pause(host: HostOpt = None, enable_control: ControlOpt = False) ->
         raise typer.Exit(code=2)
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h, enable_control=True) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, enable_control=True, mainboard_id=mid) as printer:
             await printer.pause()
         typer.echo("paused")
 
@@ -300,8 +312,8 @@ def cmd_print_resume(host: HostOpt = None, enable_control: ControlOpt = False) -
         raise typer.Exit(code=2)
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h, enable_control=True) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, enable_control=True, mainboard_id=mid) as printer:
             await printer.resume()
         typer.echo("resumed")
 
@@ -316,14 +328,46 @@ def cmd_print_stop(host: HostOpt = None, enable_control: ControlOpt = False) ->
         raise typer.Exit(code=2)
 
     async def run() -> None:
-        h = await _resolve_host(host)
-        async with await Printer.connect(h, enable_control=True) as printer:
+        h, mid = await _resolve_target(host)
+        async with await Printer.connect(h, enable_control=True, mainboard_id=mid) as printer:
             await printer.stop()
         typer.echo("stop sent")
 
     _run(run())
 
 
+@app.command("server")
+def cmd_server(
+    host: HostOpt = None,
+    bind: str = typer.Option(
+        "127.0.0.1", "--bind", help="Interface to bind. Use 0.0.0.0 to expose on LAN."
+    ),
+    port: int = typer.Option(8787, "--port", "-p"),
+    enable_control: ControlOpt = False,
+    log_level: str = typer.Option("info", "--log-level"),
+) -> None:
+    """Run the HTTP + SSE server (requires `pip install 'pycentauri[server]'`)."""
+    try:
+        from pycentauri.server import run as run_server
+    except ImportError as err:
+        _echo_err("Server support not installed. Install with: pip install 'pycentauri[server]'")
+        _echo_err(f"(missing dependency: {err})")
+        raise typer.Exit(code=1) from err
+
+    async def resolve() -> tuple[str, str | None]:
+        return await _resolve_target(host)
+
+    h, mid = asyncio.run(resolve())
+    run_server(
+        h,
+        bind=bind,
+        port=port,
+        enable_control=enable_control,
+        mainboard_id=mid,
+        log_level=log_level,
+    )
+
+
 @app.command("mcp")
 def cmd_mcp(
     enable_control: ControlOpt = False,

{pycentauri-0.1.0 → pycentauri-0.2.0}/src/pycentauri/client.py

@@ -69,6 +69,7 @@ class Printer:
         *,
         enable_control: bool = False,
         push_period_ms: int = DEFAULT_PUSH_PERIOD_MS,
+        mainboard_id: str | None = None,
     ) -> None:
         self.host = host
         self.enable_control = enable_control
@@ -76,9 +77,11 @@ class Printer:
 
         self._ws: ClientConnection | None = None
         self._reader: asyncio.Task[None] | None = None
-        self._mainboard_id: str | None = None
+        self._mainboard_id: str | None = mainboard_id or None
 
         self._mainboard_event = asyncio.Event()
+        if self._mainboard_id:
+            self._mainboard_event.set()
         self._latest_status: Status | None = None
         self._latest_status_event = asyncio.Event()
         self._latest_attributes: Attributes | None = None
@@ -96,9 +99,23 @@ class Printer:
         enable_control: bool = False,
         push_period_ms: int = DEFAULT_PUSH_PERIOD_MS,
         connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        mainboard_id: str | None = None,
     ) -> 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)
+        """Open a WebSocket to the printer and start the reader task.
+
+        ``mainboard_id`` lets callers pre-seed the printer's serial/mainboard
+        identifier (e.g. from a prior discovery). When set, the client will
+        not wait for the printer's spontaneous ``Attributes`` push before
+        sending commands — which matters in paused/error states, where the
+        firmware doesn't push Attributes until prompted, and every command
+        requires ``MainboardID`` in its envelope.
+        """
+        self = cls(
+            host,
+            enable_control=enable_control,
+            push_period_ms=push_period_ms,
+            mainboard_id=mainboard_id,
+        )
         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}")
@@ -125,20 +142,26 @@ class Printer:
         return self._mainboard_id
 
     async def wait_for_mainboard(self, timeout: float = 5.0) -> str:
-        """Block until the printer has reported its mainboard ID."""
+        """Block until the printer has reported its mainboard ID.
+
+        Returns immediately if ``mainboard_id=`` was passed to
+        :meth:`connect`. Otherwise waits for the first ``Attributes`` push
+        from the printer. The printer only pushes Attributes spontaneously
+        in idle/active states — when paused or errored it stays silent until
+        asked, so callers that run in those states should pass ``mainboard_id``
+        explicitly (e.g. from a prior :func:`pycentauri.discover`).
+        """
         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)
+        try:
+            await asyncio.wait_for(self._mainboard_event.wait(), timeout=timeout)
+        except asyncio.TimeoutError as err:
+            raise PrinterError(
+                "printer did not push Attributes within "
+                f"{timeout}s. Pass mainboard_id=... to Printer.connect() "
+                "(discover() provides one) — the firmware does not push "
+                "Attributes while paused or errored."
+            ) from err
         assert self._mainboard_id is not None
         return self._mainboard_id
 

{pycentauri-0.1.0 → pycentauri-0.2.0}/src/pycentauri/discovery.py

@@ -68,19 +68,22 @@ async def discover(
     timeout: float = DEFAULT_TIMEOUT,
     broadcast_address: str = "255.255.255.255",
     port: int = DISCOVERY_PORT,
+    retries: int = 3,
 ) -> 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.
+    de-duplicated by source IP. The probe is retransmitted ``retries`` times
+    at evenly-spaced intervals within the timeout window, since UDP probes
+    can be dropped on busy or congested networks. 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.bind(("0.0.0.0", 0))
     sock.setblocking(False)
 
     transport, protocol = await loop.create_datagram_endpoint(
@@ -88,8 +91,15 @@ async def discover(
         sock=sock,
     )
     try:
-        transport.sendto(DISCOVERY_PROBE, (broadcast_address, port))
-        await asyncio.sleep(timeout)
+        tries = max(1, retries)
+        interval = timeout / max(tries, 1) / 2
+        for _ in range(tries):
+            transport.sendto(DISCOVERY_PROBE, (broadcast_address, port))
+            await asyncio.sleep(interval)
+        # Listen for the remainder of the budget for late replies.
+        remaining = max(0.0, timeout - interval * tries)
+        if remaining:
+            await asyncio.sleep(remaining)
     finally:
         transport.close()