SpoolmanSync

The easiest way to sync Bambu Lab AMS filament with Spoolman

Tired of manually editing YAML files? SpoolmanSync provides a modern web UI for Bambu Lab filament tracking with Spoolman - no Home Assistant expertise required.

SpoolmanSync automatically tracks which filament spools are loaded in your Bambu Lab printer's AMS units and syncs this information with Spoolman for accurate filament inventory management. Works with all filament brands - not just Bambu Lab spools.

Why SpoolmanSync?

Feature	SpoolmanSync	Other Solutions
Web UI for spool assignment	✅	❌
QR/Barcode scanning	✅	❌
Printable QR code labels	✅	❌
NFC tag writing	✅	❌
Home Assistant add-on	✅	❌
Bundled Home Assistant option	✅	❌
No YAML editing required	✅	❌
Multi-AMS support	✅	Limited
Non-English Home Assistant support	✅	❌
Works with ANY filament brand	✅	Partial
Automatic filament usage tracking	✅	✅

Features

• Dashboard - View all your printers, AMS units, and tray assignments at a glance
• Spool Assignment - Click any tray to assign a spool from your Spoolman inventory
• QR Code Scanning - Scan Spoolman QR codes or custom barcodes to quickly look up and assign spools
• QR Label Generation - Create and print QR code labels for your spools. Scan with your phone camera to quickly assign to AMS trays
• NFC Tag Writing - Write spool links to NFC sticker tags. Tap with your phone to assign spools (Android only: Chrome, Edge, Opera, Samsung Internet)
• AMS 2 Pro & AMS HT Support - Works with all AMS hardware variants
• Bambu Cloud Login - Add printers by logging in with your Bambu Cloud account
• Home Assistant Add-on - Install directly from the HA add-on store with sidebar integration
• Bundled Home Assistant - Includes a pre-configured Home Assistant with ha-bambulab integration
• Webhook Integration - Receives tray change events from Home Assistant automations
• Activity Logging - Track all spool changes and sync events

Home Assistant Add-on (Recommended for HA OS users)

If you're running Home Assistant OS or Supervised, install SpoolmanSync directly as an add-on:

1. Add this repository to your add-on store:
   • Go to Settings → Add-ons → Add-on Store
   • Click ⋮ (top right) → Repositories
   • Add: https://github.com/gibz104/SpoolmanSync
2. Find SpoolmanSync in the store and click Install
3. Start the add-on and enable Show in sidebar
4. Open SpoolmanSync from the sidebar — your printers are automatically discovered from ha-bambulab
5. Configure your Spoolman URL in Settings (or in the add-on configuration tab)
6. Go to Automations and click Configure Automations

Port conflict? The add-on uses port 3000 by default for direct access and QR/NFC scanning. If another add-on or service is already using port 3000, change it in the add-on's Configuration tab.

Requirements: ha-bambulab integration installed via HACS and Spoolman running and accessible from Home Assistant.

---

Quick Install (Pre-built Images)

The fastest way to get started with Docker using pre-built images:

# Download the compose file
curl -O https://raw.githubusercontent.com/gibz104/SpoolmanSync/main/docker-compose.prebuilt.yml

# Start with embedded Home Assistant (recommended for most users)
docker compose -f docker-compose.prebuilt.yml --profile embedded up -d

# Or, if you already have Home Assistant with ha-bambulab
docker compose -f docker-compose.prebuilt.yml --profile external up -d

Then open http://localhost:3000 and follow the setup steps below.

---

Building from Source

If you prefer to build locally or want to contribute:

1. Clone the Repository

git clone https://github.com/gibz104/SpoolmanSync.git
cd SpoolmanSync

2. Choose Your Mode

SpoolmanSync requires a Docker Compose profile. Choose based on your setup:

Mode	Command	Best For
Add-on	See above	HA OS / Supervised users
Embedded	docker compose --profile embedded up -d	Most users - includes bundled Home Assistant
External	docker compose --profile external up -d	Users who already have Home Assistant with ha-bambulab

---

Embedded Mode Setup (Recommended)

Use this if you don't have Home Assistant or want a simpler setup.

Step 1: Start the Application

docker compose --profile embedded up -d

Step 2: Open the UI

Go to http://localhost:3000 in your browser.

Step 3: Add Your Printer

1. Go to Settings in the navigation
2. Click Add Printer
3. Log in with your Bambu Cloud email and password
4. Enter the verification code sent to your email
5. Select your printer from the list
6. Click Continue

Embedded.Step.3.mp4

Step 4: Connect Spoolman

