Middleware Setup

The SpoolSense middleware bridges the scanner to Klipper/AFC. It typically runs on your Klipper host (Raspberry Pi), but can run on any machine on your network that can reach the MQTT broker and Moonraker.

Do I Need This?

You need the middleware if you want:

• AFC lane assignment (BoxTurtle, tradrack)
• Toolchanger spool assignment
• Tag weight writeback after prints
• Slicer integration (Orca Slicer lane data)

If you only need Spoolman sync and Home Assistant, the scanner handles that directly. No middleware needed.

Install

SSH into your Klipper host and run:

ssh pi@your-printer-ip
curl -sL https://raw.githubusercontent.com/SpoolSense/spoolsense-installer/main/install.sh | bash

Choose "Middleware only" when asked what to install. Here's what the installer looks like:

╔══════════════════════════════════════╗
║       SpoolSense Installer           ║
╚══════════════════════════════════════╝

What do you want to install?
  1) Scanner + Middleware (recommended)
  2) Scanner only
  3) Middleware only
  4) Config only (source builds)
Choice [1]: 3

── Connection Settings ─────────────────

  (These must match your scanner's config)

MQTT broker host: 192.168.1.50
MQTT port [1883]:
MQTT username []:
MQTT password []:

── Middleware Configuration ────────────

Scanner setup:
  1) AFC shared scanner (scan spool, load any lane)
  2) AFC per-lane scanners (one scanner per lane)
  3) Toolchanger shared scanner (scan spool, assign via macro or keypad)
  4) Toolchanger per-toolhead scanners (one scanner per tool)
  5) Single toolhead (one scanner, one extruder)
Choice [1]: 1

  Note: After flashing your scanner, find its device ID
  from the MQTT topic: spoolsense/<device_id>/tag/state

Moonraker URL [http://localhost]: http://localhost

  Slicer integration: Slicers like Orca Slicer can auto-populate
  tool colors, materials, and temps from your scanned spools.

Enable slicer integration for toolheads? [y/N]: y

── Installing Middleware ────────────────

  Cloning SpoolSense middleware...
  ✓ Repository ready
  Installing Python dependencies...
  ✓ Dependencies installed
  ✓ Config written to ~/SpoolSense/middleware/config.yaml
  Creating systemd service...
  ✓ Service created and enabled

══════════════════════════════════════
  SpoolSense is installed!

  Middleware: systemctl status spoolsense
  Config:     ~/SpoolSense/middleware/config.yaml
══════════════════════════════════════

Manual Install (Advanced)

For advanced users only

Most users should use the installer above.

git clone https://github.com/SpoolSense/spoolsense_middleware.git ~/SpoolSense
cd ~/SpoolSense/middleware
pip3 install -r requirements.txt
cp config.example.yaml config.yaml
# Edit config.yaml with your settings

Configuration

Finding Your Scanner's Device ID

The middleware identifies each scanner by its device ID. You need this to configure the scanners: section.

To find it:

1. Power on the scanner and connect to http://spoolsense.local
2. The device ID is displayed on the landing page (e.g. ecb008)
3. It's also available at http://spoolsense.local/api/status in the device_id field

Edit config.yaml

mqtt:
  host: localhost
  port: 1883

spoolman:
  url: http://localhost:7912

moonraker:
  url: http://localhost:7125

scanners:
  ecb008:                    # Replace with YOUR scanner's device ID
    action: toolhead          # or afc_lane, afc_stage, toolhead_stage
    target: T0                # Tool or lane name
    publish_lane_data: true   # Write to Moonraker DB for slicer integration

Tip

If you have multiple scanners, add each one as a separate entry under scanners: with its own device ID and action.

Actions

Action	Use Case
toolhead	Single toolhead. Scan assigns spool directly.
toolhead_stage	Toolchanger. Scan stages spool, ASSIGN_SPOOL macro assigns to tool.
afc_lane	AFC, one scanner per lane. Scan assigns to that lane.
afc_stage	AFC, shared scanner. Scan stages spool, lane load triggers assignment.

Running as a Service

Note

The installer sets this up automatically. These commands are only needed if you installed manually.

sudo cp ~/SpoolSense/middleware/spoolsense.service /etc/systemd/system/
sudo systemctl enable spoolsense
sudo systemctl start spoolsense

Check status:

sudo systemctl status spoolsense
journalctl -u spoolsense -f

Automatic Updates via Mainsail

Add SpoolSense to Moonraker's update manager so you get notified of new versions in Mainsail's update panel.

Add this to your moonraker.conf:

[update_manager spoolsense]
type: git_repo
path: ~/SpoolSense
origin: https://github.com/SpoolSense/spoolsense_middleware.git
primary_branch: master
managed_services: spoolsense

Then restart Moonraker:

sudo systemctl restart moonraker

SpoolSense will now appear in Machine → Update Manager in Mainsail. When a new version is available, you can update with one click — Moonraker pulls the latest code and restarts the service automatically.