feat: Add NFC spool identification: TigerTag and OpenPrintTag support

[goeland86]

Summary

Adds NFC tag support to Spoolman, enabling automatic spool identification by scanning NFC-equipped filament spools. Two open tag formats are supported:

• TigerTag (ISO 14443A / NTAG213) — binary format with product IDs from the TigerTag external database
• OpenPrintTag (ISO 15693 / NFC-V) — Prusa's open NDEF/CBOR standard with per-spool UUIDs

Usage

There are three ways to scan NFC tags with Spoolman:

Browser-based scanning — The Spoolman web client includes an NFC scanner modal that uses the Web NFC
API to read and write tags directly from your phone or NFC-equipped computer. No
additional hardware or software needed — just open the Spoolman UI in Chrome on Android and tap a tag.

Server-side USB reader — Attach a USB NFC reader (e.g. ACR1552U) to the machine running Spoolman. Enable with SPOOLMAN_NFC_ENABLED=TRUE. The
/api/v1/nfc/read and /api/v1/nfc/write endpoints control the reader directly.

External reader with API integration — For setups where the NFC reader is physically attached to the printer (not the Spoolman server), the POST /api/v1/nfc/lookup endpoint accepts raw tag memory from any client and handles all decoding and spool matching server-side. An example implementation
is klipper-nfc-daemon, a lightweight daemon that runs on a Klipper host, polls an NFC reader, and
automatically sets the active spool in Moonraker. It supports PN532 (UART), PN5180 (SPI), and ACR1552U (USB) readers.

Backend

• POST /api/v1/nfc/lookup — unified endpoint that auto-detects tag format from raw bytes, matches to a spool, and optionally auto-creates
  spool/filament/vendor records from tag data
• POST /api/v1/nfc/read / write / encode — server-side NFC reader endpoints
• POST /api/v1/nfc/create-from-tag — create spool from decoded TigerTag data
• TigerTag binary codec (big-endian, NTAG213 144-byte format) with external product DB sync
• OpenPrintTag NDEF TLV parser + CBOR decoder with UUID derivation per spec
• Spool matching by external_id (tigertag_{id} or opt_{instance_uuid}) — no database migrations needed

Frontend

• NFC scanner modal with browser Web NFC API support
• NFC tag write modal for encoding spools onto tags
• Client-side TigerTag codec for browser-based tag reading/writing

Infrastructure

• Dockerfile updated with libusb and uv --extra nfc for optional NFC dependencies
• New optional dependencies: cbor2, ndeflib, nfcpy (in [nfc] extra)
• Environment flags: SPOOLMAN_NFC_ENABLED, SPOOLMAN_TIGERTAG_ENABLED

Design decisions

• NFC support is fully optional — gated behind environment variables, no impact on existing installations
• No database migrations — uses existing external_id field on Filament for tag-to-spool mapping
• Tag format auto-detection: 0xE1 first byte = OpenPrintTag (NFC-V capability container), 0x5C15E2E4 magic = TigerTag

Test plan

• Existing tests pass (no schema changes)
• TigerTag: scan NTAG213 tag → spool matched by external_id
• TigerTag: scan unknown tag → auto-create spool from TigerTag product DB
• OpenPrintTag: decode CBOR payload with all field types
• OpenPrintTag: match spool by instance_uuid derived from tag UID
• OpenPrintTag: auto-create spool with vendor/filament from tag data
• NFC endpoints return 200 with enabled: false when NFC is not configured
• Frontend NFC scanner modal opens and reads tags via Web NFC API

🤖 Generated with Claude Code

[goeland86]

I unfortunately don't have OpenPrintTag tested because I lack the physical hardware at present. If anyone else wants to test this, please do share the test results.

[akira69]

Without digging into this or thinking too much, I wonder if you have considered to cross support with spoolease too - though the NFC info would be coming via a spoolease api instead of direct from the scanner. anyway, cool! more features :)

[goeland86]

I had not, but I can easily try to get that implemented? I don't pretend to know every format or effort to support nfc for 3D printing 😉.

