FilamentTracker Live Spool turns a Raspberry Pi into a local-network spool scale, NFC/RFID station, touchscreen dashboard, and hardware API for FilamentTracker. The Android application and FilamentTracker Server remain the inventory systems of record; Live Spool stores no second spool inventory database.
Important
Live Spool is designed for a trusted home or workshop LAN. It is not hardened for direct Internet exposure. Do not port-forward its API.
- live spool weight with NAU7802, HX711, or mock scale backends
- PN532 NFC read, verified write, and logical erase operations over I2C
- FilamentTracker JSON/NDEF spool tags and Bambu Lab RFID interoperability
- temporary Android-triggered NFC write sessions
- combined current-spool state without a local inventory database
- touchscreen dashboard, calibration wizard, diagnostics, and settings
- REST API for FilamentTracker Android and FilamentTracker Server
- external configuration and calibration storage designed to survive updates
- idempotent installer, preservation-first updater, and safe uninstaller
Tested appliance:
- Raspberry Pi 5 with 64-bit Raspberry Pi OS Trixie
- ELECROW 7-inch 1024×600 touchscreen
- PN532 NFC reader in I2C mode at
0x24 - NAU7802 load-cell ADC at
0x2A - 5 kg four-wire load cell
Also supported in software:
- HX711 load-cell ADC using BCM GPIO pins (defaults: data 5, clock 6)
- mock hardware on Linux development systems
Raspberry Pi 5 running 64-bit Raspberry Pi OS Trixie is the reference and tested platform. Raspberry Pi 4 with a 64-bit Raspberry Pi OS is expected to work but has not yet received the same hardware validation. See Hardware before wiring anything.
The complete build package is under hardware/:
| Guide | Purpose |
|---|---|
| Bill of Materials | Components, quantities, and build notes |
| Wiring Diagram | Raspberry Pi, NFC, scale ADC, and load-cell connections |
| Assembly Guide | Mechanical assembly overview |
| Print Plates | Printable parts and plate organization |
| Calibration Guide | Tare, calibration, verification, and troubleshooting |
The recommended printable is the multi-plate FilamentTracker_Live_Spool.3mf.
An STL package is also
provided for OrcaSlicer, PrusaSlicer, Cura, and other slicers.
The enclosure is modified from MartinNYHC's SpoolBuddy design under CC BY 4.0. See the hardware attribution and modification record.
PN532 and NAU7802 intentionally share I2C bus 1:
| Signal | Raspberry Pi | PN532 | NAU7802 |
|---|---|---|---|
| 3.3 V | Pin 1 or 17 | VCC/VIN* | VCC/VIN* |
| Ground | Any GND | GND | GND |
| SDA1 | GPIO 2 / pin 3 | SDA | SDA |
| SCL1 | GPIO 3 / pin 5 | SCL | SCL |
* Confirm the voltage requirement printed on your exact breakout board.
Default HX711 wiring:
| HX711 | Raspberry Pi |
|---|---|
| VCC | 3.3 V |
| GND | Ground |
| DAT / DOUT | GPIO 5 / pin 29 |
| CLK / SCK | GPIO 6 / pin 31 |
Load-cell wire colors are not universal. For the tested cell, red is E+, black
is E-, green is A+, and white is A-. Verify your load-cell datasheet.
git clone https://github.com/SLCMotor/filamenttracker-live-spool.git
cd filamenttracker-live-spool
sudo ./install.shVersioned ZIP and TAR packages, installer files, checksums, and release notes are available from GitHub Releases. The complete release bundle is recommended for offline or archived installation.
The installer checks the platform, installs system packages, enables I2C, creates
a virtual environment, installs the service and optional kiosk autostart, and
verifies the local API. Existing configuration and calibration are preserved.
New installs use safe mock-hardware defaults; select nau7802 or hx711 in:
/etc/filamenttracker-live-spool/config.yaml
Then restart:
sudo systemctl restart live-spool-agent
curl --fail http://127.0.0.1:8001/statusDetailed instructions: Installation.
Configuration precedence is environment variables, external YAML, then the repository development defaults. Appliance files are:
/etc/filamenttracker-live-spool/config.yaml
/etc/filamenttracker-live-spool/live-spool.env
/var/lib/filamenttracker-live-spool/calibration.json
Configurable values include device name/location, API host and port, log level, runtime directory, scale backend and GPIO pins, I2C addresses, development mode, mock hardware, and local system-control availability. See Configuration.
Common endpoints:
| Method | Path | Purpose |
|---|---|---|
| GET | /health |
process health without requiring hardware |
| GET | /status |
combined appliance and hardware status |
| GET | /weight |
current scale reading |
| GET | /nfc |
NFC reader and current tag state |
| GET | /spool/current |
combined live scale and tag snapshot |
| POST | /nfc/write |
start a temporary verified write session |
| POST | /nfc/erase |
logically erase a writable NTAG |
| GET/POST | /calibration/* |
inspect or perform calibration |
Mock routes exist only in development/mock mode. System power routes are disabled by default. The API intentionally has no cloud discovery or remote-access layer. See the complete REST API and Android integration.
On the touchscreen, press and hold the Filament Tracker / Live Spool title in the upper-left corner for about one second. A progress indicator fills during the 900 ms hold, then the Technician Menu opens.
The menu provides quick access to:
- Dashboard
- Diagnostics
- Calibration
- Settings, including restart, reboot, and shutdown controls
Tap the × button or the area outside the menu to close it. The same gesture
works with a mouse by holding the primary button over the title. If the gesture
is unavailable, open /diagnostics, /calibration-wizard, or /settings
directly in the appliance browser.
Open http://<live-spool-host>:8001/calibration-wizard, remove all weight, tare,
place an accurately known weight, enter its mass, and verify the result. The
calibration file is written atomically under /var/lib and is not overwritten
by installation or updates.
 Touchscreen dashboard |
 Technician menu |
 Completed appliance |
 NAU7802 and PN532 wiring |
See the complete hardware gallery for the display, Raspberry Pi, load cell, PN532, NAU7802, HX711, breakout board, and wiring photographs. Publication copies are resized and contain no camera EXIF or GPS metadata.
cd filamenttracker-live-spool
sudo ./scripts/update.shThe updater requires a clean checkout, creates a timestamped configuration and calibration backup, performs a fast-forward-only pull, updates dependencies, restarts the service, and verifies health. It never pushes changes.
Start with:
sudo systemctl status live-spool-agent --no-pager -l
sudo journalctl -u live-spool-agent -n 100 --no-pager
i2cdetect -y 1
curl --fail http://127.0.0.1:8001/healthExpected I2C addresses are 24 for PN532 and 2a for NAU7802. See
Troubleshooting.
- Raspberry Pi 5 is the only fully validated Pi model today.
- The API assumes a trusted LAN and must not be exposed directly to the Internet.
- Bambu RFID support is read-only and depends on successful tag authentication.
- NFC writing targets compatible NTAG/NDEF tags; tag capacity varies.
- Kiosk behavior varies among Raspberry Pi OS desktop/display-server releases.
- Scale accuracy depends heavily on mechanical construction and calibration.
- validate Raspberry Pi 4 and additional displays
- improve guided hardware selection during installation
- add authentication for optional administrative operations
- expand Android and FilamentTracker Server integration tests
- validate additional enclosure variants and publish editable CAD source when available
- add upgrade rollback assistance and packaged releases
See CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md. Please report security issues privately rather than opening a public issue.
Software and original project documentation: MIT. See LICENSE and THIRD_PARTY_NOTICES.md. The derivative printable enclosure is separately licensed under CC BY 4.0; see hardware/ATTRIBUTION.md. FilamentTracker and Bambu Lab names belong to their respective owners; this project is an independent interoperability tool.