mirror of
https://github.com/Donkie/Spoolman.git
synced 2026-10-23 02:22:20 -05:00
Donkie
9ec5181d4c
The client half of design/nfc-phase-1-tag-identity.md, against the API that
landed in de533bc.
A spool's inspector grows a Tags section listing what is linked to it, with
adding as a quiet section action rather than another button in a header that
already carries the spool's primary actions. The dialog behind it takes a UID
from whichever source is to hand -- a reader tapping the tag, this phone over
Web NFC, or typing -- and resolves it as it settles, so "already on spool #12"
arrives before you commit rather than as a rejected submit. That case is
offered as one button that moves the tag, because the alternative is sending
the user to find the other spool and unlink it by hand.
The relay client is deliberately not part of live.ts. That module is one socket
per entity resource, each feeding the inventory cache, and a scan is not an
entity: it has no id, nothing to cache it under, and its URL carries a reader
id where live.ts's carries a resource name. The connection behaviour is worth
sharing, so the backoff, the wake-on-online/visible listeners, the keepalive
and the 401 probe are copied rather than generalized over both.
Which reader a browser listens to is settled by walking over and tapping a tag
on it: subscribe to every reader, take the id off the first scan, narrow to
that one. No codes, no server state, and the binding is self-evidently right
because the user made it with their hands.
Auto-navigate is off by default and subscribes only while it is on, so a
browser not using NFC holds no relay socket at all. Exactly one subscriber, in
the root layout, since two components reacting to one tap is how you get a
double navigation. It stands down while a dialog is open, while the tag dialog
holds it, and while a field is being typed in -- a tag tapped in the next room
must not take a half-typed value with it.
Web NFC is progressive enhancement: absent, not disabled, on desktop, iOS,
Firefox and every plain-HTTP install. A tag's serial is readable without
decoding its contents, so phase 1 needs no NDEF parsing.
Verified with six Playwright specs driving the relay over plain POSTs, which is
what the reader contract being ordinary HTTP buys -- the whole feature is
exercised without NFC hardware. Web NFC itself has no automated cover and
cannot; what is asserted is that its control is absent where it cannot work.
Keep track of your inventory of 3D-printer filament spools.
Spoolman is a self-hosted web service designed to help you efficiently manage your 3D printer filament spools and monitor their usage. It acts as a centralized database that seamlessly integrates with popular 3D printing software like OctoPrint and Klipper/Moonraker. When connected, it automatically updates spool weights as printing progresses, giving you real-time insights into filament usage.
Features
- Filament Management: Keep comprehensive records of filament types, manufacturers, and individual spools.
- API Integration: The REST API allows easy integration with other software, facilitating automated workflows and data exchange.
- Real-Time Updates: Stay informed with live spool updates through Websockets, providing immediate feedback during printing operations.
- Central Filament Database: A community-supported database of manufacturers and filaments simplify adding new spools to your inventory. Contribute by heading to SpoolmanDB.
- Web-Based Client: Spoolman includes a built-in web client that lets you manage data effortlessly:
- View, create, edit, and delete filament data.
- Search, group and filter your inventory by manufacturer, material, location and more.
- Add custom fields to tailor information to your specific needs.
- Design and print labels with QR codes for easy spool identification and tracking.
- Contribute to its translation into 18 languages via Weblate.
- Database Support: SQLite, PostgreSQL, MySQL, and CockroachDB.
- Multi-Printer Management: Handles spool updates from several printers simultaneously.
- Advanced Monitoring: Integrate with Prometheus for detailed historical analysis of filament usage, helping you track and optimize your printing processes. See the Wiki for instructions on how to set it up.
Spoolman integrates with:
- Moonraker and most front-ends (Fluidd, KlipperScreen, Mainsail, ...)
- OctoPrint
- OctoEverywhere
- Home Assistant
- MCP Server - Manage your filament inventory through AI assistants like Claude using the Model Context Protocol
Web client preview:
 |
 |
| Dashboard — spools as cards, grouped by location or any other field. Drag one to move it. | Label designer — QR labels built from any spool, filament or vendor field. |
Installation
Please see the Installation page on the Wiki for details how to install Spoolman.
If the new client misbehaves on your setup, set SPOOLMAN_LEGACY_CLIENT=TRUE to go back to
the previous one. Both ship in every release and talk to the same API, so your data is
untouched either way — but please report the problem
so it can be fixed.