Spoolman Support
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.
ConfigurationFirstly, 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
enable_toolchange_next_pos: True
update_spoolman_location: TrueImportant
The number and setting value of parameters may be different from above, but having this section is important.
Secondly, in mmu_parameters.cfg enable support:
spoolman_support: push|pullThe spoolman_support 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
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.
If spoolman support is enabled (push or pull modes), you will notice that two additional columns will be added to spoolman db. To display this in spoolman web interface you may need to open "Hide Columns" and select them:
An alternative to displaying these additional columns is to use the default behavior of concatenating printer and gate into the "Location" column (see not below). 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.
Note
The use of the "Location" field can be controlled be update_spoolman_location parameter in moonraker.conf. If not specified it defaults to True
[mmu_server]
update_spoolman_location: False
If you set spoolman_support to off then Happy Hare will not interact with spoolman and spool ids will not be seen in the gate map
If you set spoolman_support 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
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
If you set spoolman_support 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
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
If you made changes, restart klipper and moonraker services and you are done.
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: Unknown, SpoolId: 3, Material: TPU, Color: DC6834, Name: Filamentum Industrial Flexifill TPU 98A Grey
Gate 1: Status: Spool, SpoolId: 2, Material: PTEG, Color: DCDA34, Name: n/a
Gate 2: Status: Empty, SpoolId: 1, Material: PLA, Color: 8CDFAC, Name: n/a
Gate 3: Status: Buffer, SpoolId: 4, Material: ASA, Color: 95DC34, Name: Nanovia ASA Black
Gate 4: Status: Buffer, SpoolId: 5, Material: ABS, Color: n/a, Name: n/a
Gate 5: Status: Unknown, SpoolId: 6, Material: ABS, Color: n/a, Name: Sakata 3D ABS-E Black
Gate 6: Status: Buffer, SpoolId: 7, Material: ABS+, Color: 34DCAD, Name: n/a
Gate 7: Status: Buffer, SpoolId: n/a, Material: TPU, Color: grey, Name: n/a, Load Speed: 50%
Gate 8: Status: Unknown, SpoolId: 9, Material: TPU, Color: black, Name: n/a, 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
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 spool_id:
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 voidedTip
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=..
This command allows for management of the added functionality to Spoolman. Specifically, Happy Hare adds the printer name and gate assignment to the spoolman db (in addition to reading filament attributes from it). You can use this command to modify the the gate association as well as retrieve information about spools.
Here you can see the additional extra fields Printer Name and MMU Gate added to the database in the Spoolman web interface. The "Location" field is updated by default but this can be controlled with the update_spoolman_location config option in moonraker.conf. Add/set it to False to prevent the overwriting of the "Location" field.
To view the essential information about a spool use this command. If the SPOOLINFO parameter is 0 or -1 it will default to the currently active spool (if available):
MMU_SPOOLMAN SPOOLINFO=1
Spool is: Matte Green (id: 1)
- Material: n/a
- Used: 56 g
- Remaining: 943 g
If the spool is not currently assigned to this printer you will additionally see this action message:
Spool id 1 is not assigned to this printer!
Run: MMU_SPOOLMAN SPOOLID=1 GATE=..
Happy hare will resync on its own as necessary, but you can force a re-sync of the local gate map and the remote gate map with this command. The synchronization will be in the direction of the spoolman_support setting. If 'push' the printer name, gate and optionally the location field will be updated to match local map. If 'pull' the local gate mapping will be synced based on the printer name, gate assignment stored in spoolman. Note that this does not rebuild the cache (see REFRESH=1 later)
MMU_SPOOLMAN SYNC=1
This is useful if managing more that one printer or in a print farm scenario where centralized management if preferable. To this this up, change spoolman_support: pull in mmu_parameters.cfg
Tip
You can practice switching between modes with the MMU_TEST_CONFIG spoolman_support=xxx. If you have the spoolman web UI active you should dynamically see it change.
If spoolman_support: pull set in mmu_parameters.cfg the MMU will get its gate map and filament attributes from spoolman. Technically it pulls from spoolman and stores locally. The local gate map will display slightly differently to remind you:
MMU_GATE_MAP
Gates / Filaments:
Gate 0: Status: Unknown
Gate 1: Status: Unknown
Gate 2: Status: Unknown
Gate 3: Status: Empty
Gate 4: Status: Empty
Gate 5: Status: Empty, SpoolId: 5 --> Material: ABS, Color: 7C6555, Name: eSun ABS
Gate 6: Status: Buffer, SpoolId: 6 --> Material: ABS, Color: 7C6555, Name: eSun ABS
Gate 7: Status: Unknown
Gate 8: Status: Spool
When operating in this mode these commands are also useful:
Without any parameters the command will list the gate assignment for the printer. If you want to quickly check the gate assignment for another printer that shares the same spoolman db by specifing the PRINTER=xxx parameter:
MMU_SPOOLMAN
Spoolman gate assignment for printer: BigRed
Gate | Spool ID
-----+---------
0 | 1
1 | 23
3 | 41
4 | 5
5 | 11
6 |
7 |
8 | 12
In this mode changing the gate map locally will not have a lasting effect because it will be overwritten by the "map" stored in spoolman. Thus to update remotely specify the SPOOLID and/or GATE parameters
For example to remotely SET (associate) gate 1 with spool id 5, run:
MMU_SPOOLMAN GATE=1 SPOOLID=5
If another gate was previously set to spool id 5 it will automatically be cleared.
There are two ways to UNSET (disassociate) a spool id and gate. Either run with SPOOLID but without the GATE or specifiy the GATE but without the SPOOLID. The latter will find spool currently associated the gate on this printer and clear it. Examples:
MMU_SPOOLMAN SPOOLID=5
MMU_SPOOLMAN GATE=1
To quickly clear the entire remote gate map for this printer:
MMU_SPOOLMAN CLEAR=1
Spool 5 gate cleared in spoolman db
Spool 6 gate cleared in spoolman db
Normally this command is unecessary but since Happy Hare keeps a cache to reduce load on spoolman, it may be necessary if you remotely edit the spoolman db or an error condition occurs. Running it will completely reload spoolman, refresh the cache and then synchronized the local gate map with spoolman in the direction of the spoolman_support setting in mmu_parameters.cfg (either pushing the local map or pulling remote map):
MMU_SPOOLMAN REFRESH=1
Note
To automatically fix and out of sync spoolman database, add the FIX=1 parameter:
MMU_SPOOLMAN REFRESH=1 FIX=1 This will clear offending entries of printer and gate association and retain only the first spool found if multiple are currently assigned to a gate
Important
This is not recommended to run during a print which large spoolman databases
If using MMU_SPOOLMAN in your own macros note that operations can be combined. E.g. To clear database, ensure all inconsistencies are fixed, then assign spool 6 to gate 0:
MMU_SPOOLMAN CLEAR=1 REFRESH=1 FIX=1 GATE=0 SPOOLID=6
You can suppress output with the QUIET=1 parameter