1. In Settings, scroll to the Spoolman section
2. Enter your Spoolman URL (e.g., http://127.0.0.1:7912)
3. Click Connect

Embedded.Step.4.mp4

Step 5: Set Up Automations

This enables automatic tray change detection.

1. Go to Automations in the navigation
2. Click Configure Automations
3. The automations are automatically created in the embedded Home Assistant

Embedded.Step.5.mp4

You're Done!

Your dashboard should now show your printer with AMS trays. Click any tray to assign a spool from your Spoolman inventory.

---

External Mode Setup

Use this if you already have Home Assistant with ha-bambulab configured.

Step 1: Start the Application

docker compose --profile external up -d

Step 2: Open the UI

Go to http://localhost:3000 in your browser.

Step 3: Connect Home Assistant

1. Go to Settings in the navigation
2. Enter your Home Assistant URL (e.g., http://127.0.0.1:8123)
3. Click Connect with Home Assistant
4. You'll be redirected to Home Assistant to authorize SpoolmanSync
5. Enter you Home Assistant credentials and click "Log in"

External.Step.3.mp4

Your printers should automatically appear on the dashboard (discovered from ha-bambulab).

Step 4: Connect Spoolman

1. In Settings, scroll to the Spoolman section
2. Enter your Spoolman URL (e.g., http://127.0.0.1:7912)
3. Click Connect

External.Step.4.mp4

Step 5: Set Up Automations

This enables automatic spool tracking and filament usage monitoring.

1. Go to Automations in the navigation
2. Enter the SpoolmanSync URL - the address where Home Assistant can reach SpoolmanSync (e.g., http://192.168.1.100:3000). Use your machine's IP address, not localhost, if Home Assistant is on a different machine.
3. Click Generate Configuration
4. You'll see two YAML configurations:
   • configuration.yaml - Copy and add to your Home Assistant's configuration.yaml
   • automations.yaml - Copy and add to your Home Assistant's automations.yaml
5. Restart Home Assistant
6. Return to SpoolmanSync and click Mark as Configured

External.Step.5.mp4

You're Done!

Your dashboard should now show your printers with AMS trays. Click any tray to assign a spool from your Spoolman inventory.

---

Stopping and Restarting

Always use the same profile you used to start:

# Embedded mode
docker compose --profile embedded down      # Stop
docker compose --profile embedded up -d     # Start

# External mode
docker compose --profile external down      # Stop
docker compose --profile external up -d     # Start

---

How It Works

1. Discovery: SpoolmanSync connects to Home Assistant and discovers Bambu Lab printers via the ha-bambulab integration entities.

2. Manual Assignment: Users can manually assign spools to trays via the dashboard or by scanning QR codes.

3. Automatic Sync: When Home Assistant automations detect tray changes, they call the SpoolmanSync webhook with tray information (color, material, tag UID). SpoolmanSync matches this to spools in Spoolman and updates the active_tray extra field.

4. Spoolman Integration: All spool assignments are stored in Spoolman's extra field as active_tray, making it compatible with other Spoolman integrations.

---

Troubleshooting

"No service selected" when running docker compose

You must specify a profile:

docker compose --profile embedded up -d
# or
docker compose --profile external up -d

No printers found

Embedded mode:

• Make sure you've added a printer via the Add Printer button
• Check that your Bambu Cloud credentials are correct

External mode:

• Ensure ha-bambulab integration is installed and configured in your Home Assistant
• Verify your Home Assistant URL is correct and you authorized SpoolmanSync
• Check the Logs page for error messages

Webhook not working

• Verify the automations were added to Home Assistant
• Make sure you clicked Mark as Configured after adding the automations
• Check that the SpoolmanSync URL you entered is reachable from Home Assistant (use your machine's IP address, not localhost)
• Check that SpoolmanSync is accessible from Home Assistant's network

QR scanner not working

• HTTPS required for remote access: Browsers block camera access on insecure HTTP connections. If you're accessing SpoolmanSync from a different device (not localhost), you'll need to set up HTTPS (e.g., via a reverse proxy or Tailscale)
• Ensure you've granted camera permissions in your browser
• Try using a different camera if available
• Use manual search as a fallback

NFC tag writing not working

• HTTPS required: Web NFC requires a secure context. If you're not on localhost, you'll need HTTPS (e.g., via a reverse proxy or Tailscale)
• Android only: Web NFC is only supported on Android devices with Chrome, Edge, Opera, or Samsung Internet browsers
• Not supported: iOS (any browser), Firefox, and Brave do not support Web NFC
• If NFC is unavailable, SpoolmanSync shows a URL template you can use with a dedicated NFC writing app
• Make sure NFC is enabled in your device settings
• Use NTAG213, NTAG215, or NTAG216 NFC sticker tags

---

License

MIT License - see LICENSE.txt

Contributing

Contributions are welcome! Please open an issue or pull request.