Firmware Installation¶

SpoolBuddy requires firmware on two devices: the Raspberry Pi Pico (NFC bridge) and the CrowPanel Display (ESP32-S3).

Device Overview¶

Part 1: Pico NFC Bridge¶

The Pico runs the NFC bridge firmware that communicates with the PN5180 reader.

Option A: Pre-built UF2 (Recommended)¶

1. Download the pre-built firmware:

   pico-nfc-bridge.uf2

2. Enter BOOTSEL mode:

3. Hold the BOOTSEL button on the Pico
4. While holding, plug in the USB cable
5. Release the button

6. The Pico appears as a USB drive named "RPI-RP2"

7. Flash the firmware:

8. Drag and drop the .uf2 file onto the RPI-RP2 drive

9. The Pico automatically reboots and starts running

10. Verify:

11. The onboard LED should blink every 500ms
12. Connect a serial monitor at 115200 baud to see:

    Pico NFC Bridge v2.0 starting...
    Features: MIFARE Classic + NTAG + Bambu HKDF
    SPI OK
    Reset OK
    PN5180 version: 3.5
    RF ON (ISO14443A)
    I2C ready at 0x55
    Ready!
    

Option B: Build from Source¶

Requires PlatformIO installed.

# Clone the repository
git clone https://github.com/maziggy/spoolbuddy.git
cd spoolbuddy/pico-nfc-bridge

# Build
pio run

# Upload (Pico in BOOTSEL mode)
pio run -t upload

# Monitor serial output
pio device monitor

Part 2: CrowPanel Display¶

The CrowPanel runs the main SpoolBuddy firmware (Rust/ESP-IDF).

Option A: Pre-built Binary (Recommended)¶

1. Download the pre-built firmware:

   spoolbuddy-firmware.bin

2. Install espflash:

   cargo install espflash
   

Or download from espflash releases

1. Connect the display:
2. Use a USB-C data cable (not charge-only)
3. Connect to your computer

4. The display may show a blank screen or old firmware

5. Find the port:

   WindowsLinuxmacOS

   Device Manager → Ports → Look for "USB Serial" (e.g., COM3)

   ls /dev/ttyACM* /dev/ttyUSB*
   # Usually /dev/ttyACM0
   

   ls /dev/cu.usb*
   # Usually /dev/cu.usbmodem*
   

6. Flash the firmware:

   espflash flash --monitor spoolbuddy-firmware.bin
   

Option B: Build from Source¶

Requires Rust and the ESP toolchain.

Prerequisites¶

1. Install Rust:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env
   

2. Install ESP toolchain via espup:

   # Install espup
   cargo install espup --locked
   
   # Install the ESP toolchain (takes several minutes)
   espup install
   
   # Source the environment (add to your shell profile)
   . $HOME/export-esp.sh
   

3. Install espflash:

   cargo install espflash
   

4. (Linux only) Add USB permissions:

   sudo usermod -a -G dialout $USER
   # Log out and back in
   

Build and Flash¶

# Clone the repository
git clone https://github.com/maziggy/spoolbuddy.git
cd spoolbuddy/firmware

# Source ESP environment
. $HOME/export-esp.sh

# Build and flash (with serial monitor)
cargo run --release

Or build separately:

# Build only
cargo build --release

# Flash manually
espflash flash --monitor target/xtensa-esp32s3-espidf/release/spoolbuddy-firmware

Verification¶

After flashing both devices, verify the system is working:

Pico NFC Bridge¶

• LED blinks every 500ms
• Serial output shows "Ready!"
• PN5180 version displayed (e.g., 3.5)

CrowPanel Display¶

• Display backlight turns on
• UI renders on screen
• Touch responds to input
• Serial output shows initialization

Integration Test¶

1. Power on the complete system
2. Place a Bambu Lab spool on the scale
3. The NFC tag should be detected
4. Weight should display on screen

Troubleshooting¶

Pico Issues¶

Display Issues¶

Next: Software Setup