KX-Bridge-Release/MANUAL.md

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. For the HTTP/WebSocket API (developers, plugin authors, integrators), see API.md.

---

Getting Started

Install and start the bridge

Follow the Quick Start in README.md — the short version is:

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 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) 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). 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), 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 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Ⓜ️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//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).
• 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.
• 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 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 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 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 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 section.