llms.txt

# SpoolmanSync

> SpoolmanSync is a Next.js web application that automatically tracks filament spools loaded in 3D printers (Bambu Lab and Creality) and keeps Spoolman inventory in sync via Home Assistant. Filament weight is automatically deducted from the correct spool when prints complete. Provides a modern web UI for spool assignment — no YAML editing or Home Assistant expertise required.

## Supported Printers

- **Bambu Lab**: X1C, X1 Carbon, P1S, P1P, A1, A1 mini, H2D with AMS, AMS 2 Pro, AMS HT, AMS Lite (via ha-bambulab integration)
- **Creality**: K1, K1C, K1 Max, K2, K2 Pro, K2 Plus, Hi, Ender 3 V3 with CFS / Creality Filament System (via ha_creality_ws integration)

Works with filament from any vendor (Polymaker, Sunlu, Elegoo, Hatchbox, eSUN, Bambu Lab, generic, etc.) — not just printer-brand filament.

## Key Features

- Web dashboard showing all printers, AMS/CFS units, trays, and spool assignments
- Click-to-assign spools from Spoolman inventory with search and filters
- Automatic filament weight deduction on print completion
- Multi-AMS and multi-CFS support (multiple filament units per printer)
- Multi-brand printers on the same dashboard (e.g., Bambu Lab + Creality side by side)
- QR code scanning (scan Spoolman QR codes or custom barcodes)
- Generate and print QR code labels for spools (scan with phone to assign)
- Write spool links to NFC sticker tags (tap with phone to assign, Android only)
- Low stock alerts via Home Assistant notifications with configurable thresholds and grouping
- Kiosk mode for touchscreen spool-scanning stations (e.g., Raspberry Pi)
- Localized Home Assistant support (English, German, Dutch, Spanish, Italian, French, and more)
- Activity logging for spool changes and sync events
- External spool / non-AMS printing support

## Installation Modes

1. **Home Assistant Add-on** — installs from HA add-on store, appears in sidebar. Best for HA OS / Supervised users.
2. **Embedded Mode** — Docker Compose with bundled Home Assistant (ha-bambulab and ha_creality_ws pre-installed). Best for users without existing HA.
3. **External Mode** — Docker Compose connecting to user's existing Home Assistant. Best for users who already run HA with ha-bambulab or ha_creality_ws.

## Filament Usage Tracking

- **Bambu Lab**: Uses ha-bambulab's `print_weight` sensor (reports grams) combined with print progress for accurate per-print deduction
- **Creality**: Uses ha_creality_ws's `used_material_length` sensor (reports cm), converted to weight via filament diameter (1.75mm) and material density lookup (PLA 1.24 g/cm³, PETG 1.27, ABS 1.04, ASA 1.07, TPU 1.21, PC 1.20, Nylon 1.14, etc.)

Matching works by:
- Manual tray assignment via the web UI (works for all vendors)
- RFID auto-match using Bambu `tray_uuid` or Creality `rfid` for repeat swaps
- QR code / NFC tag lookup for any vendor

## Docs

- [README - Installation and Setup](https://raw.githubusercontent.com/gibz104/SpoolmanSync/main/README.md): Complete setup for add-on, embedded, and external modes

## Links

- [GitHub Repository](https://github.com/gibz104/SpoolmanSync)
- [Home Assistant Community Post](https://community.home-assistant.io/t/spoolmansync-automatic-filament-tracking-for-bambu-lab-printers-beginner-friendly/977383)
- [Docker Hub](https://hub.docker.com/r/gibz104/spoolmansync)
- [GitHub Issues](https://github.com/gibz104/SpoolmanSync/issues)

## Optional Dependencies

- [Spoolman](https://github.com/Donkie/Spoolman): Filament inventory manager that SpoolmanSync syncs with
- [ha-bambulab](https://github.com/greghesp/ha-bambulab): Home Assistant integration for Bambu Lab printers
- [ha_creality_ws](https://github.com/3dg1luk43/ha_creality_ws): Home Assistant integration for Creality printers