如何自制NFC耗材扫描仪：Bambuddy配套SpoolBuddy硬件开发实战指南（树莓派+PN5180）

【免费下载链接】bambuddyYour Bambu Lab. No Cloud. Your Rules. Self-hosted command center for Bambu Lab — from one A1 to an entire print farm.项目地址: https://gitcode.com/gh_mirrors/ba/bambuddy

Bambuddy 是一款自托管的 Bambu Lab 3D 打印指挥中心，从一台 A1 到整个打印农场都能统一管理。而它开源的SpoolBuddy模块，让你用一块树莓派加一片 PN5180 NFC 读卡器，就能自制一台NFC 耗材扫描仪：把耗材卷往扫描区一放，材料、颜色、剩余重量自动识别入库，告别手动填表。本文带你从零接线、配置系统，到读懂源码里的通信原理，完整走完硬件开发流程。

为什么需要一台NFC耗材扫描仪 🏷️

手工管理耗材是打印农场最大的痛点之一：

• 卷号记不住：Bambu Lab 原装耗材卷自带 MIFARE 标签，里面藏着材料类型、颜色和卷托盘 UUID，但打印机屏幕之外的工具读不到它
• 剩余量靠猜：没有称重，只能凭感觉判断还能打多久
• 多卷混插易错：换卷、换盘时人工登记极易出错

SpoolBuddy 的思路很直接：树莓派读标签 + 称重模块实时读数 → 事件推给 Bambuddy 后端 → 前端自动更新库存。支持三类标签：

硬件清单如下（可选模块不装也能跑）：

SpoolBuddy 软件架构：三个异步循环

SpoolBuddy 的核心是一个 Python 守护进程，入口在 spoolbuddy/daemon/main.py，它用 asyncio 同时跑三个循环：

1. NFC 轮询循环：持续扫描标签，检测到"标签放上/取下"事件就推送给后端；后端下发的写标签指令也会在这里执行
2. 称重轮询循环：每 100ms 读一次 NAU7802，重量变化超过 2g 才上报，避免无效数据刷屏
3. 心跳循环：定期上报设备状态，并接收后端指令（去皮、校准、远程重启、运行诊断脚本等）

模块划分非常清晰，方便你按需阅读：

• spoolbuddy/daemon/pn5180.py — PN5180 底层 SPI 驱动，注册、RF 配置、MIFARE 认证全在这里
• spoolbuddy/daemon/nfc_reader.py — 标签存在性状态机，带"连续丢失 3 次判定取下"的去抖逻辑
• spoolbuddy/daemon/scale_reader.py — 称重封装与稳定性检测
• spoolbuddy/daemon/tag_parser.py — 把 Bambu 标签原始块解析成结构化元数据
• spoolbuddy/daemon/api_client.py — HTTP 客户端，断网时事件进缓冲队列，恢复后自动补发

对应地，Bambuddy 后端在 backend/app/api/routes/spoolbuddy.py 提供了设备注册、心跳、标签扫描、称重上报等整套 API（前缀/api/v1/spoolbuddy），扫描到的标签会经由 backend/app/services/spool_tag_matcher.py 自动匹配到已有耗材卷。

PN5180 接线：一张表搞定 9 根线 🔌

这是最容易出错的环节。PN5180 走 SPI 接口，接线对照表如下（引自 spoolbuddy/README.md）：

三个高频踩坑点：

• ⚡3V3 和 5V 都要接：5V 给天线放大电路供电，能显著扩展读取距离；但千万别把 5V 接到 3V3 脚，会直接烧坏读卡器
• 🎛️NSS 用 GPIO23 手动控制片选：内核 SPI 驱动的自动 CS 时序不满足 PN5180 的 5µs 建立/100µs 保持要求，所以代码里用 GPIO 手动切换片选
• 🔌全部焊接，别用杜邦线：SPI 对信号完整性很敏感，接触不良会导致射频场闪烁、幽灵报错等玄学问题

NAU7802 称重模块更简单，4 根线：VCC→Pin 1、SDA→Pin 3 (GPIO2)、SCL→Pin 5 (GPIO3)、GND→Pin 30。

系统配置三步走：开启 SPI 和 I2C

树莓派新装系统后，SPI 和 I2C 默认是关闭的。

第一步：raspi-config 开启接口

sudo raspi-config # Interface Options -> SPI -> Enable # Interface Options -> I2C -> Enable sudo reboot

第二步：修改/boot/firmware/config.txt，在[all]段追加两行：

dtparam=i2c_arm=on dtoverlay=spi0-0cs

前者启用 I2C 总线 1 给称重模块用；后者禁用 SPI 自动片选，配合 GPIO23 手动 CS。

