Spoolman Support

Page Sections:

• Configuration
• Gate Map and Spool ID
  • Auto-setting with RFID reader

Spoolman has become a popular way to manage a large collection of print spools. It is a database that you host somewhere (commonly on same rpi as your printer) that can be accessed through a web UI and web based remote procedure calls. Other than providing spool management it does two additional things:

• Tracks filament usage
• Stores attributes about the filament, like print temperature, color and material

Happy Hare fully integrates with spoolman and leverages these two capabilities. Specifically, when Happy Hare selects a filament/spool, spoolman is notified of the selection so that the printer can update usage against the correct spool. Secondly, spoolman is asked again for filament attributes to ensure Happy Hare's knowledge is up to date. Note that the load of filament attributes is also done in bulk during MMU initialization.

To use spoolman with Happy Hare you need to configure and understand the roll of the "gate map" and the "spool_id" attribute.

Configuration

Firstly, Happy Hare's moonraker extension should be installed. It will be by default but check that you have the following in your moonraker.conf:

[mmu_server]
enable_file_preprocessor: True

Important

The 'enable_file_preprocessor' may be True or False depending on whether slicer placeholder pre-processing is enabled. Having the section is important

Secondly, in mmu_parameters.cfg enable support:

spoolman: push|pull

The spoolman parameter can be set to:

• off - no spoolman support
• push - The local gate map is considered as the source of truth and will be pushed to spoolman
• pull - The remote spoolman database is considered as the source of truth and will be pulled into the local gate map

Important

Please note that both push and pull modes require you to have spoolman 0.18.1 or later installed. If you are using an older version of spoolman you will need to upgrade to use this feature.

Tip

If spoolman support is enabled, you can enable additional columns to be displayed in spoolman web interface (after a moonraker restart) as follows:

I'd recommend adding the Printer Name and MMU Gate for a smoother experience. The printer name will refer to the klipper machine's hostname and the MMU gate will refer to the gate number that the spool is loaded into. This can be useful if you have multiple printers and MMUs and want to keep track of which spool is loaded into which MMU.

Off:

If you set spoolman to off then Happy Hare will not interact with spoolman.

Push:

If you set spoolman to push then Happy Hare will push the local gate map (that can be seen in mmu_vars.cfg file) to spoolman at klipper startup and when explicitely asked. In this mode klipper will read the mmu_vars.cfg file at startup to initialize its internal gate map and then push that to spoolman by asking moonraker to update the spoolman database. In this case the local configuration is the source of truth and spoolman is updated to match. When you make changes to the gate map using MMU_GATE_MAP GATE=<int> SPOOLID=<int> you can push those changes to spoolman by calling the MMU_SPOOLMAN SYNC=1 command. (see section on commands for more details).

Note

Executing

MMU_GATE_MAP GATE=3 SPOOLID=74
MMU_SPOOLMAN SYNC=1

Will result in the following gate map in the spoolman web browser interface (if you have enabled the additional columns as described above):

The graph below details the klipper startup sequence:

sequenceDiagram
    participant L as Persisted variables
    participant K as Klipper
    participant M as Moonraker
    participant S as Spoolman

    L->>K: read local gate map
    K->>M: push gate map
    M->>S: push gate map

Loading

The graph below details the klipper explicit push sequence:

sequenceDiagram
    participant L as Persisted variables
    participant K as Klipper
    participant M as Moonraker
    participant MF as Mainsail/Fluidd
    participant S as Spoolman

    MF->>M: MMU_GATE_MAP GATE=3 SPOOLID=74
    M->>K: MMU_GATE_MAP GATE=3 SPOOLID=74
    K->>L: write local gate map
    MF->>M: MMU_SPOOLMAN SYNC=1
    M->>K: MMU_SPOOLMAN SYNC=1
    K->>M: push gate map
    M->>S: push gate map

Loading

Pull:

If you set spoolman to pull then Happy Hare will pull the gate map from spoolman at klipper startup and when explicitely asked. In this mode klipper will ask moonraker to pull the gate map from spoolman at startup and then read the gate map from moonraker to initialize its internal gate map. In this case spoolman is the source of truth and klipper is updated to match. When you make changes to the gate map in spoolman you can pull those changes to klipper by calling the MMU_SPOOLMAN SYNC=1 command. (see section on commands for more details).

The graph below details the klipper startup sequence:

sequenceDiagram
    participant L as Persisted variables
    participant K as Klipper
    participant M as Moonraker
    participant S as Spoolman

    K->>M: pull gate map
    M->>S: pull gate map
    S->>M: gate_map
    M->>K: MMU_GATE_MAP MAP=gate_map
    K->>L: write local gate map

Loading

The graph below details the klipper explicit pull sequence:

