Spoolman Support
Important
THE ENHANCED SPOOLMAN SUPPORT IS A v2.7.0 FEATURE (currently in limited beta)
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.
The new update_spoolman_location setting controls whether the spoolman "Location" field is updated with a summary of which MMU/gate the spool is located. If you already use this field for another purpose, simply set to False -- You then might want to display the printer & gate columns in the Spoolman UI.
Secondly, in mmu_parameters.cfg enable support:
spoolman_support: get|push|pullThe spoolman_support parameter can be set to:
-
off- No spoolman support -
readonly- Only filament attributes are retrieved, spoolman db is never modified -
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 (get, push or pull modes), you will notice that two additional columns (Printer Name and MMU Gate) will be added to spoolman db. To display this in spoolman web interface you will need to open "Hide Columns" and select them:
An alternative to displaying these additional columns is to use the default behavior of concatenating Printer Name and MMU Gate into the "Location" column (see note 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. It also unclutters the spoolman web interface.
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. In this case the local filament color and material details are used and retrieval from spoolman is disabled. Automapping of tools to gates (detailed Here) might still be useful in this mode but will not be as powerful as when spoolman is enabled.
The graph below details the klipper startup sequence: the local gate map and filament details is read locally
sequenceDiagram
autonumber
participant L as Persisted variables
participant K as Klipper
K->>L: read local gate map
L-->>K: local gate map
If you set spoolman_support to readonly it behaves as it did prior to the v2.7.0 release. In this mode Happy Hare will fetch the filament color and material details from spoolman and replace local attributes if a spoolid is set for a gate otherwise the local attributes will be used.
The graph below details the klipper startup sequence: the local gate map (gate, printer and spool_id) is read and the filament details for all referenced spool ids is retrieved and updated locally.
sequenceDiagram
autonumber
participant L as Persisted variables
participant K as Klipper
participant M as Moonraker
participant S as Spoolman
K->>L: read local gate map
L-->>K: local gate map
K->>M: get filament attributes
M->>S: read filament details
S-->>M: filament details
M->>K: MMU_GATE_MAP MAP={filament details}
K->>L: update filament details
In summary:
- Use the
MMU_GATE_MAPcommand to adjust the gate map. - If spool id is specified the filament attributes will be pulled from spoolman overwriting local attributes
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 or when a gate is assigned a new spool id.
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> with a different spool id, the change will also be synced to spoolman.
The graph below details the klipper startup sequence: the local gate map (gate, printer and spool_id) is pushed to spoolman db and filament details for gate with spool_id are retrieved/updated.
sequenceDiagram
autonumber
participant L as Persisted variables
participant K as Klipper
participant M as Moonraker
participant S as Spoolman
K->>L: read local gate map
L-->>K: local gate map
K->>M: push gate map
M->>S: write printer/gate mapping
M->>S: read filament details
S-->>M: filament details
M->>K: MMU_GATE_MAP MAP={filament details}
K->>L: update filament details
To update the gate map you would execute commands similar to this:
MMU_GATE_MAP GATE=3 SPOOLID=74
Will result in the following gate map in the spoolman web browser interface (assuming compatible spoolman version):
First the local gate map is updated as it would be with spoolman disabled. Then the local gate map (gate, printer and spool_id) is pushed to spoolman db and filament attributes are updated from spoolman for gates with spool_id set and persisted locally. Note this is very similar to the startup sequence.
sequenceDiagram
autonumber
participant MF as Mainsail/Fluidd
participant L as Persisted variables
participant K as Klipper
participant M as Moonraker
participant S as Spoolman
MF->>K: MMU_GATE_MAP GATE=3 SPOOLID=74
K->>L: write local gate map
K->>M: push gate map change
M->>S: write gate map change
M->>S: read filament details
S-->>M: filament details
M->>K: MMU_GATE_MAP MAP={filament details}
K->>L: update filament details
In summary:
- Use the
MMU_GATE_MAPcommand to adjust the gate map. - Use
MMU_SPOOLMAN REFRESH=1 SYNC=1to force the update of spoolman to reflect the local 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 the results will be synced to the local gate map. If you think the two are ever out of sync you can issue a MMU_SPOOLMAN SYNC=1 command. (see section on commands for more details).
To make changes in spoolman you can either do it directly in spoolman (and then run the MMU_SPOOLMAN REFRESH=1 SYNC=1) or more conveniently by using the Happy Hare MMU_SPOOLMAN GATE=<int> SPOOLID=<int> command. (see section on Command Reference for more details).
The graph below details the klipper startup sequence: the remote gate map is requested and it is used to sync the local gate map.
sequenceDiagram
autonumber
participant L as Persisted variables
participant K as Klipper
participant M as Moonraker
participant S as Spoolman
K->>L: read local gate map
L-->>K: local gate map
K->>M: pull remote gate map & filament details
M->>S: read gate map & filament details
S-->>M: gate map & details
M->>K: MMU_GATE_MAP MAP={gate map...}
K->>L: update local gate map
To perform a similar update to the "push" example above, you would execute (note MMU_GATE_MAP is not used):
MMU_SPOOLMAN GATE=3 SPOOLID=74
Firstly a request is sent via moonraker to persist the change in the remote gate map (spoolman). Then a sync is requested: The remote gate map (mapping and filament attribtues) is pulled from the spoolman db. The map is then persisted locally.
sequenceDiagram
autonumber
participant MF as Mainsail/Fluidd
participant L as Persisted variables
participant K as Klipper
participant M as Moonraker
participant S as Spoolman
MF->>K: MMU_SPOOLMAN GATE=3 SPOOLID=74
K->>M: update remote gate map
M->>S: write remote gate map
M->>S: get filament detail
S-->>M: gate map & details
M->>K: MMU_GATE_MAP MAP={gate map...}
K->>L: update local gate map and details
In summary:
- Use the
MMU_SPOOLMANcommand to adjust the gate map. - Use
MMU_SPOOLMAN REFRESH=1 SYNC=1if you ever edit spoolman directly
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 or perhaps printed neat QR code labels from Spoolman?
Maybe you are already using nfc2klipper to be able to read the rfid info into klipper. How do you automatically use that with Happy Hare? Here is how...
Because it isn't practical to build a RFID/QR code reader 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 / QR code
- 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. If configured, LEDs and Mainsail interface will be 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/qr code) is voidedTip
If the pending_spool_id_timeout is exceeded the spool_id will be forgotten and the RFID / QR code 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 if MMU's build in readers Happy Hare may include direct 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. If 'readonly' just the filament attributes will be refreshed from spoolman. Note that this does not rebuild the moonraker 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 set 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 directly or an error condition occurs. Running it will completely reload spoolman, refresh the cache and then synchronize 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.