Troubleshooting¶

Common issues and solutions for SpoolBuddy.

PN5180 NFC Issues¶

PN5180 Not Responding¶

Symptoms: No tag detection, SPI timeout errors, "PN5180 not found"

Solutions:

1. Verify wiring - Check all 8 connections against Wiring Guide
2. Check voltage - Measure 3.3V at PN5180 VCC pin (NOT 5V!)
3. Verify RST pin - Should be HIGH (3.3V) during operation
4. Reduce SPI speed - Try 500kHz for testing

Tags Not Detected¶

• Tag compatibility: Bambu Lab tags are ISO 15693. RC522 does NOT work!
• Antenna position: Center under spool core, <5cm from tag
• Interference: Move away from WiFi router, metal surfaces

Scale Issues¶

NAU7802 Erratic Readings¶

Symptoms: Weight jumps around, negative values, drifting

Solutions:

1. Check load cell wiring - If readings inverted, swap A+ and A- wires
2. Stable power - Use quality USB-C cable and 5V/2A power supply
3. Mechanical issues - Platform must only connect via load cell (no touching sides)
4. Allow warm-up - NAU7802 needs ~1 minute to stabilize
5. Shield from drafts - Air currents affect readings

Negative Weight¶

• Swap A+ and A- wires
• Or configure offset in software
• Tare after fixing

Display Issues¶

Blank Screen¶

• Power: Try different USB-C cable (must be data capable)
• Firmware: Flash with correct board settings, PSRAM enabled
• Reset: Press RST button

Touch Not Working¶

• GT911 touch controller is internal
• Check LVGL touch driver initialization
• May need I2C address configuration

Firmware Issues¶

Upload Fails¶

No Serial Output¶

• Build with ARDUINO_USB_CDC_ON_BOOT=1
• Check baud rate: 115200
• Press RST button after upload

Backend Issues¶

Server Won't Start¶

# Check logs
journalctl -u spoolbuddy -n 50

# Port in use?
sudo lsof -i :3000

# Missing dependencies?
pip install -r requirements.txt

# Database permissions?
chmod 664 spoolbuddy.db

WebSocket Disconnects¶

• Check server resources: htop
• Check network stability
• Increase WebSocket ping interval

Printer Connection Issues¶

Can't Connect to Printer¶

Symptoms: "Connection refused", MQTT timeout

Verify:

1. Network: server and printer on same network

   ping <Printer_IP>
   

2. Credentials: Serial number and access code correct

3. Printer settings: LAN mode enabled, not in sleep mode

4. Port: MQTT uses port 8883

   nc -zv 192.168.1.50 8883
   

Diagnostic Commands¶

Check Hardware¶

# Check USB devices
lsusb

# Check serial ports
ls /dev/tty*

Check Services¶

# SpoolBuddy service
sudo systemctl status spoolbuddy

# View logs
journalctl -u spoolbuddy -f

# Restart service
sudo systemctl restart spoolbuddy

Check Network¶

# IP address
ip addr

# Ping printer
ping -c 5 <Printer_IP>

# Check ports
netstat -tlnp | grep 3000

Check API¶

# Health check
curl http://localhost:3000/api/health

# List printers
curl http://localhost:3000/api/printers

# Current weight
curl http://localhost:3000/api/scale/weight

Getting Help¶

If you're still stuck:

1. Check the logs - Usually contains the answer
2. Search GitHub Issues - Someone may have had the same problem
3. Join Discord - discord.gg/3XFdHBkF
4. Open an Issue - Include logs and hardware details