第三步：安装依赖包

sudo apt install python3-spidev python3-libgpiod gpiod libgpiod3 i2c-tools pip install spidev gpiod smbus2

重启后用ls /dev/spidev0.*和i2cdetect -y 1验证，看到0x2A（NAU7802）说明硬件已就绪。

首次点亮：诊断脚本 + 标签读取测试 🔍

仓库自带了三个诊断脚本，装在spoolbuddy/scripts/目录下：

sudo python3 spoolbuddy/scripts/pn5180_diag.py # 验证 PN5180 通信，应显示固件版本 sudo python3 spoolbuddy/scripts/read_tag.py # 放标签上读卡，验证 UID 读取 sudo python3 spoolbuddy/scripts/scale_diag.py # 读 10 次称重采样，验证 NAU7802

遇到怪现象时，官方排障表（同样在 spoolbuddy/README.md 中）非常好用：

两个关键参数别动：SPI 速率 500kHz（再高就通信出错）、SPI 模式 0（CPOL=0, CPHA=0）。

硬核看点：Bambu 标签是怎么被"解锁"的 🔓

这是整个项目最有意思的部分。Bambu Lab 原装耗材标签是加密的 MIFARE Classic 卡，密钥不是固定的，而是根据每张卡的 UID 动态推导出来的：

spoolbuddy/daemon/pn5180.py 中的hkdf_derive_keys()使用 HKDF-SHA256 算法，以 Bambu 主密钥为盐、标签 UID 为输入密钥材料，派生出 16 个扇区各 6 字节的密钥，再逐扇区认证、读取 Block 1/2/4/5 —— 材料类型、颜色、温度参数和 32 位托盘 UUID 就都拿到了。

认证本身由 PN5180 硬件代劳：mfc_authenticate()发送MFC_AUTHENTICATE主机命令后，Crypto1 加解密在硬件内完成，Python 侧只需要读数据块。NTAG 社区标签则无需认证，直接读 NDEF 数据区即可。

SpoolBuddy 还支持做一台带屏"小终端"：Kiosk 屏幕上，放上标签或卷重量变化会唤醒显示，空闲自动熄屏，背光亮度都能从 Bambuddy 前端远程调整，实现逻辑在 spoolbuddy/daemon/display_control.py。

与 Bambuddy 后端联动：扫描即入库 📡

安装完成后，SpoolBuddy 守护进程启动时会向后端注册设备（上报 IP、固件版本、NFC/称重能力），之后三个循环持续上报事件。前端的联动效果：

• 扫到标签 → 自动匹配或创建耗材卷，AMS 槽位同步更新
• 称重数据实时显示在耗材页，预测"还能打多久"
• 支持从前端远程触发：写 NTAG 标签、设备去皮校准、运行诊断脚本甚至重启

统计页面上能看到完整的耗材消耗曲线，数据都在你自己服务器上，不经过任何第三方云。

快速开始：一键安装脚本

不想手动折腾的话，官方安装脚本 spoolbuddy/install/install.sh 支持两种模式：

• --mode spoolbuddy：树莓派只做扫描仪伴侣，连接远程 Bambuddy 实例（需提供服务端地址和 API Key）
• --mode full：同一台树莓派上同时装 Bambuddy + SpoolBuddy

脚本会自动装系统包、建 venv、部署 systemd 服务并配置开机自启。也可以先克隆仓库自行研究源码：

git clone https://gitcode.com/gh_mirrors/ba/bambuddy

核心代码都在spoolbuddy/目录，测试用例在 spoolbuddy/tests/ 下，比如test_tag_parser.py就覆盖了标签解析的各种边界情况，是理解数据格式的绝佳材料。

写在最后

从 9 根杜邦线到自动入库的完整链路，SpoolBuddy 展示了"低成本硬件 + 自托管软件"的典型玩法：

1. ✅ 硬件成本极低：PN5180 模块 + 可选称重模块，百元级搞定
2. ✅ 协议逆向有惊喜：HKDF 密钥派生让 Bambu 加密标签变得可读
3. ✅ 软件全链路开源：驱动、状态机、诊断工具、后端 API 一应俱全
4. ✅ 打印农场越大规模，收益越明显

动手试试吧——扫一卷耗材，看它自己"报出姓名"的那一刻，是这套系统最有魔性的瞬间。✨

【免费下载链接】bambuddyYour Bambu Lab. No Cloud. Your Rules. Self-hosted command center for Bambu Lab — from one A1 to an entire print farm.项目地址: https://gitcode.com/gh_mirrors/ba/bambuddy