FilaBridge

UPDATE: DEVELOPMENT IS TEMPOARILY HALTED. DUE TO MY PRUSA PRINTERS BOTH BREAKING DOWN AND NEEDING REPAIRS

A high-performance Go microservice that bridges PrusaLink-compatible printers and Spoolman for (mostly) automatic filament inventory management. Originally designed for Prusa printers (CORE One, XL, MK4, etc.) but works with any printer that supports the PrusaLink API.

The Problem

I run multiple 3D printers and use Spoolman to track my filament inventory. The issue? I had to manually update filament usage after every print. With multi-material prints on my Prusa XL, this was getting tedious and error-prone.

Features

• 🔗 PrusaLink Compatibility: Works with any PrusaLink-compatible printer (Prusa CORE One, XL, MK4, Mini, and more)
• 📊 Real-time Dashboard: Web interface with live updates via WebSocket connections
• 🎯 Multi-Toolhead Support: Seamlessly handles single and multi-toolhead printers (tested with 5-toolhead Prusa XL)
• 📈 Smart Usage Tracking: Automatically parses G-code files to accurately track filament consumption per toolhead
• 💾 Persistent Storage: SQLite database stores toolhead mappings and complete print history
• ⚡ High Performance: Single lightweight binary, minimal resource usage, fast execution
• 🔧 Web-based Config: No config files needed - manage everything through the web UI
• 🔍 Smart Spool Search: Search and filter spools by ID, material, brand, or name with real-time filtering
• ⚠️ Error Handling: Print error detection with acknowledgment system for failed filament tracking
• 🔄 Auto-mapping: Automatic spool assignment when selecting from dropdown menus
• 🌐 Live Updates: Real-time status updates without page refreshes using WebSocket technology
• 🏷️ NFC Tag Support: Generate QR codes and program NFC tags for spools, filaments, and locations
• 📱 Smart Scanning: Two-step NFC workflow - scan spool + location (or location + spool) for instant assignment
• 📍 Location Tracking: Track spools in custom locations (dryboxes) or printer toolheads

Why FilaBridge?

Managing filament inventory across multiple 3D printers is tedious. FilaBridge automates this by:

• Monitoring your printers in real-time with live WebSocket updates
• Tracking which spools are loaded on which toolheads
• Automatically updating your Spoolman inventory when prints complete
• Providing accurate filament usage by parsing G-code files
• Handling errors gracefully with clear notifications and acknowledgment system
• Using NFC tags to quickly assign spools to printers or storage locations
• Tracking filament locations across your workshop

No more manual updates or guesswork about remaining filament!

Screenshots

FilaBridge main dashboard showing printer status and toolhead mappings

NFC Management interface for generating QR codes for individual spools

Filament type QR code generation for new unopened spools

Location management interface for creating printer toolhead and storage location QR codes

Prerequisites

• A PrusaLink-compatible 3D printer (Prusa or any printer with PrusaLink API)
• PrusaLink enabled on your printer(s) for local network access
• Spoolman
• For building from source: Go 1.23 or higher
• (Optional) For NFC features: NFC-capable smartphone and NFC tags (NTAG213/215/216 recommended)
• (Recommendation) NFC Tools Pro mobile app (for programming tags)

Installation

Option 1: Docker (Easiest)

1. Run Spoolman (if not already running):

   docker run -d --name spoolman -p 8000:8000 -v spoolman-data:/home/spoolman/data ghcr.io/donkie/spoolman:latest
   

2. Run FilaBridge:

   docker run -d --name filabridge -p 5000:5000 \
     -v .:/app/data \
     ghcr.io/needo37/filabridge:latest
   

3. Configure: Open http://localhost:5000 and click "⚙️ Configuration"

Using docker-compose (recommended for full stack):

git clone https://github.com/needo37/filabridge.git
cd filabridge
docker-compose up -d

The docker-compose.yml automatically sets the FILABRIDGE_DB_PATH environment variable to /app/data to ensure the database persists in the mounted volume.

Option 2: Pre-built Binary

1. Download the latest release for your platform from the Releases page

   • Linux (amd64, arm64)
   • macOS (amd64/Intel, arm64/Apple Silicon)
   • Windows (amd64)

