viewit
0ee1af4cb7
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.
331 lines
14 KiB
Markdown
331 lines
14 KiB
Markdown
# 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.
|