sequenceDiagram
    participant L as Persisted variables
    participant K as Klipper
    participant M as Moonraker
    participant MF as Mainsail/Fluidd
    participant S as Spoolman

    MF->>M: MMU_SPOOLMAN SYNC=1
    M->>K: MMU_SPOOLMAN SYNC=1
    K->>M: pull gate map
    M->>S: pull gate map
    S->>M: gate_map
    M->>K: MMU_GATE_MAP MAP=gate_map
    K->>L: write local gate map

Loading

If you made changes, restart klipper and moonraker services and you are done.

Gate Map and Spool ID

Each gate can have configured information about what is loaded (technically it can have information even if the gate is currently empty). This information used in various features and UI visualization but also is available to you via printer.mmu.* printer variables for use in your custom gocde.

The gate map currently consists of: (1) availability of filament, (2) filament material type, (3) filament color in W3C color name or in RGB format, (4) the spoolman spool ID, (5) load/unload speed override. If spoolman is enabled the material and color is automatically retrieved from the spoolman database. Note a direct way to manipulate the gate map is via the MMU_GATE_MAP command. For example:

Gates / Filaments:
Gate 0: Status: Empty, Material: TPU, Color: DC6834, Name: Filamentum Industrial Flexifill TPU 98A Grey, SpoolID: 3
Gate 1: Status: Spool, Material: PTEG, Color: DCDA34, Name: n/a, SpoolID: 2
Gate 2: Status: Empty, Material: PLA, Color: 8CDFAC, Name: n/a, SpoolID: 1
Gate 3: Status: Empty, Material: ASA, Color: 95DC34, Name: Nanovia ASA Black, SpoolID: 4
Gate 4: Status: Empty, Material: ABS, Color: n/a, Name: n/a, SpoolID: 5
Gate 5: Status: Empty, Material: ABS, Color: n/a, Name: Sakata 3D ABS-E Black, SpoolID: 6
Gate 6: Status: Empty, Material: ABS+, Color: 34DCAD, Name: n/a, SpoolID: 7
Gate 7: Status: Empty, Material: TPU, Color: grey, Name: n/a, SpoolID: n/a, Load Speed: 50%
Gate 8: Status: Empty, Material: TPU, Color: black, Name: n/a, SpoolID: 9, Load Speed: 60%

If spoolman is enabled and a SpoolID is available, Happy Hare will use this to pull attributes from spoolman and set the other elements of the gate map. I.e. it will replace whatever was statically created with dynamic data from spoolman. If you exploit that you can simple keep the SpoolID up to date when you replace or reload a filament spool and not worry about anything else. If you have LEDs installed they can display the dynamically set filament color.

To set the SpoolID use the command like this to set the ID to 5 on gate #0:

MMU_GATE_MAP GATE=0 SPOOLID=5

A SpoolID of -1 can be used to unset the spool ID and other attributes can be set manually as in MMU_GATE_MAP GATE=0 SPOOLID=-1 COLOR=red MATERIAL=PLA

See the command reference for a complete list of command arguments.

Note

If you see a command similar to this appear on the console during boot, don't worry. It is the startup sync of gate map with spoolman at work. It doesn't always appears because the sync can occur before the console is ready but seeing it occassionaly is confirmation that everything is connected

Changing SpoolID on Toolchange

Once configured Happy Hare will, on a change of tool, let spoolman know (via moonraker) to deactivate the previous spool and activate the new one. You will see this occur in a UI like mainsail:

If you use my enhanced KlipperScreen-Happy Hare Edition there are also screens to visualize the gate map with spoolman setup as well as to edit the spoolID:

Auto-setting with RFID reader

So you have fitted all you spools with a fancy RIFD tags and built a nifty RFID onto your printer or MMU, perhaps are already using nfc2klipper to be able to read that info into klipper. How do you automatically use that with Happy Hare? Here is how...

Because it isn't practical to build a RFID into every gate, the workflow supported by Happy Hare is this:

• Offer up spool to reader
• Read the spool_id you have programmed onto the RFID tag
• In this reader macro, call: MMU_GATE_MAP NEXT_SPOOLID=.. with the read spool_id
  • Insert filament into gate and run MMU_PRELOAD` to load and park the filament, or
  • If you have pre-gate sensors then simply insert the filament into the back of the gate (this can even be done in print although obviously the filament cannot be preloaded in that case

The gate map entry for this gate will automatically be updated with the spool_id and the rest of the gate map parameters (material/color/temp) will be retrieved from spoolman and, if configured, LEDs updated. The length of time that "NEXT_SPOOLID" remains valid is configured in mmu_parameters.cfg:

pending_spool_id_timeout: 20            # Seconds after which this pending spool_id (set with rfid) is voided

Tip

If the pending_spool_id_timeout is exceed the spool_id will be forgotten and the RFID would need to be read again. Set this to a little longer than the time it takes you to load a spool into your MMU but not too long that it never expires

Note

In the future Happy Hare may include direct RFID reader support but at present you need to program the calling of MMU_GATE_MAP NEXT_SPOOLID=..