Spoolman Integration¶

Sync your AMS filament with Spoolman for complete spool tracking and inventory management.

Spoolman Integration — Native Inventory UI¶

Bambuddy ships a full native inventory UI for Spoolman-managed spools. When Spoolman is enabled, the Inventory tab switches from the embedded Spoolman iframe to a built-in interface that shares the exact same design as the local inventory — filtering, editing, NFC writes, and AMS deep-links all work identically regardless of which backend is active.

What is Spoolman?¶

Spoolman is a self-hosted filament inventory manager that:

• Tracks spool quantities
• Records filament usage
• Manages multiple materials and vendors
• Integrates with slicers

Bambuddy syncs your AMS slots with Spoolman for unified tracking.

Connection Setup¶

Requirements¶

• Spoolman instance running and accessible
• Network access from Bambuddy to Spoolman

Configuration¶

1. Go to Settings > Filament
2. The Spoolman card is the first card on the page
3. Toggle Enable Spoolman on, then enter:

1. Click Test Connection
2. Click Save

Sync Features¶

How Sync Works¶

When AMS data changes:

1. Bambuddy detects the filament via RFID
2. Searches Spoolman for matching spool (by UUID)
3. If found: Updates remaining weight and location
4. If not found and Auto-add unknown RFID spools is on (default): Auto-creates new spool in Spoolman
5. If not found and the toggle is off: Bambuddy raises a confirmation modal in the running web UI instead — you decide whether to add it

Auto-add unknown RFID spools¶

The toggle lives under Settings → Filament → Filament Tracking above the Spoolman card and applies to both Built-in Inventory and Spoolman modes. Default is on (legacy behaviour). Turn it off if you prefer to pre-register new spools in Spoolman before loading them, to avoid the matcher creating a duplicate when the AMS reads the tag.

With the toggle off:

• Loading an unknown spool no longer writes a Spoolman row silently
• A modal opens in the Bambuddy UI showing the printer / AMS slot / material / colour
• Add to Inventory creates the spool in Spoolman and binds it to the AMS slot in a single call
• Manual Sync AMS actions report the slot as skipped with the reason "Auto-add disabled; add to inventory manually"
• The modal does not re-pop on every MQTT push — only when you physically remove and re-insert a spool, or load a different unknown spool

Sync Modes¶

• Auto - Syncs whenever AMS data changes (recommended)
• Manual - Only syncs when you click the Sync button

Bulk actions¶

Spoolman-mode users get the same bulk actions documented in the Inventory page — select multiple spools in the Inventory table to bulk-edit fields, archive / restore, delete, or reset the "Total Consumed" counter in a single call. See Inventory → Bulk actions for the full action set. The bulk-edit endpoint loops your selection through the same per-spool update path, so Spoolman's filament-linking, vendor resolution, and extra-dict behaviour are identical to single-spool edits.

If Spoolman is unreachable mid-batch, the backend collects per-spool errors and returns them alongside the success count. The frontend translates that into a partial-success warning toast (or a red "all failed" toast that preserves your selection so you can retry once Spoolman is back online) — bulk actions never silently drop rows.

Sync Results¶

After syncing, you'll see:

• Synced count - Number of spools successfully synced
• Skipped spools - List of spools that couldn't sync (with reasons)
• Errors - Any issues that occurred

Skipped spools show:

• Location (e.g., "AMS A1")
• Color swatch
• Reason (e.g., "Non-Bambu Lab spool")

Usage Tracking¶

When prints complete, Bambuddy reports per-filament usage to Spoolman:

1. Bambuddy extracts per-filament usage data from the archived 3MF file (slicer estimates)
2. For partial prints, per-layer G-code analysis provides precise consumption up to the exact failure layer
3. On completion, each spool's usage is reported individually to Spoolman (multi-material support)
4. Spoolman updates spool quantities accordingly
5. If no 3MF data is available, AMS remain% delta is used as a fallback

When usage cannot be tracked at all¶

Both routes above can be unavailable at once, and the result is a spool whose remaining amount never moves:

• There is no 3MF to read. A file sent to an H2-series or P2S printer from Bambu Studio is kept on the printer's internal eMMC, which FTPS does not serve, so the print archives without one. Bambuddy probes external storage for a copy by name before giving up, and often finds it, but not always.
• And the slot reports no remaining percentage. The delta fallback needs a reading at the start of the print. A spool without an RFID tag — including anything in an AMS HT — reports -1 until somebody sets a remaining amount on the printer, so there is no starting figure to subtract from.

Bambuddy logs the slot it could not charge rather than passing over it in silence. To get tracking back, either start the print through Bambuddy or OrcaSlicer (both upload to external storage, so the 3MF is readable), or set a remaining amount for the slot on the printer's own screen so the AMS begins reporting a percentage for it.

How Bambuddy decides which spool a slot used¶

A sliced file numbers its filaments 1, 2, 3, 4. Which AMS tray each of those numbers actually came from is a separate decision, made when the job is sent, and it is frequently not left-to-right — you can map filament 1 to slot 3 in the Print dialog of any slicer. Bambuddy works that mapping out in this order:

1. The mapping Bambuddy sent, for prints you start from Bambuddy itself — the Print button, the queue, a reprint. Exact, because Bambuddy chose it.
2. The mapping the slicer sent, captured from the print command when Bambu Studio or OrcaSlicer dispatched the job over your local network.
3. The printer's own report. Most models publish the running job's slot-to-tray assignment in their status. This is what covers a job sent from Bambu Studio through the Bambu cloud, where the command never passes through your network for Bambuddy to see.
4. Colour matching, for the models that publish no such report — the A1, A1 Mini, P1S and P2S. The sliced colour of each filament is matched against the loaded trays, and is only used when every filament matches exactly one.
5. Position, as a last resort: filament 1 to the first loaded tray, filament 2 to the second, and so on.

Only the last of these can be wrong in a way you would notice, and it is also the only one that assumes your AMS is loaded in slicer order. If a print consistently deducts from the wrong spool, search the log for slot_to_tray — the line names the mapping and which of the five produced it.

Disable AMS Estimated Weight Sync¶

By default, Bambuddy syncs AMS weight estimates to Spoolman. If you prefer Spoolman's own usage-based tracking:

1. Go to Settings > Filament and open the Spoolman card
2. Enable Disable AMS Estimated Weight Sync
3. AMS weight estimates will no longer overwrite Spoolman quantities
4. New spools still use the AMS estimate as their initial weight

Partial Usage for Failed Prints¶

When a print fails or is cancelled, filament was still consumed. Enable partial usage reporting:

1. Go to Settings > Filament and open the Spoolman card
2. Enable Report Partial Usage for Failed Prints
3. Bambuddy calculates filament used via per-layer G-code analysis up to the exact failure layer
4. Falls back to linear scaling (total estimate × progress%) if layer data is unavailable

AMS Slot Mapping¶

Viewing Mappings¶

Hover over any AMS slot to see:

• Vendor - Bambu Lab or Generic
• Profile - Filament type (e.g., "PLA Basic")
• Color - Color name and swatch
• K Factor - Pressure advance value
• Fill Level - Remaining percentage with visual bar
• Spool ID - Bambu Lab UUID (when Spoolman enabled)

Fill Level for AMS Lite / External Spools¶

AMS Lite units (e.g., A1 series) have no weight sensor and always report 0% fill level. When a spool is linked to Spoolman and has weight data, Bambuddy uses Spoolman's remaining weight instead:

• AMS with weight sensor - Uses AMS percentage directly (no change)
• AMS Lite (reports 0%) - Falls back to Spoolman: (remaining_weight / filament_weight) × 100
• External spool - Shows fill level from Spoolman if linked (otherwise shows "—")

When Spoolman data is used, the hover card displays "(Spoolman)" next to the fill percentage so you can distinguish the data source.

Opening Linked Spools¶

For spools already linked to Spoolman:

1. Hover over any AMS slot with a linked spool
2. Click Open in Spoolman button
3. Opens the spool's page in Spoolman in a new tab
4. Edit spool details directly in Spoolman

Manual Linking¶

Link existing Spoolman spools to your AMS:

1. Hover over any AMS slot with a Bambu Lab spool that's not yet linked
2. Click Link to Spoolman button
3. Select from list of unlinked Spoolman spools
4. Click Link to confirm

Spool UUID¶

