mirror of
https://github.com/OrcaSlicer/OrcaSlicer.git
synced 2026-08-05 09:07:39 +00:00
111 lines
4.9 KiB
Markdown
111 lines
4.9 KiB
Markdown
# Filament synchronization and mapping
|
|
|
|
*Owns the three filament stages end to end: acquiring printer state,
|
|
selecting a mapping, and delivering it at print time. Defers the upload
|
|
and start mechanics to [Printing](printing.md), and per-vendor discovery
|
|
detail to [Built-in agents](agents.md).*
|
|
|
|
Filament support has three separate stages. A successful first stage does
|
|
not mean that a selected mapping will be delivered to the printer.
|
|
|
|
Stage 3 is where the two paths diverge, and only one of them reaches the
|
|
printer:
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
SRC["Filament source<br/>Moonraker lane_data, or the classic MMU object"]
|
|
ACQ["1 - Acquire state<br/>Moonraker pull, not subscription"]
|
|
ST["DevFilaSystem<br/>Bambu-shaped view, synthetic 4-slot groups"]
|
|
SEL["2 - Select mapping<br/>Send dialog matches project filament to slots"]
|
|
PAR["PrintParams<br/>ams_mapping fields"]
|
|
QIDI["Qidi agent writes enable_box<br/>and value_t per tool, then starts the print"]
|
|
BASE["Base Moonraker, Happy Hare, AFC<br/>upload and start ignore the mapping fields"]
|
|
OK["Mapping reaches the printer"]
|
|
DEAD["Mapping never reaches the printer<br/>the job runs on the printer's own loaded-lane behavior"]
|
|
|
|
SRC --> ACQ --> ST --> SEL --> PAR
|
|
PAR -- Qidi --> QIDI --> OK
|
|
PAR -- every other target --> BASE --> DEAD
|
|
```
|
|
|
|
## 1. Acquire printer state
|
|
|
|
`FilamentSyncMode` declares how the UI obtains filament state:
|
|
|
|
| Mode | Meaning |
|
|
| --- | --- |
|
|
| `subscription` | A status stream keeps the state current. |
|
|
| `pull` | The UI must request state before it can use it. |
|
|
| `none` | The agent has no usable filament state. |
|
|
|
|
Moonraker uses `pull`. Its ordinary status stream does not supply the
|
|
filament data used by this UI. In particular, `lane_data` is a Moonraker
|
|
database namespace, not a printer object that the existing subscription
|
|
can follow. Changing Moonraker to `subscription` would suppress the pull
|
|
that actually populates the UI.
|
|
|
|
The agent first reads `lane_data`, which can describe AFC and newer Happy
|
|
Hare installations. If that is unavailable, it reads the classic Happy
|
|
Hare `mmu` object. Those response shapes are source-supported but not yet
|
|
verified against current Happy Hare and AFC installations.
|
|
|
|
The current parser expects lane values as strings and silently skips
|
|
numeric values. Whether current AFC or Happy Hare installations emit
|
|
numeric lane values is unverified.
|
|
|
|
The received lanes are converted into a Bambu-shaped model so existing
|
|
AMS UI can render them. The model groups numeric lane indexes into
|
|
synthetic groups of four slots and passes the result through
|
|
`ParseV1_0`. This is a UI compatibility adapter, not evidence that the
|
|
printer has a Bambu AMS.
|
|
|
|
Pull state can be stale. The Send dialog can build a mapping from the
|
|
current `DevFilaSystem` without refreshing it first, and a failed pull can
|
|
leave older state visible. Do not represent a displayed lane list as a
|
|
fresh printer read unless the call site just performed the pull.
|
|
|
|
## 2. Select a mapping
|
|
|
|
The Send dialog matches each project filament to a compatible reported
|
|
slot. It rejects a mismatched material type and then prefers compatible
|
|
slots according to the existing mapping rules. The result is carried in
|
|
the legacy linear mapping, the explicit AMS-and-slot mapping, and mapping
|
|
metadata for the job.
|
|
|
|
Treat lane numbers as printer contracts. A numeric lane index is used as a
|
|
slot index in the synthetic four-slot view, so an incorrect numbering
|
|
assumption can select the wrong physical lane.
|
|
|
|
The material identity code also retains a defect: ABS and ASA can be
|
|
shown as PLA when profile identifiers collide. This is not fixed here,
|
|
and multi-color mapping has not received hardware verification.
|
|
|
|
## 3. Deliver the mapping at print time
|
|
|
|
`PrintJob` copies the selected mappings into `PrintParams`, but base
|
|
Moonraker does not read those fields when it uploads and starts a print.
|
|
For plain Moonraker, Happy Hare, and AFC targets using that base path, a
|
|
correct-looking mapping in the UI is therefore not delivered to the
|
|
printer. The print runs using the printer's own loaded-lane behavior.
|
|
|
|
Qidi is the implemented exception. Its agent writes its own box mapping
|
|
before starting the print. That is a Qidi-specific delivery contract, not
|
|
a generic Moonraker solution.
|
|
|
|
There are deliberately no guessed Happy Hare or AFC write macros. Their
|
|
macro and variable names are defined by printer-side configuration, so a
|
|
guessed command could silently do nothing or control the wrong setup. Add
|
|
a delivery path only after verifying the exact contract against upstream
|
|
documentation or a real printer.
|
|
|
|
## Maintenance checklist
|
|
|
|
- Keep Moonraker in `pull` mode while `lane_data` remains pull-only.
|
|
- Refresh or clearly surface stale state before relying on Send-dialog
|
|
mappings.
|
|
- Do not claim base Moonraker honors mappings until it consumes them at
|
|
print time.
|
|
- Preserve Qidi as a distinct delivery implementation.
|
|
- Verify lane numbering, material identity, and multi-color behavior on
|
|
hardware before expanding the mapping contract.
|