# 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.