Each Bambu Lab spool has a unique identifier (UUID):

• Visible in AMS hover card when Spoolman is enabled
• Click the copy button to copy full UUID
• Used internally to match spools between AMS and Spoolman

Unlinking¶

Remove a link:

1. Open Spoolman interface
2. Find the spool
3. Clear the extra.tag field

Custom fields Bambuddy registers¶

Spoolman rejects any write naming an extra field it doesn't know about, so Bambuddy registers the four it uses the first time it needs them:

You can rename these in Spoolman's own field editor, or give them a default, and Bambuddy will leave your changes alone. It matches on the field's key, which never changes, rather than on the display name. Deleting one, though, means Bambuddy re-creates it on the next sync — it needs the field to exist in order to write to it.

Adding Spools¶

From AMS¶

When unknown filament is detected:

1. Click Add to Spoolman
2. Enter spool details:
3. Material type
4. Color
5. Vendor
6. Initial weight
7. Cost per kg
8. Spool is created and linked

From Spoolman¶

Add spools directly in Spoolman:

1. Open Spoolman interface
2. Add new spool
3. Spool appears in Bambuddy when loaded

Inventory View¶

View your complete inventory:

In Bambuddy¶

• AMS slots with linked spools
• Quick view of what's loaded
• Remaining quantities

In Spoolman¶

• Full spool database
• Usage history
• Cost tracking
• Vendor management

Usage Statistics¶

Track filament consumption:

Per-Print Usage¶

Each archived print records per-filament data:

• Each spool used (tracked individually for multi-material prints)
• Grams consumed per spool (from G-code extrusion analysis)
• Material type and slot mapping

Spoolman Integration¶

Usage syncs to Spoolman:

• Spool quantities update
• History recorded
• Low stock alerts

Automatic Features¶

Auto-Sync on Print Complete¶

After each print:

1. Calculate per-filament usage from G-code layer data
2. Report each spool's consumption individually to Spoolman
3. Spoolman updates spool quantities and records usage history
4. For multi-material prints, each filament is tracked separately

Auto-Detect on AMS Change¶

When AMS filament changes:

1. Detect new configuration
2. Match with Spoolman
3. Update slot mappings

Auto-Clear Location on Removal¶

When spools are removed from AMS:

1. Bambuddy detects the empty slot
2. Finds spools with matching location (e.g., "Workshop X1C - AMS A Slot 1")
3. Clears the location field in Spoolman
4. Spool is now available for other printers

Low Stock Alerts¶

Get notified when spools run low:

Bambuddy sends the alert; Spoolman supplies the remaining weight.

1. Assign your Spoolman spools to AMS slots in Bambuddy.
2. Set the low-stock threshold on the Inventory page (default 20 %).
3. Enable the Low Filament event on a notification provider.

When an assigned spool drops below the threshold you get one notification, such as "X2D: Slot A1 at 15%". It can fire again once the spool goes back above the threshold, for example when you load a fresh one.

Notification setup

Advanced Configuration¶

Multiple Printers¶

Each printer's AMS syncs independently:

• Different spools per printer
• Separate usage tracking
• Unified inventory in Spoolman

Bambu Lab Filaments¶

Bambu Lab filaments include RFID data:

• Material type auto-detected
• Color recognized
• Can match or create in Spoolman

Troubleshooting¶

Connection Failed¶

1. Verify Spoolman URL is correct
2. Check network connectivity
3. Ensure Spoolman is running
4. Check firewall rules

Sync Not Working¶

1. Verify connection is configured
2. Check Spoolman logs
3. Restart Bambuddy if needed
4. Manually trigger sync

Wrong Spool Linked¶

1. Unlink the incorrect spool
2. Manually link correct spool
3. Check RFID data matches

Print cost¶

When a print finishes, each filament slot is charged to the spool that fed it and priced from that spool, then the per-slot costs are added up. A multi-material print is billed at each slot's own rate rather than at one rate for the whole job.

The price comes from Spoolman, in this order:

1. The spool's own Price, if set. Use this when a particular purchase cost something other than the catalogue figure.
2. The filament's Price, otherwise.

The rate per gram is that price divided by the filament's Weight — the net filament weight, not including the spool core — so a 750 g roll is priced as a 750 g roll.

Tips¶