Bambu RFID Reader wiki

Bambu RFID Reader wiki

面向用户的完整功能说明，包含每个页面、每个按钮、每种状态及工作原理。

目录

  1. 应用简介与工作原理
  2. 首次启动：软件使用协议
  3. 主界面与底部标签栏
  4. 识别页（扫卡读取）
  5. 库存页（耗材清单）
  6. 数据页（统计视图）
  7. 复制页（标签管理与写入）
  8. 写入页（自定义 NFC 写入）(遗弃的功能)
  9. 配置页（应用设置）
  10. 通用说明：颜色显示
  11. 常见问题与状态说明

1. 应用简介与工作原理

这个应用是做什么的？

本应用专为拓竹（Bambu Lab）3D打印机的耗材 RFID 标签设计。拓竹耗材卷盘上贴有一张 NFC 芯片标签，芯片内存储了耗材的型号、颜色、温度参数等信息。本应用可以通过手机的 NFC 功能读取这些信息，并以可读的形式展示出来。

NFC 是什么？

NFC（近场通信）是一种极短距离的无线通信技术，有效距离通常在 4 厘米以内。手机上的 NFC 天线通常位于手机背面中部或上部区域（不同机型位置不同）。当手机 NFC 区域贴近标签时，就能读取标签内的数据。

数据存在哪里？

  • 标签数据：耗材型号、颜色编码、打印参数等，存储在耗材卷盘的 NFC 芯片中
  • 本地数据库：库存记录（每卷料的剩余量、备注等），存储在手机本地的数据库文件中
  • 标签文件：复制的标签数据，以 JSON 文件形式存储在手机的 Android/data/com.m0h31h31.bamburfidreader/files/ 目录下
  • 配置偏好：界面设置、开关状态等，存储在手机的应用私有存储中

2. 首次启动：软件使用协议

首次安装并打开应用时，会弹出《软件使用协议》页面。

协议页内容

  • 标题：软件使用协议
  • 摘要：提示用户需阅读并同意协议才能继续使用
  • 协议全文：可上下滑动阅读，内容涉及软件性质、统计说明、风险免责等

按钮

按钮 操作
同意并继续 接受协议，进入应用主界面
不同意并退出 拒绝协议，立即退出应用

说明：协议只在首次安装后出现一次（或版本重大更新后再次展示）。不同意则无法使用应用。

3. 主界面与底部标签栏

进入应用后，屏幕底部有 6 个标签页按钮，点击切换对应页面：

标签 图标含义 功能简介
识别 扫描 贴卡读取耗材信息
库存 列表 查看和管理已记录的耗材
数据 统计 按颜色和型号汇总显示
复制 标签 管理已保存的标签文件，写入到新标签
配置 齿轮 应用设置与工具

切换标签时，每个页面独立保存自己的状态，互不干扰。

4. 识别页（扫卡读取）

这是应用的核心页面，用于读取耗材 RFID 标签上的所有信息。

工作原理

手机 NFC 检测到标签后，会自动触发读取。应用从标签芯片的多个数据块中读取原始字节数据，再通过内置的解析规则，将原始数据转换成可读的耗材信息（型号、颜色、温度等）。

状态说明

状态 显示内容 含义
等待扫卡 “正在等待 NFC 标签” NFC 已就绪，等待贴卡
读取成功 “读取成功” 全部数据正常读取
部分读取 “部分读取” 读取了部分数据块，可能有扇区未能认证
读取失败 “读取失败” 未能读取有效数据
设备无NFC “该设备不支持 NFC” 手机没有 NFC 功能
NFC未开启 “NFC 未开启，请到系统设置中启用” NFC 功能被关闭
UID未读到 “未读取到 UID” 标签存在但 UID 无法读取

读取成功后显示的信息

颜色展示区

页面顶部会显示一个或多个色块，直观展示耗材颜色：

  • 单色：一个色块铺满宽度
  • 多色/渐变：多个色块横向排列
  • 色块上覆盖耗材型号名称和颜色名称
  • 若颜色含透明度（如透明耗材），色块背景会显示棋盘格花纹

卡 UID

原始标签的唯一识别号，6 位十六进制字符串。每张标签的 UID 唯一，不可更改。

