pycentauri 0.5.1__tar.gz → 0.6.0__tar.gz

{pycentauri-0.5.1 → pycentauri-0.6.0}/CHANGELOG.md

@@ -6,6 +6,130 @@ Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-05
+
+### Added
+- **Centauri Carbon 2 support.** The CC2 uses MQTT on port 1883
+  (instead of the CC1's WebSocket SDCP on 3030) with a JSON-RPC
+  envelope, X-Token auth, and a completely different command set
+  (1001/1002/1020–1031 vs 0/1/128–512). This release adds:
+  - `CC2Printer` — async MQTT client that subclasses `Printer`,
+    translating CC2 payloads into the same `Status` / `Attributes`
+    models so every surface (CLI, HTTP, MCP, web UI) works unchanged.
+  - `connect_auto(host, access_code=...)` — factory that detects the
+    model (probes `:1883` only — a CC1 answers with a harmless kernel
+    RST, and the CC1's real WebSocket connect doubles as its own probe)
+    and returns the right `Printer` subclass. Callers never need to
+    know which model they're talking to.
+  - `--access-code` / `PYCENTAURI_ACCESS_CODE` on every CLI command
+    and MCP launch (required for CC2, ignored for CC1).
+  - `paho-mqtt>=2.0` added to core dependencies.
+- CC2 status exposes `gcode_move.speed` — live head speed as the
+  commanded speed of the current move, in mm/min (÷60 matches the
+  printer screen's mm/s readout)
+  and `speed_mode` (integer 0–3) — fields the CC1 lacks entirely. Both
+  are preserved in `Status.raw["_cc2"]` alongside `remaining_time_sec`,
+  `filament_detected`, `external_device`, and `exception_status`.
+- CC2 methods 1028 (SET_TEMPERATURE), 1029 (SET_LIGHT), 1030
+  (SET_FAN_SPEED), 1031 (SET_PRINT_SPEED), 1023 (RESUME), and 1036
+  (PRINT_TASK_LIST) all confirmed working. 1042 (VIDEO_STREAM) and
+  1044 (GET_FILE_LIST) are non-responsive on firmware 01.03.02.51.
+- **Canvas multi-filament system integration (CC2 only):**
+  - `Printer.canvas_status()` — returns `CanvasStatus` with connected
+    units, tray list (filament name/type/color/brand/temp range/loaded
+    status), active tray, and auto-refill state. Method 2005.
+  - `Printer.set_auto_refill(enabled)` — toggles auto-refill. Method
+    2004. Gated by `enable_control`.
+  - CLI: `centauri canvas` (read) + `centauri refill --on/--off`
+    (write, requires `--enable-control`).
+  - HTTP: `GET /canvas` (always) + `POST /canvas/refill` (control-gated).
+  - MCP: `get_canvas_status` (always) + `set_auto_refill` (control-gated).
+  - `CanvasStatus`, `CanvasUnit`, `CanvasTray` model classes exported
+    from the package for typed access.
+
+### Fixed (pre-release hardening — none of these shipped in an earlier release)
+- **CC1 `status()`/`watch()` self-heal through a wedged push
+  scheduler.** Discovered live 2026-07-04 on V0.3.0-o: the firmware can
+  enter a state where `Cmd 512` subscribes are accepted but no status
+  frames are ever pushed, while the request path stays healthy — and a
+  reboot does not clear it (verified 2026-07-05). Both methods now fall
+  back to explicit `Cmd 0` status requests (documented to emit a
+  one-shot status frame) whenever a subscribe produces no push within
+  one period, instead of hanging forever. See `docs/PROTOCOL.md`
+  "Operational quirks".
+- `CC2Printer.watch()` now polls method 1002 inline whenever pushes go
+  quiet instead of silently terminating after one push period — CC2
+  `centauri watch` and the SSE stream no longer die on an idle printer.
+- MQTT responses are correlated by the client's exact `api_response`
+  topic and non-push method. Previously any client's response — or the
+  printer's own 6000/6008 broadcasts, which reuse small auto-increment
+  ids — could resolve a pending request future with the wrong payload
+  (including reporting success for a control command).
+- Registration is re-published from `_on_connect`, so paho's automatic
+  MQTT reconnect re-registers with the printer and pushes survive a
+  printer reboot without restarting `centauri server`.
+- All MQTT-callback work that touches futures, events, queues, or the
+  merged status dict is marshalled onto the asyncio loop (fixes the
+  cross-thread delta merge and late `set_result` races).
+- `GET /stream` uses a bounded connect timeout (read stays unbounded
+  for MJPEG) instead of hanging forever against a wedged camera port.
+- `GET /canvas` returns 504 for printer timeouts, reserving 501 for
+  "no Canvas on this printer"; the web UI now retries transient Canvas
+  failures instead of hiding the panel until a page reload.
+- A wrong CC2 access code now raises a clear auth error (MQTT reason
+  code / HTTP 401 hint) instead of a generic timeout or raw traceback.
+- `connect_auto()` and `centauri rtsp` no longer probe :3030 — the CC1
+  WebSocket connect doubles as the probe, avoiding the connect/close
+  churn that port is sensitive to. `centauri rtsp` and the HTTP server
+  both pick the right MJPEG port (CC1 :3031 / CC2 :8080) automatically,
+  including reconnects after starting with the printer offline.
+- Unknown CC2 `machine_status` values map to sentinel code 99 instead
+  of leaking raw values into the CC1 status-code space; `PrintStatus`
+  gains constants for the CC2 codes 27/28/29.
+- `CanvasStatus.from_payload` survives malformed/absent `canvas_info`
+  payloads; `CanvasUnit`/`CanvasTray` are exported from the package
+  root; `typing_extensions` declared as a direct dependency.
+- **CC2 sessions send the app-level `{"type": "PING"}` keepalive every
+  30 s.** The firmware expires a client's registration after several
+  quiet minutes and then silently stops answering that session's
+  requests — the MQTT connection stays up, responses just never come
+  (verified 2026-07-05: a dashboard went request-deaf after ~6 minutes
+  while a fresh session answered instantly). MQTT-level keepalive does
+  not prevent this; only the app-level PING does.
+- `centauri server` bounds uvicorn's graceful shutdown at 5 s. Open
+  SSE/MJPEG streams never close on their own, and without the bound a
+  stopped server lingered forever as a zombie still holding a printer
+  connection (observed 2026-06-23 and 2026-07-05).
+- CC2 lifecycle commands (start/pause/stop/resume) use a 90 s timeout —
+  the firmware answers only after the mechanical sequence completes
+  (observed 2026-07-05: a resume succeeded but its confirmation
+  arrived after the old 15 s window, surfacing a false error). When a
+  confirmation still doesn't arrive, `POST /print/*` returns 504
+  ("sent, unconfirmed — check printer status") instead of 502, and the
+  web UI shows it as a warning rather than a failure.
+
+### Tests
+- New `tests/test_cc2_mapping.py`: pure dict-in/dict-out coverage of
+  the CC2→CC1 translation layer — machine_status/sub_status mapping
+  (including purge-zone filament-switch detection and its progress
+  guard), partial-delta deep merge, full 1002 payload round-trip, and
+  Canvas parsing. Plus a server test pinning `GET /canvas` → 501 on
+  CC1.
+
+### Documentation
+- `docs/PROTOCOL.md` gains a full CC2 section: MQTT transport, topic
+  structure, connection/registration dance, the confirmed method table
+  (12 probed, 10 working), error codes, the complete status payload,
+  and a CC1-vs-CC2 comparison table. Probed on 2026-06-30 through
+  2026-07-04 against firmware 01.03.02.51 (Canvas methods 2004/2005
+  verified live with a 4-slot Canvas attached; CC2 webcam confirmed
+  unauthenticated MJPEG on :8080).
+- `docs/ARCHITECTURE.md` rewritten for the two-transport reality:
+  module map with `cc2`/`connect`, per-model ports, CC1-vs-CC2
+  `/status` and SSE flow differences, and an honest test-architecture
+  section (no automated live suite exists; live verification is manual
+  CLI runs).
+
 ## [0.5.1] - 2026-06-17
 
 ### Added

pycentauri-0.6.0/PKG-INFO

@@ -0,0 +1,470 @@
+Metadata-Version: 2.4
+Name: pycentauri
+Version: 0.6.0
+Summary: Local-network toolkit for Elegoo Centauri Carbon 3D printers: async Python client, CLI, MCP server, REST/SSE HTTP server, web UI, and RTSP bridge
+Project-URL: Homepage, https://github.com/bjan/pycentauri
+Project-URL: Repository, https://github.com/bjan/pycentauri
+Project-URL: Issues, https://github.com/bjan/pycentauri/issues
+Project-URL: Changelog, https://github.com/bjan/pycentauri/blob/main/CHANGELOG.md
+Author: Brandon
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: 3d-printing,centauri,centauri-carbon,elegoo,mcp,sdcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Printing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Requires-Dist: typing-extensions>=4.6
+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
+
+Local-network toolkit for [Elegoo Centauri Carbon](https://www.elegoo.com/)
+3D printers — the **original Centauri Carbon (CC1)** and the **Centauri
+Carbon 2 (CC2)**. One async client, six surfaces: Python library, CLI,
+MCP server for AI agents, REST/SSE HTTP server, built-in web dashboard,
+and an RTSP bridge for your NVR.
+
+No cloud account, no Elegoo servers — everything talks directly to the
+printer on your LAN. `pycentauri` auto-detects which model it's talking
+to and speaks the right protocol:
+
+| | CC1 | CC2 |
+|---|---|---|
+| Transport | SDCP v3 over WebSocket (`:3030`) | JSON-RPC over MQTT (`:1883`) |
+| Auth | none | access code (printer screen) |
+| Discovery | UDP broadcast | direct IP + HTTP bootstrap |
+| Webcam | MJPEG `:3031` | MJPEG `:8080` |
+| Live head speed | — | ✓ (`gcode_move.speed` ÷ 60 = the screen's mm/s readout) |
+| Fan channels | 3 | 5 |
+| Canvas multi-filament | — | ✓ (status + auto-refill) |
+| Filament-switch detection | — | ✓ (position-based) |
+
+> **Status:** alpha, but used daily against real printers. Protocols were
+> reverse-engineered from Elegoo's official
+> [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK, the
+> [`CentauriLink`](https://github.com/CentauriLink/Centauri-Link) project,
+> and live wire captures. CC1 tested on firmware V1.1.46 and OpenCentauri
+> V0.3.0-o; CC2 tested on firmware 01.03.02.51. Full wire-protocol notes
+> live in [`docs/PROTOCOL.md`](docs/PROTOCOL.md).
+
+## Install
+
+```sh
+pip install pycentauri                    # library + CLI
+pip install "pycentauri[mcp]"             # + MCP server
+pip install "pycentauri[server]"          # + HTTP REST/SSE server + web UI
+pip install "pycentauri[mcp,server]"      # all Python surfaces
+```
+
+The RTSP bridge additionally requires
+[MediaMTX](https://github.com/bluenviron/mediamtx/releases) and `ffmpeg`
+on `$PATH`.
+
+Python 3.10+. Core dependencies: `websockets`, `paho-mqtt`, `httpx`,
+`typer`, `pydantic`.
+
+## Connecting to your printer
+
+**CC1** needs only its IP (or nothing at all — it answers UDP discovery).
+
+**CC2** needs its IP *and* its access code, found on the printer's
+touchscreen under network/connectivity settings. Pass it as
+`--access-code` / `access_code=` / `PYCENTAURI_ACCESS_CODE`. The examples
+below use `Ab3dEf` as a stand-in — substitute your own.
+
+Every CLI command accepts `--host` (env: `PYCENTAURI_HOST`). With no host
+given, commands try UDP discovery, which only finds CC1s.
+
+## CLI
+
+```sh
+# Discovery (CC1 only — CC2 doesn't answer broadcasts)
+centauri discover
+
+# Status, attributes, live watch, snapshot
+centauri status     --host 192.168.1.209                        # CC1
+centauri status     --host 192.168.1.189 --access-code Ab3dEf   # CC2
+centauri status     --host 192.168.1.209 --json
+centauri attributes --host 192.168.1.209
+centauri watch      --host 192.168.1.209
+centauri snapshot   --host 192.168.1.209 shot.jpg
+
+# Print control — all writes require --enable-control
+centauri print start cube.gcode --host 192.168.1.209 --enable-control
+centauri print pause            --host 192.168.1.209 --enable-control
+centauri print resume           --host 192.168.1.209 --enable-control
+centauri print stop             --host 192.168.1.209 --enable-control
+
+# Live adjust while printing
+centauri speed sport                            --host 192.168.1.209 --enable-control
+centauri fan  --model 100 --aux 60 --chamber 30 --host 192.168.1.209 --enable-control
+centauri temp --nozzle 215 --bed 60             --host 192.168.1.209 --enable-control
+
+# Canvas multi-filament (CC2 only)
+centauri canvas       --host 192.168.1.189 --access-code Ab3dEf
+centauri refill --on  --host 192.168.1.189 --access-code Ab3dEf --enable-control
+```
+
+`centauri canvas` prints each tray's filament, color, temperature range,
+and loaded state:
+
+```
+auto_refill  : OFF
+active_tray  : none
+connected    : yes
+
+canvas #0:
+  ● tray 0: PLA Wood (PLA) #F72221 [190-230°C]
+  ● tray 1: PLA Wood (PLA) #AF7832 [190-230°C]
+  ● tray 2: PETG (PETG) #A03BF7 [230-260°C]
+  ● tray 3: PLA Wood (PLA) #D2C5A3 [190-230°C]
+```
+
+### Speed modes
+
+Both printers accept exactly four speed settings — arbitrary percentages
+are silently ignored by the firmware:
+
+| Mode | CC1 wire value (`PrintSpeedPct`) | CC2 wire value (`speed_mode`) |
+|---|---|---|
+| `silent` | 50 | 0 |
+| `balanced` | 100 | 1 |
+| `sport` | 130 | 2 |
+| `ludicrous` | 160 | 3 |
+
+Speed changes only take effect while a print is actively running.
+
+## Python library
+
+```python
+import asyncio
+from pycentauri import Printer, CC2Printer, connect_auto
+
+async def main():
+    # Explicit CC1
+    async with await Printer.connect("192.168.1.209") as printer:
+        st = await printer.status()
+        print(st.print_status, st.progress, st.temp_nozzle)
+
+    # Explicit CC2
+    async with await CC2Printer.connect("192.168.1.189", access_code="Ab3dEf") as printer:
+        st = await printer.status()
+        print(st.temp_nozzle, st.raw["_cc2"]["gcode_move_speed"])  # mm/min; ÷60 = screen's mm/s
+
+        canvas = await printer.canvas_status()
+        for unit in canvas.canvas_list:
+            for tray in unit.tray_list:
+                print(tray.tray_id, tray.filament_name, tray.filament_color)
+
+    # Auto-detect — port-probes :3030 vs :1883 and returns the right class
+    async with await connect_auto("192.168.1.189", access_code="Ab3dEf") as printer:
+        attrs = await printer.attributes()
+        print(attrs.machine_name, attrs.firmware_version)
+
+asyncio.run(main())
+```
+
+Both classes expose the same API: `status()`, `attributes()`, `watch()`
+(async iterator of live status), `snapshot()`, `start_print()`, `pause()`,
+`resume()`, `stop()`, `set_print_speed()`, `set_fan_speed()`,
+`set_temperatures()`, `canvas_status()`, `set_auto_refill()`. Write
+methods require `enable_control=True` at connect time and raise
+`ControlDisabledError` otherwise. Canvas methods raise `PrinterError` on
+CC1 (no Canvas support over SDCP).
+
+CC2-only telemetry rides along in `Status.raw["_cc2"]`: the live head
+speed (`gcode_move_speed` — the commanded speed of the current move in
+**mm/min**; divide by 60 for the mm/s figure the printer's screen
+shows), `speed_mode`, filament runout sensor state,
+firmware-computed `remaining_time_sec`, `machine_status`/`sub_status`
+raw codes, and `external_device` (camera / U-disk presence).
+
+## HTTP server + web UI
+
+```sh
+# Read-only, loopback only
+centauri server --host 192.168.1.209
+
+# Read + write + RTSP, on the LAN (put an authenticating proxy in front)
+centauri server --host 192.168.1.209 --bind 0.0.0.0 --port 8787 \
+                --enable-control --rtsp
+
+# CC2
+centauri server --host 192.168.1.189 --access-code Ab3dEf \
+                --bind 0.0.0.0 --port 8787 --enable-control
+```
+
+The server holds a single long-lived connection to the printer
+(WebSocket for CC1, MQTT for CC2) with automatic reconnect and
+exponential backoff — it will never exhaust CC1's 5-connection limit.
+
+The **web UI** at `/ui/` is a clean dark dashboard, mobile-friendly and
+dependency-free (no CDN assets — works on an air-gapped LAN): live
+webcam, job progress with layer/ETA, printer state, thermals, kinematics
+(with live head speed on CC2), pause/resume/stop, speed-mode selector,
+fan and heater sliders that hydrate from live values, a Canvas panel
+with per-tray color swatches and an auto-refill toggle (CC2), and RTSP
+bridge controls. Control panels only render when the server was started
+with `--enable-control`.
+
+### Endpoints
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/` | Redirects to `/ui/` |
+| `GET` | `/ui/` | Web dashboard |
+| `GET` | `/api/info` | Health + version + connection state |
+| `GET` | `/status` | Latest status (typed summary + full `raw` payload) |
+| `GET` | `/attributes` | Model, firmware, mainboard ID |
+| `GET` | `/snapshot` | Single JPEG frame |
+| `GET` | `/stream` | MJPEG proxy (drop into an `<img>` tag) |
+| `GET` | `/events/status` | Server-Sent Events stream of status pushes |
+| `GET` | `/discover` | UDP LAN scan (finds CC1s) |
+| `GET` | `/canvas` | Canvas state (CC2; `501` on CC1) |
+| `GET` | `/docs`, `/redoc` | OpenAPI documentation |
+| `POST` | `/print/start` | `{"filename": "cube.gcode", "storage": "local"}` † |
+| `POST` | `/print/pause` · `/print/resume` · `/print/stop` | † |
+| `POST` | `/print/speed` | `{"mode": "sport"}` or `{"mode": 130}` † |
+| `POST` | `/print/fan` | `{"model": 50, "auxiliary": 30, "chamber": 0}` — any subset, 0–100 † |
+| `POST` | `/print/temperature` | `{"nozzle": 215, "bed": 60}` — any subset, °C, 0 = off † |
+| `POST` | `/canvas/refill` | `{"enabled": true}` (CC2) † |
+| `GET` | `/api/rtsp` | RTSP bridge state (when `--rtsp`) |
+| `POST` | `/api/rtsp/start` · `/api/rtsp/stop` | Toggle the bridge (when `--rtsp`) |
+
+† requires the server to be launched with `--enable-control`; otherwise
+the route isn't registered at all.
+
+Temperature writes are bounds-checked server-side: nozzle 0–300 °C,
+bed 0–110 °C, chamber 0–60 °C.
+
+## MCP server (AI agents)
+
+Give Claude Code, Claude Desktop, Cursor, or any MCP client eyes and
+hands on your printer:
+
+```sh
+# Read-only (status, snapshot, attributes, discovery, canvas)
+claude mcp add pycentauri --env PYCENTAURI_HOST=192.168.1.209 \
+    -- python -m pycentauri.mcp
+
+# With control tools
+claude mcp add pycentauri-cc2 \
+    --env PYCENTAURI_HOST=192.168.1.189 \
+    --env PYCENTAURI_ACCESS_CODE=Ab3dEf \
+    -- python -m pycentauri.mcp --enable-control
+```
+
+The target host is pinned in the server's environment at spawn time — a
+prompt-injected agent cannot redirect commands to an arbitrary IP,
+because no tool takes a host parameter.
+
+| Tool | Availability | Description |
+|---|---|---|
+| `get_status` | always | State, temps, progress, layer, position, fans |
+| `get_attributes` | always | Model, firmware, mainboard ID |
+| `get_snapshot` | always | Webcam frame as MCP image — the model *sees* the print |
+| `discover_printers` | always | UDP LAN scan |
+| `get_canvas_status` | always | Canvas trays, colors, auto-refill (CC2) |
+| `start_print` | `--enable-control` | Start a file already on the printer |
+| `pause_print` / `resume_print` / `stop_print` | `--enable-control` | Job control |
+| `set_print_speed` | `--enable-control` | `silent`/`balanced`/`sport`/`ludicrous` |
+| `set_fan_speed` | `--enable-control` | Any subset of model/aux/chamber, 0–100% |
+| `set_temperatures` | `--enable-control` | Any subset of nozzle/bed/chamber, °C |
+| `set_auto_refill` | `--enable-control` | Canvas auto-refill toggle (CC2) |
+
+Control tools aren't merely gated — without the flag they are never
+registered, so they don't appear in the model's tool list at all.
+
+## RTSP bridge
+
+Re-streams the printer's MJPEG webcam as H.264/RTSP for clients that
+don't speak MJPEG — Home Assistant, Frigate, Jellyfin, Synology
+Surveillance, VLC:
+
+```sh
+# Standalone (foreground, Ctrl-C to stop)
+centauri rtsp --host 192.168.1.209
+# → rtsp://<this-host>:8554/printer
+
+# Integrated with the HTTP server — adds a STREAM panel to the web UI
+centauri server --host 192.168.1.209 --rtsp --bind 0.0.0.0
+```
+
+MediaMTX only runs the ffmpeg transcode while a client is connected, so
+idle cost is zero. Tunables: `--fps`, `--bitrate`, `--preset`, `--path`,
+`--port` (standalone) or the `--rtsp-*` variants on `centauri server`.
+The bridge picks the correct camera port for CC1 vs CC2 automatically.
+
+## Print status codes
+
+`print_status` in the API and library uses the CC1 firmware's code
+space, extended with three codes for CC2 Canvas operations:
+
+| Code | Meaning | | Code | Meaning |
+|---|---|---|---|---|
+| 0 | Idle | | 13 | Printing |
+| 1 | Homing | | 14 | Error |
+| 5 | Pausing | | 15 | Leveling |
+| 6 | Paused | | 16 | Preheating |
+| 7 | Stopping | | **27** | **Switching filament** (CC2) |
+| 8 | Stopped | | **28** | **Filament load complete** (CC2) |
+| 9 | Completed | | **29** | **Unloading filament** (CC2) |
+
+The full table (including CC1's resin-inherited codes) is in
+[`docs/PROTOCOL.md`](docs/PROTOCOL.md).
+
+On the CC2, mid-print Canvas filament switches are detected by head
+position: the firmware never fully leaves its "printing" state during a
+switch, but the head parks at the purge chute behind the bed (y ≥ 258 mm,
+physically outside the printable area) for the duration. pycentauri
+reports code 27 the entire time the head is parked there mid-print.
+
+## Safety model
+
+- **Explicit opt-in for writes.** Every surface requires
+  `enable_control=True` / `--enable-control` before any state-changing
+  command is possible. Read-only is the default everywhere.
+- **Bounds-checked heaters.** The library refuses temperature targets
+  outside nozzle 0–300 °C / bed 0–110 °C / chamber 0–60 °C even though
+  the firmware might accept them.
+- **Unauthenticated HTTP surface.** The REST server has no auth of its
+  own. Bind it to loopback (the default) or put an authenticating
+  reverse proxy in front before exposing it beyond localhost.
+- **You own unattended printing.** An agent with control tools can pause,
+  stop, or heat your printer. Leaving one unattended is your call.
+
+## Known firmware quirks
+
+### CC1 (original Centauri Carbon)
+
+- **5 concurrent WebSocket slots, hard.** The 6th connection gets HTTP
+  500 `"too many client"`. Slots free on close. The CLI opens one per
+  invocation; the HTTP/MCP servers hold exactly one long-lived slot.
+- **Paused/errored states don't push Attributes.** Every SDCP command
+  needs the printer's `MainboardID`, which normally arrives in an
+  Attributes push — but not while paused or errored. pycentauri
+  pre-seeds it from UDP discovery on every connect. If you call
+  `Printer.connect()` on a paused printer without discovery, pass
+  `mainboard_id=` yourself.
+- **Unknown commands crash the firmware.** A few unrecognised SDCP
+  commands in quick succession kill the printer's `app` daemon — and any
+  active print with it. Don't probe undocumented command codes against a
+  printer that's doing something you care about.
+- **The push scheduler goes dormant at idle (and a reboot doesn't wake
+  it).** The firmware can enter a state where `Cmd 512` subscribes are
+  acknowledged but no status frame is ever pushed while the printer
+  sits idle — persisting across reboots (verified 2026-07-05 on
+  V0.3.0-o). Starting a print revives pushes at full rate. One-shot
+  `Cmd 0` requests always work, so pycentauri automatically falls back
+  to polling when a subscribe goes quiet (~7 s updates at idle,
+  full-rate pushes while printing). Clients that rely purely on
+  subscribe pushes will hang forever on an idle printer in this state.
+
+### CC2 (Centauri Carbon 2)
+
+- **No UDP discovery.** The CC2 ignores broadcast probes; specify its IP
+  explicitly. Give it a static DHCP lease — it doesn't register a
+  hostname with most routers, so its address drifts otherwise.
+- **Access code required for MQTT**, passed as the password with
+  username `elegoo`. The HTTP bootstrap (`/system/info`) wants the same
+  code as an `X-Token` *query parameter* — it ignores the header form.
+- **The webcam is unauthenticated.** MJPEG on `:8080` (any path) is open
+  to anyone on your LAN, access code or not. That's the firmware's
+  choice, not ours.
+- **Rate limiting.** Rapid-fire MQTT requests (3+ back-to-back) trip a
+  cooldown of a few seconds during which the broker silently drops
+  responses. pycentauri's polling cadence stays under it; your scripts
+  should too.
+- **Registrations expire without an app-level PING.** The printer
+  forgets a registered client after several quiet minutes and silently
+  stops answering that session's requests — the MQTT connection itself
+  stays up, so there's no error to catch. pycentauri sends the SDK's
+  `{"type": "PING"}` keepalive every 30 s to hold the registration; if
+  you write your own client, you must too.
+- **File list (method 1044) and video stream (1042) don't respond** on
+  firmware 01.03.02.51, so remote print-start on CC2 requires knowing
+  the filename in advance.
+
+## Project layout & docs
+
+```
+src/pycentauri/
+├── client.py      # CC1: async SDCP-over-WebSocket client
+├── cc2.py         # CC2: async JSON-RPC-over-MQTT client (same API)
+├── connect.py     # connect_auto() — port-probe model detection
+├── sdcp.py        # SDCP v3 envelope build/parse
+├── discovery.py   # UDP broadcast discovery
+├── camera.py      # MJPEG frame grabber
+├── models.py      # Status / Attributes / CanvasStatus / PrintInfo
+├── cli.py         # Typer CLI
+├── server.py      # FastAPI app + connection supervisor
+├── rtsp.py        # MediaMTX/ffmpeg bridge
+├── mcp/           # FastMCP stdio server
+└── web/           # Static dashboard (no build step, no CDN)
+```
+
+- [`docs/PROTOCOL.md`](docs/PROTOCOL.md) — both wire protocols in
+  detail: envelopes, command/method tables with tested-on dates, status
+  payloads, error codes, failure modes, and a CC1-vs-CC2 comparison.
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — module map and
+  request flow.
+
+## Development
+
+```sh
+git clone https://github.com/bjan/pycentauri && cd pycentauri
+python -m venv .venv && .venv/bin/pip install -e ".[mcp,server,dev]"
+
+.venv/bin/ruff check . && .venv/bin/ruff format --check .
+.venv/bin/mypy src          # strict mode
+.venv/bin/pytest -q         # no printer required — tests use in-process fakes
+```
+
+Tests run against an in-process fake SDCP WebSocket server plus pure
+translation-layer tests for CC2; nothing in CI touches real hardware.
+Live verification against a physical printer is manual — `centauri
+status`, `centauri canvas`, and a fan write are the standard smoke
+test after protocol-layer changes.
+
+## Credits & license
+
+- Protocol references: Elegoo's
+  [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) SDK
+  (Apache-2.0) and
+  [`CentauriLink`](https://github.com/CentauriLink/Centauri-Link).
+- Licensed under Apache-2.0 — see [LICENSE](LICENSE).
+- Not affiliated with or endorsed by Elegoo. Reverse-engineered
+  protocols can break with any firmware update; nothing here is
+  warranted to keep your prints alive.