Skip to content

How It Works

SpoolSense has three layers: the scanner (hardware), the middleware (optional, for Klipper integration), and your spool manager (Spoolman).

Scan Flow

  NFC Tag on Spool
        |
        v
  +-----------+     WiFi/MQTT      +------------+
  |  Scanner  | -----------------> | Middleware  |
  |  (ESP32)  |                    | (Klipper)  |
  +-----------+                    +------------+
        |                                |
        | HTTP                           | HTTP
        v                                v
  +-----------+                    +-----------+
  | Spoolman  |                    | Moonraker |
  +-----------+                    +-----------+
        |
        v
  +----------------+
  | Home Assistant |
  +----------------+

Step by Step

1. Tag Scanned

Place a spool with an NFC tag on the scanner. The ESP32 reads the tag over SPI using either a PN5180 or PN532 NFC reader. The read happens in a continuous scan loop running in its own FreeRTOS task, so detection is near-instant.

2. Tag Classified

The firmware auto-detects the tag format based on the NFC protocol and tag contents:

  • ISO15693 (8-byte UID) ... OpenPrintTag on ICODE SLIX2 (PN5180 only)
  • ISO14443A (4 or 7-byte UID) ... the firmware reads the tag pages and checks for known formats:
    • TigerTag ... binary layout starting at page 4 with a known version signature
    • OpenTag3D ... CBOR-encoded data with OpenTag3D MIME type
    • OpenSpool ... NDEF JSON with "protocol":"openspool"
    • Bambu Lab ... MIFARE Classic detected by SAK byte (UID-only, encrypted data)
    • Generic UID ... plain NTAG with no recognized data format

Each format has its own parser that extracts material, color, weight, manufacturer, temperatures, and other fields.

3. Spoolman Synced

If Spoolman is configured, the scanner syncs over HTTP after each scan. Smart tags (OpenPrintTag, TigerTag, OpenTag3D, OpenSpool) carry filament data directly — the scanner finds or creates a matching spool entry in Spoolman automatically. Basic UID tags carry only a UID and rely on Spoolman for their filament data — if no match exists, the user can register the tag via the web UI.

4. LED + Display Feedback

If a status LED is enabled, the scanner shows the spool's filament color on the LED. The actual hex color from the tag or Spoolman is used, so a red PLA spool lights up red. Black filament shows as dim white (so you can tell a spool is scanned vs. no spool). The LED also flashes white on tag detection, green on successful writes, and red on errors.

If a TFT display is attached (ST7789 square or GC9A01 round, 240x240), it shows a colored spool graphic with filament color fill, weight bar, brand/material name, and tag format icon. If a 16x2 LCD is attached, it displays the material type, remaining weight, and status messages.

5. MQTT Published

The scanner publishes spool state to MQTT. Home Assistant auto-discovers the scanner as a device with sensors for material, color, weight, manufacturer, and scanner status. All sensors update in real time as spools are scanned and removed.

6. Middleware Routes (Optional)

If running the middleware on your Klipper host, it receives the MQTT scan event and handles printer-side integration:

  • Assign the spool to an AFC lane or toolhead ... the middleware sends gcode commands to Klipper (SET_SPOOL_ID, SET_ACTIVE_SPOOL, ASSIGN_SPOOL) and saves the assignment to Klipper variables so it persists across reboots.
  • Set AFC lane colors ... when a spool is assigned to an AFC lane (BoxTurtle, NightOwl), the middleware sends the filament color to the lane's LED via SET_COLOR gcode. The lane lights up to match the loaded filament.
  • Set scanner LED color ... for UID-only tags that have no color on the tag itself, the middleware looks up the color from Spoolman and sends it back to the scanner via MQTT. The scanner LED then shows the correct filament color.
  • Write spool data to Moonraker's lane_data ... slicer integration for Orca Slicer and others. Tool info (color, material, weight, temperatures) is written to Moonraker's database so the slicer auto-populates tool settings.
  • Update the NFC tag with remaining weight ... after a print, the middleware can write the updated remaining weight back to the NFC tag so the tag stays accurate even offline. (Opt-in feature, disabled by default.)

With vs Without Middleware

Feature Scanner Only Scanner + Middleware
Read NFC tags ✅ ✅
Spoolman sync ✅ ✅
Home Assistant sensors ✅ ✅
Scanner LED filament color ✅ from tag or Spoolman ✅ from tag or Spoolman
TFT / LCD display ✅ ✅
AFC lane assignment ❌ ✅
AFC lane color LEDs ❌ ✅
Toolchanger support ❌ ✅
Keypad tool assignment ✅ ✅
Tag weight writeback ❌ ✅
Slicer integration (Orca) ❌ ✅

The scanner works standalone for basic spool tracking, Spoolman sync, and Home Assistant. Add the middleware when you need Klipper/AFC integration, lane colors, or tag writeback.