耗材信息区

字段 说明
耗材类型 如 PLA、PETG、ABS 等基础类型
颜色名称 拓竹官方颜色名称（如”竹林绿”）
颜色编码 十六进制颜色代码，如 #61C680

库存与余量区

字段 说明
料盘 ID 该卷料的唯一标识，来自标签特定区块
余量进度条 蓝色进度条，直观显示剩余百分比
剩余克重 当前剩余重量（克），来自本地数据库
总重 该耗材卷的原始总重量（来自标签）
原始耗材 用户自填：这卷料实际是什么耗材
备注 用户自填：任意备注信息

原始耗材与备注：这两个小型输入框可以直接在页面上编辑，内容会自动保存到本地数据库，下次扫同一张卡时自动恢复。

技术参数区（其他信息）

显示标签中存储的技术参数，如：

  • 直径（如 1.75mm）
  • 干燥温度 / 干燥时长
  • 热床温度
  • 喷嘴温度范围
  • 生产日期

日志区

底部的文本区域显示读取过程的详细日志，包括每个数据块的原始内容和解析步骤，主要用于调试和故障排查。

按钮与操作

出库按钮

  • 位置：页面色块右上角（仅在读取到料盘 ID 后可用）
  • 作用：将该料盘的库存记录从数据库中删除，模拟”耗材用完出库”操作
  • 点击后：弹出确认对话框

出库确认对话框：

  • 标题：确认出库
  • 内容：确定删除该料盘 ID 记录吗？
  • 按钮：确定（执行删除）/ 取消（放弃）

尝试修复按钮

  • 作用：若当前读取的标签在共享标签库中找到了匹配文件（通过 UID 匹配），则自动进入恢复写入流程
  • 使用场景：标签数据损坏，但之前已备份过这张卡的数据
  • 状态提示：
    • 正在尝试修复：按 UID 匹配共享文件...
    • 已找到匹配文件并进入恢复写入：[文件名]
    • 未找到 UID=[xxx] 对应的数据文件，请在复制页手动选择
    • 修复失败：未读取到 UID

5. 库存页（耗材清单）

库存页记录了所有曾扫描过的耗材卷盘信息，可查看每卷料的余量、型号、颜色和备注。

工作原理

每次在识别页成功扫卡后，应用会自动将该卷料的信息（料盘 ID、型号、颜色、余量等）保存到本地数据库。库存页从数据库读取这些记录并列表显示。同一张卡多次扫描，记录会自动更新而不重复添加。

搜索栏

  • 位置：页面顶部
  • 占位提示：搜索任意字段
  • 搜索范围：料盘 UID、耗材类型、颜色名称、颜色编码、余量百分比等所有字段
  • 搜索逻辑：大小写不敏感，输入多个关键词时需同时匹配（空格分隔）
  • 实时过滤：边输入边过滤，无需按回车

排序按钮

位于搜索栏右侧，点击循环切换三种排序状态：

状态 图标 排序方式
默认 排序图标（灰色） 按录入时间，最新在前
降序 向下箭头（高亮） 按余量从多到少
升序 向上箭头（高亮） 按余量从少到多

库存列表项

每条记录显示为一张卡片，包含：