I would need help getting the tests done for anything I don't have access to, but I'm happy to do it.

[turw41th]

How easy would it be to also add support for Qidi NFC tags for usage with their Qidi Box system? They have it documented here: https://wiki.qidi3d.com/en/QIDIBOX/RFID
I would be happy to help you test this as I have a Qidi Box.

[goeland86]

Let me look. The question is whether I have the hardware to test it. I'm mostly using the tiger tag format right now for cost reasons.

[goeland86]

@turw41th so looking at it closer, it looks like we can add it easily. But we'd be using the tag's hardware UID to bind it to an entry in Spoolman. It's exactly what it does with Tigertags, so that's not an issue architecturally. But they're MIFARE tags as opposed to NTAG213 which is what I have on hand, so I won't be able to test it. If you're willing to test it out, I'll have my fork updated with it shortly.

[goeland86]

Qidi NFC Tag Support

This update adds support for Qidi RFID tags (MIFARE Classic 1K / FM11RF08S) alongside the existing TigerTag and OpenPrintTag formats.

What's new

Qidi tags are ISO 14443A MIFARE Classic 1K tags used by Qidi 3D printers and the QIDIBOX filament management system. They store a simple 3-byte payload: material code, color code, and manufacturer ID. Spoolman now reads, writes, and auto-detects these tags through the same NFC infrastructure used for TigerTag and OpenPrintTag.

How it works

• Auto-detection: The server-side NFC reader automatically detects whether a scanned tag is NTAG213 (TigerTag), NFC-V (OpenPrintTag), or MIFARE Classic (Qidi) and routes to the correct decoder.
• UID-based binding: Since Qidi tags only store material + color (no unique spool ID), binding uses the tag's hardware UID. Scan once to bind, and all future scans of that physical tag resolve to the same spool.
• Fuzzy matching: If no UID binding exists, Spoolman fuzzy-matches by material type and color hex against existing spools.
• Auto-create: Unrecognized Qidi tags can auto-create a spool with the correct Qidi vendor, material name (e.g. "Qidi PLA Silk"), and color.
• Writing: Spools can be written to blank MIFARE Classic 1K tags in Qidi format from the web UI.
• Lookup endpoint: The /api/v1/nfc/lookup endpoint accepts tag_type: "qidi" or auto-detects from 16-byte block data, so Klipper integrations work out of the box.

Supported Qidi materials & colors

• 35 materials: PLA, PLA Matte, PLA Silk, PLA-CF, ABS, ABS-GF, ASA, PA-CF, PAHT-CF, PETG, PETG-CF, PPS-CF, TPU, PVA, and more
• 24 colors: White, Black, Red, Blue, Yellow, Orange, Green, Purple, Pink, and more — each mapped to an RGB hex value

Authentication

Qidi tags use MIFARE Classic Crypto-1 authentication with Key A. Two keys are tried in sequence:

1. Qidi custom key: D3:F7:D3:F7:D3:F7 (factory Qidi tags)
2. Default key: FF:FF:FF:FF:FF:FF (blank MIFARE Classic tags)

Files changed

File	Description
spoolman/qidi_codec.py	New — Material/color lookup tables, 3-byte encode/decode, auto-detection
spoolman/qidi_lookup.py	New — UID-based spool binding, fuzzy matching, auto-create
spoolman/nfc_service.py	Added read_tag_auto() with MIFARE Classic detection, dual-key auth read/write
spoolman/api/v1/nfc.py	Added QidiTagDataResponse, Qidi handling in all NFC endpoints
client/src/utils/nfc.ts	Added QidiTagData interface, updated request/response types
client/src/components/nfcScannerModal.tsx	Shows Qidi tag summary, creates spools from Qidi data
client/src/components/nfcBindModal.tsx	Supports Qidi UID-based tag binding
client/src/components/nfcWriteModal.tsx	Tag format selector (TigerTag / Qidi)
client/public/locales/en/common.json	New translation keys for Qidi UI
README.md	Updated NFC feature list

API examples

Look up a Qidi tag (auto-detect):

