docs: add API.md and MANUAL.md, link them from README

API.md documents the full HTTP/WebSocket surface (Moonraker-compatible endpoints for Mainsail/Fluidd/OrcaSlicer/moonraker-obico compatibility, plus the bridge-specific /api and /kx routes) for integrators and plugin authors. MANUAL.md is a task-oriented end-user guide covering day-to-day usage: dashboard, printing, filament/AMS management, multi-printer setup, the power-switch feature, settings reference, and basic troubleshooting.
2026-08-02 23:00:30 +02:00
parent b37dfb4dcf
commit f54783ad16
3 changed files with 588 additions and 0 deletions
--- a/API.md
+++ b/API.md
@@ -0,0 +1,256 @@
+# KX-Bridge HTTP API Reference
+
+This document lists the HTTP and WebSocket surface exposed by
+`kobrax_moonraker_bridge.py`. It is a reference for integrators and
+plugin authors, not a tutorial — for day-to-day usage of the bridge see
+[MANUAL.md](MANUAL.md), and for setup see [README.md](README.md).
+
+The API has two distinct parts:
+
+1. **Moonraker-compatible surface** — a subset of the real
+   [Moonraker](https://moonraker.readthedocs.io/) HTTP + WebSocket API,
+   implemented just far enough to make Mainsail, Fluidd, OrcaSlicer, and
+   `moonraker-obico` work against the Kobra X. **This is not a full
+   Moonraker implementation** — many real Moonraker endpoints/methods do
+   not exist here, and some responses are static stubs that exist only
+   to stop a client from erroring/looping (noted below).
+2. **Bridge-specific surface** — `/api/...` and `/kx/...` endpoints for
+   things Moonraker has no concept of: multi-printer management, AMS/ACE
+   filament control, the GCode store, custom filament profile import,
+   Spoolman, and the smart-plug power switch.
+
+## Security
+
+**There is no authentication on any endpoint.** The bridge is designed
+to be run on a trusted local network only. Do not expose port `7125`
+(or any additional per-printer port) to the internet — anyone who can
+reach the port can control the printer, read/delete files, and read
+`/kx/printers` credentials indirectly through bridge behavior. `/access/api_key`
+returns a hardcoded dummy value purely so `moonraker-obico` doesn't warn;
+it is not a real credential.
+
+CORS is enabled (`_json_cors` / `handle_kx_options` add
+`Access-Control-Allow-*` headers and answer `OPTIONS` with 204) so the
+Web UI can call sibling bridge instances directly in multi-printer setups.
+
+---
+
+## Moonraker-compatible endpoints (HTTP)
+
+All responses follow Moonraker's `{"result": {...}}` envelope unless noted.
+
+| Method | Path | Purpose | Notes |
+|---|---|---|---|
+| GET | `/server/info` | Server/klippy status | Always reports `klippy_connected: true`, `klippy_state: "ready"` |
+| GET | `/printer/info` | Printer identity | Static hostname/paths; `software_version` from `KLIPPER_VERSION` |
+| GET | `/machine/system_info` | System info stub | Mostly static/placeholder fields |
+| GET | `/printer/objects/list` | List available printer objects | Keys of `_build_printer_objects()` |
+| GET | `/printer/objects/query?objects=...` | Query object status | Comma-separated `objects` query param, or bare query keys |
+| GET`/POST` | `/printer/objects/subscribe` | Subscribe (HTTP polling variant) | Returns full status snapshot immediately |
+| GET | `/server/files/list` | List gcode files | Only returns the single currently-tracked file (if any) |
+| GET | `/server/files/metadata?filename=...` | File metadata (layers, est. time, etc.) | Shared logic with WS `server.files.metadata`; falls back to GCode store / buried-report cache |
+| POST | `/server/files/upload` | Upload a gcode file (multipart) | Same handler as `/api/files/local` |
+| POST | `/printer/print/start?filename=...` | Start a print | Body may include `filament_assignments`, `excluded_objects`, `auto_leveling` |
+| POST | `/printer/print/pause` | Pause current print | |
+| POST | `/printer/print/resume` | Resume current print | |
+| POST | `/printer/print/cancel` | Cancel current print | |
+| GET | `/access/api_key` | Dummy API key | No real auth exists |
+| GET | `/machine/update/status` | Update-manager stub | Always `busy: false`, empty `version_info` |
+| GET | `/server/history/list?limit=` | Print job history | Backed by the bridge's own GCodeStore/job DB |
+| GET | `/server/webcams/list` | Webcam descriptor | Rewrites `localhost`/`127.0.0.1` Host header to the bridge's LAN IP so remote Obico/Mainsail instances get a reachable URL |
+| POST | `/printer/gcode/script` | Execute a (very limited) gcode command | See `_exec_gcode_script`; not a general gcode interpreter |
+| GET | `/server/database/item?namespace=&key=` | Moonraker "database" KV read | Real payload only for `lane_data` (AMS/filament sync for OrcaSlicer); stub/empty responses for `AFC`, `afc-install`, `happy_hare`, `mainsail`; in-memory KV for `obico` |
+| POST | `/server/database/item` | Moonraker "database" KV write | In-memory only (not persisted across restarts); used by `moonraker-obico` for its own settings |
+| GET | `/server/database/list` | List KV namespaces | Static: `["lane_data", "mainsail", "obico"]` |
+
+### OctoPrint-compatibility shim
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/version` | OctoPrint-style version probe (some tools check this instead of Moonraker) |
+| POST | `/api/files/local`, `/api/files/{path}` | Alias for the same multipart upload handler as `/server/files/upload` |
+
+### WebSocket JSON-RPC (`/websocket`)
+
+Moonraker's JSON-RPC 2.0 protocol over a single `/websocket` endpoint. On
+connect the bridge immediately pushes `notify_klippy_ready` and then
+periodic `notify_status_update` notifications. Supported `method` values:
+
+| Method | Purpose |
+|---|---|
+| `printer.info` / `printer_info` | Same payload as `/printer/info` |
+| `server.info` / `server_info` | Same payload as `/server/info` |
+| `printer.objects.list` | Same as HTTP equivalent |
+| `printer.objects.query` / `printer.objects.get` | Object status by requested keys |
+| `printer.objects.subscribe` | Returns a status snapshot (no real push subscription semantics — status pushes happen automatically via `notify_status_update`) |
+| `printer.print.start` | `params.filename` |
+| `printer.print.pause` / `.resume` / `.cancel` | |
+| `machine.system_info` | Minimal stub |
+| `server.files.list` | Always returns `[]` over WS (unlike the HTTP version) |
+| `printer.gcode.script` | `params.script`, same limited executor as the HTTP endpoint |
+| `server.connection.identify` | Returns a dummy `connection_id` for Obico's handshake |
+| `connection.register_remote_method` | Accepted and ignored (Obico registers a remote-event callback) |
+| `server.webcams.list` | Same shape as HTTP, using the bridge's own LAN IP |
+| `server.history.list` | Job history, same source as `/server/history/list` |
+| `machine.update.status` | Stub |
+| `server.files.metadata` | Same logic as `/server/files/metadata` |
+
+Any other method is logged and answered with an empty `result: {}` — it
+does not error, to avoid breaking clients that probe for optional
+methods.
+
+---
+
+## Bridge-specific endpoints
+
+All `/kx/...` (and most `/api/...`) responses use `{"result": ...}` on
+success and `{"error": "..."}` with a 4xx/5xx status on failure, except
+where noted.
+
+### Printer control (`/api/...`)
+
+| Method | Path | Purpose | Body / Query |
+|---|---|---|---|
+| POST | `/api/light` | Toggle chamber light | `{on, brightness}` |
+| POST | `/api/fan` | Set part-cooling fan speed | `{speed}` (0–100) |
+| POST | `/api/connect` | Manually (re)connect the MQTT client | — |
+| POST | `/api/disconnect` | Manually disconnect | — |
+| POST | `/api/restart` | Restart the bridge process | — |
+| POST | `/api/speed` | Set print speed mode | `{mode}` (int) |
+| POST | `/api/axis` | Jog an axis, or `{"action":"turnoff"}` to disable steppers | `{axis, move_type, distance}` |
+| POST | `/api/temperature` | Set nozzle/bed target temps | `{nozzle?, bed?}`; uses a different MQTT path mid-print vs. idle |
+| GET | `/api/state` | Full dashboard status snapshot | Primary polling endpoint used by the Web UI |
+| GET | `/api/camera` | Current camera stream URL | |
+| GET | `/api/camera/stream` | MJPEG live view | `multipart/x-mixed-replace`, fed from a shared ffmpeg fanout |
+| GET | `/api/camera/h264` | Raw H.264 stream (for Obico) | |
+| GET | `/api/camera/snapshot` | Last cached JPEG frame | Instant, served from RAM |
+| POST | `/api/camera/start` / `/api/camera/stop` / `/api/camera/reset` | Camera lifecycle control | `reset` clears the 429 backoff and restarts ffmpeg |
+| GET | `/api/settings` | Read current config.ini-backed settings | |
+| POST | `/api/settings` | Write settings, then restart the bridge | See config fields below |
+| GET | `/api/update/check` | Check Gitea releases for a newer version | Branches on nightly/dev/stable channel |
+| POST | `/api/update/apply` | Self-update (non-Docker builds only) | `{tag}` |
+| POST | `/api/file_ready/clear` | Dismiss the "file ready to print" banner/dialog state | |
+| GET | `/api/log/stream` | Server-Sent Events log tail | |
+| GET | `/api/log/download` | Download buffered log as plaintext | |
+| GET | `/serve/{filename}` | Internal file server used to hand the printer a URL to fetch gcode from | Not meant for direct browser use |
+
+**`/api/settings` fields** (POST body, all optional — merges into
+existing config.ini): `printer_ip`, `mqtt_port`, `username`, `password`,
+`mode_id`, `device_id`, `power_on_url`, `power_off_url`,
+`power_status_url`, `default_ams_slot`, `auto_leveling`,
+`vibration_compensation`, `camera_on_print`, `web_upload_warning`,
+`print_start_dialog`, `poll_interval`, `verbose_http_log`,
+`printer_name`, `spoolman_server`, `spoolman_sync_rate`,
+`ace_dry_presets`.
+
+### AMS / ACE filament control (`/api/...`)
+
+| Method | Path | Purpose | Body |
+|---|---|---|---|
+| POST | `/api/ams/set_slot` | Set material type + color for a slot | `{index, type, color:[r,g,b]}` |
+| POST | `/api/ams/feed` | Feed filament in/out | `{slot_index, type}` (1=feed in, 2=feed out) |
+| POST | `/api/ace/auto_feed` | Toggle auto-feed for an ACE unit | `{ace_id, on}` |
+| POST | `/api/ace/dry` | Start/stop the ACE dryer | `{action: "start"|"stop", ace_id?, target_temp?, duration?}` |
+
+### GCode store (bridge-managed uploads) (`/kx/files...`)
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/kx/files` | List files the bridge has stored, with last-print status/duration |
+| DELETE | `/kx/files/{file_id}` | Delete a stored file |
+| GET | `/kx/files/{file_id}/download` | Download a stored file |
+| POST | `/kx/files/{file_id}/verify` | Clear the "web upload, unverified" flag |
+| GET | `/kx/files/{id}/objects` | Print-object list + SVG preview (for the pre-print skip feature) |
+| GET | `/kx/history?limit=&offset=` | Paginated print job history |
+
+### Files on the printer's own storage (`/kx/printer-files...`)
+
+Distinct from the GCode store above — these list/manage files that live
+on the printer's internal storage (e.g. printed directly from Anycubic
+Slicer Next, bypassing the bridge).
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/kx/printer-files` | List files via the printer's `file/listLocal` MQTT action |
+| POST | `/kx/printer-files/delete` | Delete one or more files: `{"filenames": [...]}` (single endpoint for single + bulk delete) |
+| GET | `/kx/printer-files/{filename}/thumbnail` | Fetch (and cache) a file's embedded gcode thumbnail via `file/fileDetails` |
+
+### Printing (`/kx/print`)
+
+| Method | Path | Purpose | Body |
+|---|---|---|---|
+| POST | `/kx/print` | Start a print from a stored GCode-store file | `{file_id, filament_assignments?, excluded_objects?, auto_leveling?}` |
+
+`filament_assignments` is `[{slot_index, material, color_hex}, ...]`; if
+omitted, all currently-occupied AMS slots are auto-mapped.
+
+### Pre-print / mid-print object skip (`/kx/skip...`)
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/kx/skip` | Skip named objects mid-print: `{"names": [...]}` |
+| POST | `/kx/skip/query` | Re-request the object list from the printer and return merged skip state |
+| GET | `/kx/skip/state` | Current skip state (object list, already-skipped names, SVG, filename) |
+
+### Filament profiles (`/kx/filament/...`)
+
+| Method | Path | Purpose | Body / Query |
+|---|---|---|---|
+| GET | `/kx/filament/slots` | Current AMS slot contents + any user profile override | |
+| GET | `/kx/filament/profiles?type=&vendor=` | Curated OrcaSlicer filament profile catalog (system + user-imported) | Optional filters |
+| GET | `/kx/filament/profiles/user` | User-imported profiles only (for the settings management list) | |
+| POST | `/kx/filament/profiles/user` | Import profiles from a ZIP or `.json` file(s) (multipart) | Multipart field `file`/`files`/`upload`; ZIP entries or bare `.json`, parsed via `orca_filaments.parse_profile_bytes` |
+| DELETE | `/kx/filament/profiles/user?vendor=&name=` | Delete one user profile (both params) or all (no params) | |
+| POST | `/kx/filament/slots/{idx}/profile` | Assign (or clear) a fixed profile override for one AMS slot | `{vendor, name}`; empty strings clear the mapping. Selector is `(vendor, name)`, not `id` — IDs are not unique across the Orca profile catalog |
+| GET`/POST` | `/kx/filament/visible_vendors` | Get/set the vendor visibility filter for the slot profile dropdown | POST body `{"vendors": [...]}`; empty list = show all |
+
+### Spoolman integration (`/kx/spoolman/...`)
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/kx/spoolman/status` | Whether Spoolman is configured/reachable, server URL, sync rate, current slot→spool map |
+| GET | `/kx/spoolman/spools` | Proxied list of spools from the configured Spoolman server |
+| POST | `/kx/spoolman/active-spool` | Assign spool IDs to AMS slots: `{"slot_map": {"0": 42, "2": 17}}` (AMS slot index → Spoolman spool ID) |
+
+### Multi-printer management (`/kx/printers...`)
+
+| Method | Path | Purpose | Body |
+|---|---|---|---|
+| GET | `/kx/printers` | List all configured printers with online-ish metadata | |
+| POST | `/kx/printers/add` | Add a printer by IP (credentials auto-fetched from the printer) | `{printer_ip, name?}` — triggers a bridge restart |
+| DELETE | `/kx/printers/{pid}` | Remove a printer from config; renumbers remaining `[printer_N]` sections | — triggers a bridge restart |
+| POST | `/kx/printers/{pid}/power` | Toggle an external smart plug (Tasmota-style) for a printer | `{"action": "on"|"off"}` |
+| GET | `/kx/printers/{pid}/power-status` | Query the smart plug's current on/off state | |
+
+**Power switch is not the printer's own power state** — it's a plain
+`GET` fired at a user-configured `power_on_url` / `power_off_url` /
+`power_status_url` (e.g. a Tasmota `cmnd=Power%20on` URL). See
+[MANUAL.md](MANUAL.md#power-switch-feature) for details.
+It only exists for printers where `power_on_url` or `power_off_url` is
+set in config; `/kx/printers` exposes this as `has_power_control`.
+
+### Misc
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/kx/ui/{name}` | Serves theme assets (JS/CSS/vendored libs) and translation JSON files under the active UI theme |
+| GET | `/` , `/printer{N}` | Serves the Web UI (index.html with CSS/JS inlined for embedded-webview compatibility, e.g. OrcaSlicer's device tab) |
+| GET | `/favicon.ico` | Favicon |
+
+---
+
+## Response conventions
+
+- Moonraker-compatible endpoints wrap results as `{"result": {...}}` (or
+  `{"error": {"code": ..., "message": ...}}` for the `/server/database/*`
+  404 case) to match the real Moonraker schema.
+- Bridge-specific `/api/...` and `/kx/...` endpoints generally return
+  `{"result": ...}` on success and `{"error": "message"}` with a
+  non-2xx HTTP status on failure — but this is not universal; check the
+  handler in `kobrax_moonraker_bridge.py` if exact shape matters (route
+  registrations are near the end of the file, search for
+  `r.add_get(`/`r.add_post(`/`r.add_delete(`).
+- Endpoints that trigger a config write (`/api/settings`,
+  `/kx/printers/add`, `/kx/printers/{pid}` DELETE) restart the whole
+  bridge process shortly after responding — clients should expect a
+  brief connection drop.
--- a/MANUAL.md
+++ b/MANUAL.md
@@ -0,0 +1,330 @@
+# KX-Bridge User Manual
+
+This is a day-to-day how-to guide for using KX-Bridge once it's running.
+For installing/updating the bridge itself, see [README.md](README.md).
+For the HTTP/WebSocket API (developers, plugin authors, integrators), see
+[API.md](API.md).
+
+---
+
+## Getting Started
+
+### Install and start the bridge
+
+Follow the Quick Start in [README.md](README.md#-quick-start) — the short
+version is:
+
+```bash
+docker compose up -d
+```
+
+then open `http://BRIDGE-IP:7125` in a browser.
+
+### Connect to your printer for the first time
+
+1. On the printer's display: **Settings → Enable LAN mode**.
+2. In the bridge Web UI, the **Printers** tab shows **"+ Add printer"** on
+   first start. Click it, enter the printer's IP address, and confirm —
+   username, password and device ID are fetched from the printer and
+   decrypted automatically. No manual credential entry needed.
+3. Click **⚡ Connect** in the top-right corner to open the
+   connection. The status badge next to it shows the current printer state
+   (Standby, Printing, …).
+
+### Connect OrcaSlicer
+
+In OrcaSlicer, set the printer's connection type to **Moonraker** and enter
+`http://BRIDGE-IP:7125` as the host (full URL including `http://` and the
+port). See the [Recommended Slicer](README.md#-recommended-slicer) section
+of the README for the patched OrcaSlicer-KX build with proper per-slot
+filament matching.
+
+---
+
+## Dashboard Overview
+
+The Dashboard is the main screen and is made of movable/resizable tiles
+("cards"). Click **🖉 Customize dashboard** (top right
+of the dashboard) to enter edit mode: drag tiles to reorder, drag corners to
+resize, then save the arrangement as a named **preset** via the preset
+dropdown, or reset back to the default layout.
+
+The default tiles are:
+
+- **Camera** — live view from the printer's camera, with a light toggle and
+  a play/stop button. A small ↺ reset button appears if the stream needs to
+  reconnect (e.g. after a 429 rate-limit from the printer).
+- **Progress** — print percentage, a thumbnail of the current file, current
+  layer, current Z-height, elapsed/remaining time, and the file name.
+  While printing this card shows **Pause**, **Objects** (partial cancel, see
+  [Printing](#printing)) and **Stop** buttons. When a file is loaded but not
+  yet started, it instead shows **Print**, **Assign Slots**, and **Clear**.
+- **Temperatures** — current and target nozzle/bed temperature with
+  progress bars, quick "Set"/"Off" controls, and a rolling history chart of
+  the last 60 readings.
+- **Axis control** — jog buttons for X/Y/Z, adjustable step size (0.1 / 1 /
+  5 / 10 mm or a custom value), Home XY, Home Z, Home All, and Motors Off.
+- **Print Speed** — three presets (Quiet / Normal / Sport) matching the
+  printer's own speed modes.
+- **Fan** — a slider plus quick buttons (0/25/50/75/100%) for the part-cooling
+  fan.
+- **Filament / AMS** — one tile per AMS/ACE slot showing assigned material,
+  color and (if configured) the mapped OrcaSlicer profile. Click a slot to
+  open its edit dialog (see [Managing Filaments](#managing-filaments)).
+  If an ACE dryer is attached and active, a separate drying-status row
+  appears below the grid.
+
+Two banners can appear above the dashboard: an upload-ready banner when a
+GCode file finishes uploading (with Print / Assign Slots / Cancel actions),
+and a pause-reason banner when the printer pauses itself (e.g. filament
+runout).
+
+---
+
+## Printing
+
+### Uploading GCode
+
+Open the **Browser** tab (sidebar) → **Uploaded** sub-tab, and
+either drag a `.gcode`/`.bgcode` file onto the drop zone or click it to pick
+a file. Uploaded files get thumbnails (if embedded by the slicer), a search
+box, a status filter (All / Successful / Failed / New) and a sort order
+(date, name, print duration). Select the checkbox on a card to enter
+multi-select mode for bulk deletion.
+
+If you configured file-ready mode as "Print dialog" (see
+[Settings Reference](#settings-reference)), a dialog opens right after
+upload offering to start the print immediately or assign AMS slots first.
+With "banner" mode you instead get a persistent banner at
+the top of the screen with the same choices, so you can keep browsing
+before deciding.
+
+### Starting a print / assigning filament
+
+When starting a file that uses multiple filament channels (AMS/ACE slots),
+the **filament assignment dialog** opens automatically (or via "Assign
+Slots"). It lets you:
+
+- Map each GCode filament channel to a physical AMS/ACE slot, with a
+  mismatch warning if a channel's expected material/color doesn't match
+  what's actually loaded in the slot you pick.
+- Expand **✂ Skip objects** to deselect specific
+  printable objects (for multi-object plates) before the print starts —
+  the same object list and skip mechanism is also available mid-print from
+  the Progress card's "Objects" button.
+- Toggle **Auto-Leveling** for this print.
+- If Spoolman is configured, assign a specific spool to each slot right
+  from this dialog.
+
+Confirm with **▶ Print** to send the job to the printer.
+
+### Print-start behavior settings
+
+Under **Settings → Printer** you can control default behavior for
+every print:
+
+- **Default slot (single-color print)** —
+  which AMS slot to use automatically for single-material files.
+- **Auto-leveling before print** — run bed leveling before every print.
+- **Resonance compensation before print** — run input-shaper calibration
+  before every print.
+- **After upload: print-start behavior**
+  — dialog vs. banner, as described above.
+- **Turn camera on at print start** —
+  auto-start the camera stream whenever a print begins.
+- **Show warning for web-upload
+  prints** — an extra confirmation step for files uploaded through the
+  browser rather than sliced directly for this printer, to catch
+  wrong-printer-profile mistakes.
+
+### While printing
+
+The Progress card provides **Pause/Resume**, **Stop** (with a confirmation
+prompt), and **Objects** to skip specific objects on a multi-object plate
+mid-print.
+
+---
+
+## Managing Filaments
+
+### AMS / ACE slots
+
+Each slot tile on the Dashboard can be opened (click it) to edit:
+
+- **Color** — via a color picker, recent-color swatches, or "copy color
+  from slot" to match another slot.
+- **Material** — quick buttons for common materials, or free text.
+- **OrcaSlicer profile override** — pick a specific imported or built-in
+  OrcaSlicer filament profile for this slot. This is what gets sent to the
+  slicer during AMS sync instead of a generic "Generic PLA/PETG" fallback
+  (see the README's [OrcaSlicer-KX](README.md#-recommended-slicer) section
+  for why this matters).
+- A **feed** button to extrude/load filament for that slot directly from
+  the UI.
+
+If your printer has an ACE dryer unit, an additional drying panel appears
+below the AMS grid when drying is active, and slot edit dialogs let you
+configure drying **presets**: PLA, PLA+, PETG, TPU, ABS/ASA, PA/PC, and
+three freely-nameable Custom presets, each with its own temperature
+(30–80 °C) and remaining-time (h:m:s) setting. Presets can be edited and
+saved, or reset back to their defaults.
+
+### Importing your own OrcaSlicer profiles
+
+Under **Settings → Filament → OrcaSlicer-Profile** (or from the "★ Own
+profiles" link inside a slot's profile dropdown), open the import dialog
+and either drag a **ZIP** of your OrcaSlicer filament folder onto the drop
+zone, or upload individual **.json** profile files. In OrcaSlicer, that
+folder is reachable via **Help → Show Configuration Folder →
+user/<id>/filament/**. Imported profiles show up in every slot's profile
+dropdown under a "★ Own profiles" group and can be removed again from the
+same import dialog's list.
+
+### Filament-profile mapping and visible vendors
+
+Still under **Settings → Filament**:
+
+- **Filament profile mapping (per
+  slot)** — pin a fixed OrcaSlicer profile to each AMS slot so the bridge
+  always reports that profile during slicer sync, regardless of what
+  material/color is currently loaded.
+- **Visible vendors** — restrict which vendors show
+  up in the slot profile dropdown (useful if you only ever use a handful of
+  brands); leaving nothing selected shows all vendors. "Generic" and your
+  own imported profiles are always visible regardless of this filter.
+
+### Spoolman integration
+
+Configure the Spoolman server URL under **Settings → Integrations →
+Spoolman** (e.g. `http://spoolman:7912`) and a sync rate in seconds (`0`
+means "sync only when a print finishes"). Once connected, a
+**Spoolman — Slot assignment** panel appears under
+**Settings → Filament**, letting you assign a specific spool from your
+Spoolman inventory to each AMS slot. Filament usage is then tracked and
+reported to Spoolman automatically as you print, and the filament
+assignment dialog shown when starting a print also lets you pick/confirm
+spools per slot at print time.
+
+---
+
+## Multi-Printer Setup
+
+KX-Bridge can manage several printers from one running instance.
+
+- **Add a printer:** go to the **Printers** tab and click
+  **"+ Add printer"**. Enter the IP (name is
+  optional); credentials are fetched automatically, same as during first
+  setup. Each additional printer gets its own port (7126, 7127, …).
+- **Switch printers:** use the dropdown in the header (next to the printer
+  name), or open the **Printers** tab and click **"Switch"**
+  on any non-active printer's card. Each card also shows live status
+  (state, current file, progress bar, nozzle/bed temperature) fetched
+  directly from that printer's own bridge instance.
+- **Remove a printer:** click the **✕** button on its card in the
+  **Printers** tab; you'll be asked to confirm.
+
+---
+
+## Power Switch Feature
+
+The power switch feature lets the bridge turn an external **smart plug**
+on or off, and query its state — it is **not** a connection to the
+printer's own internal power management, since the printer has no
+remotely controllable power state of its own. You need a smart plug
+(commonly a Tasmota-flashed plug) wired between the wall outlet and the
+printer's power supply, reachable over HTTP from the bridge.
+
+Configure it under **Settings → Connection**, in the "Power Switch" card,
+with three
+URLs:
+
+- **Power-On URL** — called to switch the plug on.
+- **Power-Off URL** — called to switch the plug off.
+- **Status URL** — polled to show the current on/off state.
+
+For a Tasmota device, these are typically of the form:
+
+```
+http://192.168.x.x/cm?cmnd=Power%20on
+http://192.168.x.x/cm?cmnd=Power%20off
+http://192.168.x.x/cm?cmnd=Power
+```
+
+replacing `192.168.x.x` with the smart plug's own IP address (not the
+printer's). Once configured, a 🔌 power icon appears next to that
+printer's card in the **Printers** tab; click it to toggle the plug.
+Turning it off asks for confirmation, since it will cut power to whatever
+is plugged in — make sure nothing is printing first. The icon's color
+reflects the last known state (green = on, gray = off) as reported by the
+status URL.
+
+---
+
+## Settings Reference
+
+Settings are organized into tabs on the **Settings** panel:
+
+- **Connection** — printer name, printer IP, MQTT port,
+  MQTT username/password, device ID and mode ID (normally filled in
+  automatically by "Add printer"), plus the Power Switch URLs described
+  above.
+- **Printer** — default slot for single-color prints,
+  auto-leveling and resonance-compensation defaults, upload/print-start
+  behavior, camera auto-start, and the web-upload confirmation warning
+  (see [Printing](#printing)).
+- **Display** — UI language (DE/EN/ES/FR/IT/中文), light/dark
+  theme toggle, how often the bridge polls the printer for status updates,
+  and a verbose HTTP request logging toggle for troubleshooting.
+- **Filament** — OrcaSlicer profile import, per-slot profile mapping,
+  visible-vendor filtering, and (if Spoolman is connected) the Spoolman
+  slot-assignment panel — all described in
+  [Managing Filaments](#managing-filaments).
+- **Integrations** — Spoolman server URL and sync rate, and
+  an info box pointing to the `moonraker-obico.cfg` file used to configure
+  Obico (Obico itself is set up outside the bridge UI — see
+  [Camera / OrcaSlicer-KX / Obico](#camera--orcaslicer-kx--obico) below).
+- **System** — shows the current bridge version and lets you check for and
+  install updates directly from the browser, including a changelog preview.
+
+Most settings changes are applied via the **Save &
+Restart** button at the bottom of the Settings panel, which restarts the
+bridge process to apply them.
+
+---
+
+## Troubleshooting Basics
+
+- **Logs:** the **Console** tab shows a live event log with
+  filters by direction (RX/TX), level (errors/warnings), and topic (AMS,
+  print, info, status), plus a free-text filter and a download button for
+  the full log file.
+- **"Wrong MQTT credentials" on start:** re-add the printer via
+  "+ Add printer", or see the credential-refresh steps in the README's
+  [Troubleshooting](README.md#-troubleshooting) section.
+- **Printer not found / no LAN mode:** confirm LAN mode is enabled on the
+  printer's display and that the printer and bridge are on the same
+  network.
+- **Docker permission errors, upgrading from old versions, and other
+  install-level issues:** see the README's own
+  [Troubleshooting](README.md#-troubleshooting) section.
+
+For anything not covered here or in the README, please check or open an
+issue on the project's Gitea page:
+<https://gitea.it-drui.de/viewit/KX-Bridge-Release/issues>.
+
+---
+
+## Camera / OrcaSlicer-KX / Obico
+
+- **Camera:** the Dashboard's Camera tile plays the printer's live stream
+  directly; no separate setup is required beyond having the printer
+  connected.
+- **OrcaSlicer-KX:** for filament brand/color to sync correctly into
+  OrcaSlicer's AMS view, use the patched community build — see the
+  README's [Recommended Slicer](README.md#-recommended-slicer) section for
+  the download link and what it changes.
+- **Obico:** self-hosted failure-detection and time-lapse integration runs
+  through the separate `moonraker-obico` plugin/container, configured via
+  the config file referenced under **Settings → Integrations → Obico**.
+  Full setup instructions live in the README's
+  [Community & Integrations](README.md#-community--integrations) section.
--- a/README.md
+++ b/README.md
@@ -33,6 +33,8 @@ officially tested or supported. Feedback welcome.</sub>
 >
 > 👉 Want to contribute? Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

+> 📖 Looking for day-to-day usage help? See the [User Manual](MANUAL.md). Building an integration? See the [API Reference](API.md).
+
 ---

 ## ✨ Features