2. Make it executable (Linux/macOS):

   chmod +x filabridge
   

3. Run Spoolman (if not already running):

   docker run -d --name spoolman -p 8000:8000 -v spoolman-data:/home/spoolman/data ghcr.io/donkie/spoolman:latest
   

4. Start FilaBridge:

   ./filabridge
   

5. Configure: Open http://localhost:5000 and click "⚙️ Configuration"

Option 3: Build from Source

1. Clone and build:

   git clone https://github.com/needo37/filabridge.git
   cd filabridge
   go mod download
   go build -o filabridge .
   

2. Run Spoolman (if not already running):

   docker run -d --name spoolman -p 8000:8000 -v spoolman-data:/home/spoolman/data ghcr.io/donkie/spoolman:latest
   

3. Start FilaBridge:

   ./filabridge
   

Configuration

The system stores all configuration in the SQLite database. For Docker deployments, you can optionally set the FILABRIDGE_DB_PATH environment variable to specify where the database should be stored (defaults to /app/data in Docker).

First Run

1. Start the application
2. Open the web interface at http://localhost:5000
3. Click "Start Configuration" button
4. Enter a name for your Printer.
5. Enter your PrusaLink IP Address and API key
6. Choose the number of toolheads your printer has.
7. Click "Save Configuration"
8. The service will automatically restart with new settings

Usage

Running the Service

# Run both bridge service and web interface (recommended)
./filabridge

# Custom host and port
./filabridge --host 0.0.0.0 --port 8080

Web Interface

The web interface provides:

• Printer Status: Real-time view of printer states and current jobs with live WebSocket updates
• Toolhead Mapping: Assign filament spools to specific toolheads with smart search functionality
• Progress Monitoring: Visual progress bars for active prints
• Live Updates: Real-time status updates without page refreshes
• Spool Search: Search and filter spools by ID, material, brand, or name
• Error Management: View and acknowledge print processing errors
• Auto-mapping: Automatic spool assignment when selecting from dropdowns

Filament Management

1. Add spools to Spoolman: Use Spoolman's web interface to add your filament spools
2. Map spools to toolheads: Use the FilaBridge web interface to assign spools with smart search
3. Monitor usage: The system automatically tracks and updates filament usage
4. Handle errors: Acknowledge any print processing errors that require manual intervention

NFC Tag Management

1. Generate QR Codes: Navigate to NFC Management tab in the web interface
2. Create Tags:
   • Spool Tags: Generate QR codes for individual spools
   • Filament Tags: Generate QR codes for filament types (for new unopened spools)
   • Location Tags: Create and generate QR codes for printer toolheads and custom locations (dryboxes, storage shelves, etc.)
3. Program NFC Tags: Use NFC Tools Pro to scan QR codes and write URLs to NFC tags
4. Assign Spools: Tap spool tag, then location tag (location then spool works as well) to instantly assign and update inventory

API Endpoints

The web interface also provides REST API endpoints:

• GET /api/status - Get current printer status and mappings
• GET /api/spools - Get all spools from Spoolman
• POST /api/map_toolhead - Map a spool to a toolhead
• POST /api/unmap_toolhead - Unmap a spool from a toolhead
• GET /api/print-errors - Get all unacknowledged print errors
• POST /api/print-errors/{id}/acknowledge - Acknowledge a print error
• GET /api/nfc/assign - Handle NFC tag scans (spool or location)
• GET /api/nfc/urls - Get all NFC URLs with QR codes
• GET /api/nfc/session/status - Check NFC session status
• GET /api/locations - Get all locations
• POST /api/locations - Create custom location
• PUT /api/locations/{name} - Rename location
• DELETE /api/locations/{name} - Delete location
• WS /ws/status - WebSocket endpoint for real-time status updates

Project Structure

filabridge/
├── main.go                 # Application entry point
├── config.go              # Configuration management
├── prusalink.go           # PrusaLink API client
├── spoolman.go            # Spoolman API client
├── bridge.go              # Core monitoring and tracking logic
├── nfc.go                 # NFC session management and tag handling
├── web.go                 # HTTP server and web interface
├── templates/             # HTML templates
├── go.mod                 # Go module definition
└── README.md              # Documentation

Troubleshooting

Common Issues

1. **Print