元素 说明
颜色色块 36×36 点的色块，显示该耗材的实际颜色
耗材类型 粗体显示详细型号（如”Bambu PLA Basic”）
颜色名称 副标题，显示官方颜色名称
颜色编码 格式如 [#61C680]
余量克重 剩余重量数值，如 剩余克重：180g；若未设置则显示”剩余克重：未知”
备注 若有备注，显示一行截断预览
余量进度条 横向进度条，直观显示剩余比例
余量百分比 如 45.2%，精确到小数点后一位

滑动操作

左划（编辑）：

  • 背景变绿，显示”编辑”文字
  • 滑到底松手后打开编辑对话框

右划（删除）：

  • 背景变红，显示”删除”文字
  • 滑到底松手后弹出删除确认对话框

编辑对话框

左划触发，可修改以下内容：

控件 功能
– 按钮 减少克重（每次减少一定量，不低于 0）
+ 按钮 增加克重（不超过该耗材总重量）
克重输入框 直接输入数字（仅允许数字）
滑块 拖动调整克重，范围 0 到总重量
百分比显示 根据当前克重实时计算并显示百分比
原始耗材输入框 编辑原始耗材备注
备注输入框 编辑任意备注文字
  • 确定：保存修改到数据库，关闭对话框
  • 取消：放弃修改，关闭对话框

删除确认对话框

  • 标题：确认删除
  • 内容：确定删除这条库存记录吗？
  • 确定：从数据库删除该条记录
  • 取消：放弃删除

空状态

当库存无数据（或搜索无结果）时，显示”暂无库存数据。”提示文字。

6. 数据页（统计视图）

数据页将库存数据按耗材类型和颜色进行归类汇总，以色块网格的形式直观展示当前所有颜色的分布情况。

工作原理

从本地数据库加载所有库存记录，按耗材类型分组，每种颜色用一个色块表示。开启”合并”模式后，相同颜色的多个卷盘合并为一个色块并显示数量。

顶部控制区

分类 开关

  • 关（默认关）：按简单耗材类型分组（如”PLA”、”PETG”）
  • 开：按详细类型分组（如”Bambu PLA Basic”、”Bambu PLA Matte”）

合并 开关

  • 关：每卷料各显示一个色块，可看到多个相同颜色
  • 开：相同颜色合并为一个色块，右上角显示数量徽标

两个开关的状态在退出应用后仍会保留。

耗材分组面板

每种耗材类型显示为一个独立面板：

  • 标题：耗材类型名称 + 括号内的数量，如 PLA (12)
  • 内容：该类型下所有颜色的色块网格
  • 面板按颜色数量从多到少排列

色块（合并关闭时）

每个色块代表库存中的一卷料：

  • 色块颜色 = 该卷料的颜色
  • 色块上显示颜色名称（前 4 个字符）
  • 色块下方显示余量百分比

色块（合并开启时）

相同颜色合并后：

  • 若只有 1 卷：显示颜色名称和余量百分比
  • 若有多卷：右上角显示数字徽标（卷数），不显示单独百分比
  • 点击合并色块：弹出该颜色下所有卷料的详情对话框

颜色详情对话框（合并模式下点击色块）

弹出列表，每行显示：

  • 小色块（30×30 点）

  • 耗材详细类型

  • 料盘 UID 末 8 位

  • 余量百分比

  • 关闭：点击”关闭”按钮或点击对话框外部

加载与空状态

状态 显示
数据加载中 “加载中…” 文字
库存为空 “暂无数据” 文字

7. 复制页（标签管理与写入）

复制页用于管理已保存的标签文件，并将这些文件中的耗材数据写入到新的空白 FUID 标签，实现标签复制。

工作原理

需要先导入标签数据包，列表会显示标签数据，用户选择目标文件后，将手机贴近空白 FUID 标签即可完成写入，新标签将拥有与原标签相同的耗材信息。

注意：劲量不要将数据写入已有数据的标签，相同标签会被识别为同一卷料。需要做双标签或者不用库存功能时,可无视提醒。

搜索栏

  • 搜索范围：耗材类型、颜色名称、颜色 UID、料盘 UID
  • 实时过滤列表

汇总信息栏

  • 格式：总数：X 当前筛选：Y
  • 实时反映搜索过滤后的结果数量

注意事项面板（可折叠）

位于页面上方，标题为红色加粗文字”写入注意事项”，可点击展开/收起：

  1. 标签必须紧贴手机 NFC 区域，写入过程中不要移动
  2. 写入完成后按提示移开标签，再贴上进行识别验证
  3. 不要写入已有的标签，相同标签会被识别为一卷料
  4. 写入可能失败！作者不对任何后果负责！（红色警告文字）

视图模式

通过配置页可切换两种视图模式：

模式一：列表视图

标签以列表形式显示，每行一条：

元素 说明
左侧竖条 选中时变为主题色，未选中时透明
耗材类型 粗体，选中时变为主题色
UID 信息 格式：UID：[料盘UID] 颜色ID：[颜色UID]
颜色名称 颜色文字说明
颜色色块 42×28 点的颜色预览块

点击行：选中该条记录（选中后背景变浅主题色）

右划删除：

  • 背景变红，显示”删除”
  • 弹出删除确认对话框

模式二：分类视图

按耗材类型分组，每组可折叠：

分组标题行：

  • 拖动图标（可拖动调整分组顺序）
  • 耗材类型名称（粗体）
  • 数量（括号内）
  • 展开/收起箭头（▼展开，▲收起）

点击标题行：展开或收起该分组

拖动分组：长按拖动图标可调整各分组的排列顺序，顺序自动保存

展开后显示颜色网格：

  • 每个色块 60 点，显示颜色、名称、UID
  • 若同一颜色有多个文件，右上角显示数量徽标
  • 点击色块：弹出 UID 选择对话框

UID 选择对话框：

  • 顶部显示：颜色色块 + 耗材类型 + 颜色名称 + 颜色 ID
  • 主体：所有相关料盘 UID 以”芯片”样式排列
  • 点击 UID 芯片：选中对应标签文件，对话框自动关闭
  • 关闭按钮：手动关闭对话框

当前选择显示

当选中某条记录后，页面上显示：当前选择：[料盘UID]

底部操作按钮

开始写入 按钮

  • 可用状态：已选中一条记录，且当前没有进行中的写入任务
  • 不可用状态：未选中记录，或写入进行中（按钮变灰）
  • 点击操作：
    1. 若库存中已存在相同料盘 ID → 弹出重复提示对话框
    2. 若无重复 → 立即进入等待贴卡状态

重复料盘 ID 对话框：

  • 标题：料盘 ID 重复
  • 内容：库存中已存在料盘 ID：[xxx]，是否仍然继续复制写入？
  • 继续复制：忽略重复，开始写入流程
  • 取消：放弃（状态提示：已取消：检测到重复料盘 ID，未开始写入）

取消写入 按钮

  • 可用状态：写入进行中
  • 点击操作：取消当前写入任务

写入流程状态提示

提示文字 含义
写入准备就绪：请将目标空白标签紧贴 NFC 区域... 等待用户贴卡
正在写入，请保持标签稳定贴合，切勿移动... 写入进行中（不要移动！）
写入已完成，请移开标签后再次贴卡进行校验。 写入完成，等待贴卡校验
正在校验，请保持标签稳定贴合，切勿移动... 校验进行中
已取消格式化任务 用户取消了操作
已离开复制页，写入任务已停止。 中途切换了页面

删除确认对话框

  • 标题：确认删除
  • 内容：确定删除标签 [UID] 吗？
  • 确定：删除该标签文件
  • 取消：放弃

8. 写入页（自定义 NFC 写入）** (遗弃的功能) **

写入页与耗材无关，用于向 NFC 标签写入任意自定义内容（文本、网址、电话、WiFi），实现 NFC 标签的通用用途（如自动跳转网页、分享联系方式等）。

注意：拓竹官方标签通常需要先在配置页执行”格式化标签”操作，才能写入自定义 NDEF 数据。

介绍说明

页面顶部有一段说明文字，解释本页面的用途。

写入类型选择

四个单选按钮，选择写入的内容类型：

类型 写入内容 使用场景
文本 纯文字 设备标签、说明信息
网页 网址（URL） 贴卡跳转网站
电话 电话号码 贴卡自动拨号
WiFi WiFi 连接信息 贴卡自动连接 WiFi

各类型的输入区域

文本模式

  • 文本内容输入框
  • 提示：例如 Hello NFC / 设备编号 / 备注信息

网页模式

  • 网页地址输入框
  • 提示：例如 https://example.com

电话模式

  • 电话号码输入框
  • 提示：例如 +8613812345678

WiFi 模式

输入框 说明
WiFi 名称 (SSID) 网络名称
WiFi 密码 网络密码（开放网络可留空）
加密类型 填写 WPA、WEP 或 NONE

提示：WiFi 数据将以 NDEF 文本记录写入（WIFI:… 格式）

开始写入按钮

  • 点击后：进入等待贴卡状态
  • 状态提示：NDEF 写入准备就绪：请将目标标签紧贴 NFC 区域，保持静止直到写入与校验完成。
  • 若当前已有进行中的写入任务，提示：请先完成当前贴卡任务

写入结果

  • 成功：绿色提示文字
  • 失败：红色提示文字，显示具体失败原因
  • 进行中：灰色提示文字，显示当前操作状态

9. 配置页（应用设置）

配置页是功能最丰富的页面，整合了界面设置、工具操作、数据管理等功能，页面内容较长，支持上下滑动。

公告区域（可折叠）

  • 标题栏：显示”公告”，右侧有 ▼/▲ 展开/收起标识
  • 点击标题栏：展开或收起公告内容
  • 内容：来自开发者的公告信息（从远程服务器拉取）
  • 默认状态：展开

广告区域（可折叠）

  • 标题栏：显示”广告”，右侧有 ▼/▲ 展开/收起标识
  • 点击标题栏：展开或收起广告内容
  • 默认状态：展开

界面风格

两个按钮选择界面渲染风格：

选项 说明
新拟态 柔和阴影、立体感的现代设计风格
MIUIX 小米 MIUIX 风格，扁平简洁

切换后立即生效，无需重启。

深色模式

三个按钮选择主题明暗：

选项 说明
浅色 强制使用亮色主题
深色 强制使用深色主题
跟随系统 根据手机系统深色模式自动切换

切换后立即生效。

主题配色

  • 当前配色预览：显示一个小色块 + 当前配色方案名称
  • 点击该行：弹出配色选择对话框

配色选择对话框：

  • 标题：选择配色方案
  • 内容：5列×5行的色块网格，共 25 种配色
  • 点击色块：选中该配色，对话框自动关闭
  • 当前选中的配色在色块上显示 ✓ 图标，且色块有边框高亮
  • 取消：关闭对话框不做修改

25 种可选配色方案：

名称 色调
橘橙 温暖橙色
天蓝色 明亮天蓝
海蓝 深邃海蓝（默认）
冰蓝 清凉冰蓝
暗夜蓝 深海夜蓝
枪灰色 中性灰
岩石灰 浅石灰
果绿色 嫩绿
草绿 青草绿
暗夜绿 深军绿
炭黑 纯黑
深棕色 深咖啡棕
拿铁褐 奶咖浅棕
暗夜棕 中深棕
沙棕色 沙漠棕
樱花粉 粉嫩樱花
丁香紫 淡雅紫
猩红 鲜艳红
砖红色 沉稳砖红
莓果紫 深紫红
暗夜红 低调暗红
象牙白 纯净白
骨白 温润象牙白
柠檬黄 明亮黄
沙漠黄 暖米黄

功能开关区

库存与数据功能

  • 开关：显示/隐藏底部标签栏中的”库存”和”数据”两个页面
  • 说明：关闭后只显示识别、复制、写入、配置四个标签

隐藏已复制标签

  • 开关：在复制页中隐藏已成功复制的标签
  • 说明：开启后，已复制的标签不再显示在复制页列表中，避免误操作

双标签模式

  • 开关：开启后需要复制 2 次才算完成，才会隐藏该标签
  • 说明：用于需要同时复制两张标签的场景（例如料盘两面各一张）

复制页视图

  • 列表：复制页以列表形式展示标签
  • 分类：复制页以按耗材类型分类的网格形式展示

数据管理

读取全部扇区数据并保存文件

  • 作用：扫卡时读取标签所有扇区的原始数据，并保存到文件
  • 说明：开启后读取速度会变慢；文件保存在 Android/data/com.m0h31h31.bamburfidreader/rfid_file/self_xxxxx/ 目录
  • 确认对话框：
    • 标题：读取全部数据提醒
    • 内容：说明速度影响和文件位置
    • 按钮：确定开启 / 取消

保存秘钥到文件

  • 作用：将读取到的 标签数据 扇区密钥保存到文件中，供后续使用

备份数据库

  • 作用：将本地库存数据库备份为文件，存储到Android/data/com.m0h31h31.bamburfidreader/rfid_file/filaments_backup.db
  • 结果：成功/失败提示

导入数据库

  • 作用：从Android/data/com.m0h31h31.bamburfidreader/rfid_file/filaments_backup.db导入之前备份的数据库文件，覆盖当前库存数据
  • 确认对话框：
    • 标题：确认导入数据库
    • 内容：导入数据库会覆盖当前本地耗材数据库内容。确定继续吗？
    • 按钮：确定导入 / 取消

标签管理

打包标签数据

  • 作用：将所有已保存的标签文件打包成 ZIP 文件，方便备份或分享，打包文件在系统Downloads目录下
  • 按钮文字：显示当前标签数量，如 打包标签数据（42）
  • 状态：正在打包标签数据，请稍候...

导入标签包

  • 作用：从外部选择一个 ZIP 格式的标签包并导入
  • 结果：导入成功/失败提示；选择文件后取消则提示：已取消选择标签包

强制覆盖导入标签

  • 开关：导入时强制覆盖已有的同名标签文件
  • 说明：关闭时跳过重名文件，开启时全部覆盖

清空自有标签

  • 作用：删除 self 目录下的全部标签文件（自己扫描保存的）
  • 确认对话框：
    • 标题：确认清空自有标签
    • 内容：将删除当前 self 目录下的全部标签文件，此操作不可恢复。确定继续吗？
    • 按钮：确定 / 取消

清空标签库

  • 作用：删除 share 目录下的全部标签文件（导入的共享标签库）,以及标签数据库
  • 确认对话框：
    • 标题：确认清空标签库
    • 内容：将删除 share 目录下的全部标签文件，此操作不可恢复。确定继续吗？
    • 按钮：确定 / 取消

格式化标签

  • 格式化标签 按钮：

    • 作用：将拓竹官方标签的存储空间重新格式化，清除原有数据，使其可以写入自定义 NDEF 内容
    • 点击后：进入等待贴卡状态
    • 状态提示：格式化标签准备就绪：请将目标标签紧贴 NFC 区域，保持静止直到完成。

  • 取消格式化 按钮：

    • 作用：取消进行中的格式化任务
    • 状态提示：已取消格式化任务

  • 显示格式化标签调试信息 开关：

    • 开启后格式化过程中会显示详细的调试输出，方便排查失败原因

若当前有进行中的写入/校验任务，所有操作均提示：请先完成或取消当前写入/校验任务

版本信息

页面底部显示：软件版本：x.x.x

10. 通用说明：颜色显示

颜色如何展示

应用中大量使用颜色色块来直观展示耗材颜色：

  • 实色：直接显示对应颜色的纯色块
  • 透明/半透明：色块背景显示棋盘格图案（灰白相间），透明部分可见棋盘
  • 多色：多个色块横向或网格排列

文字颜色自动对比

色块上的文字颜色（黑色或白色）由程序根据背景颜色的亮度自动计算：

  • 背景颜色较亮（如象牙白、柠檬黄）→ 文字显示为深色
  • 背景颜色较暗（如暗夜蓝、炭黑）→ 文字显示为白色

11. 常见问题与状态说明

NFC 相关

问题 可能原因 解决方法
应用提示”设备不支持 NFC” 手机无 NFC 硬件 更换支持 NFC 的设备
应用提示”NFC 未开启” 系统 NFC 功能关闭 进入手机设置 → 连接 → NFC，开启即可
贴卡后无反应 NFC 位置不对 尝试调整卡片位置，通常天线在手机背面中部
显示”部分读取” 某些扇区认证失败 正常现象，关键数据通常已读取到
显示”读取失败” 标签损坏或不兼容 尝试多次贴卡；如是兼容问题则无法读取

写入相关

问题 可能原因 解决方法
写入失败 标签移动 / 距离过远 保持标签紧贴 NFC 区域，勿移动
提示”请先完成当前贴卡任务” 已有写入任务未完成 先完成当前任务或点击取消
拓竹标签无法写入自定义内容 标签格式为出厂格式 先在配置页使用”格式化标签”功能

库存相关

问题 可能原因 解决方法
扫卡后余量/备注消失 —（已修复） 更新到最新版本
库存页无数据 从未扫描过标签 在识别页扫描耗材卷盘
同一卷料有多条记录 不同料盘 ID 正常，每个料盘 ID 唯一，是不同物理卷盘

数据同步

  • 识别页扫卡后，库存页和数据页会自动更新
  • 切换标签页时数据自动刷新
  • 设置的开关状态、视图模式均自动保存，下次打开应用时恢复

文档版本：与应用当前版本同步