curl -X POST /api/v1/nfc/lookup \
  -d '{"raw_data_b64": "ARIBAAAAAAAAAAAAAAAAAA==", "nfc_tag_uid": "A1B2C3D4"}'

Auto-create spool from Qidi tag:

curl -X POST /api/v1/nfc/lookup \
  -d '{"raw_data_b64": "ARIBAAAAAAAAAAAAAAAAAA==", "tag_type": "qidi", "nfc_tag_uid": "DEADBEEF", "auto_create": true}'

Write spool as Qidi tag:

curl -X POST /api/v1/nfc/write \
  -d '{"spool_id": 1, "tag_format": "qidi"}'

Reference

• Qidi RFID Wiki
• Tag chip: FM11RF08S (MIFARE Classic 1K compatible)
• Data location: Sector 1, Block 0 (absolute block 4)
• Protocol: ISO/IEC 14443-A, 13.56 MHz

[turw41th]

@goeland86 Very cool, I didn't expect you to be this quick! Let me order some matching NFC tags real quick and I'll test it out with your fork as soon as I have them.
How do you handle the supported colors? As Qidi tags only support a very specific set of colors, but spoolman allows to use all hex colors? How is that managed if I have never scanned an already written qidi specific tag, but only want to write my own tags?

[goeland86]

As Qidi tags only support a very specific set of colors, but spoolman allows to use all hex colors? How is that managed if I have never scanned an already written qidi specific tag, but only want to write my own tags?

Reading a Qidi tag → The color index (1-24) is mapped to a known RGB hex value via a lookup table (e.g. color code 18 = Red = #FF362D). That hex value gets stored on the Spoolman spool.

Writing a Qidi tag from Spoolman → Since Spoolman allows arbitrary hex colors but Qidi only supports 24 predefined colors, I use nearest-color matching: the code computes the Euclidean distance in RGB space between your spool's color and all 24 Qidi palette entries, then picks the closest one. If it's an exact match it returns immediately, otherwise it snaps to the nearest color. I'll admit I had Claude figure that distance-matching for me.

For example, a spool with color #FF0000 (pure red) would map to Qidi color code 18 ("Red", #FF362D). The Spoolman spool retains its original hex color — only the Qidi tag gets the quantized palette index.

TL;DR: You don't need to scan an existing Qidi tag first. You can write brand new tags from any Spoolman spool and the color is automatically snapped to the nearest of the 24 Qidi colors.

The relevant code is in qidi_codec.py — color_code_from_hex() handles the mapping, and COLOR_CODE_MAP defines all 24 palette entries.

[turw41th]

@goeland86 I received the tags, but I did not check the WebNFC api specs beforehand and did not notice that it cannot write or read Mifare classic tags. I also don't have an ncf reader at home. I might vibe code a native android app that acts as a front end for spoolman and uses android.nfc and test it this way. Other wise I'd have to wait for another ali express order with an nfc reader.

[goeland86]

So, I think my branch has a webNFC fork that basically transmits the byte arrays to and from Spoolman, so you should be able to use your mobile directly with spoolman in the browser? I haven't really looked into it, my use-case was aimed at PN532's hooked up to the printers, so I put a spool on the printer and it automatically sets the right Spoolman ID on klipper.

[turw41th]

I can use the tags and write the tags, as my mifare tags have an NDEF layer. But the tag will always be recognized as an NDEF tag by spoolman and it will use the tigertag format which is not being recognized by my multi material system.

[goeland86]

Ah, bummer. Let me see if I can tweak the UI to set a preferred format for the tags.

Update: re-read what you said about WebNFC not working with Mifare in general. That's annoying.

[turw41th]

Are you going to try some hack or should I look how I could test it on other ways?

[goeland86]

Are you going to try some hack or should I look how I could test it on other ways?

I'm not sure that there's much I could hack, the WebNFC is a capability built into the browser. I'd have to build a custom browser to get the hack working, and I'm not that good, even with an LLM assistant. 😓

[turw41th]

Alright no worries, I'll check if I can whip up an android native frontend app. That might take me a day or two though.