khmm12/flipper-xiaomi-filter-reset
GitHub: khmm12/flipper-xiaomi-filter-reset
Flipper Zero 应用，通过 NFC 重置小米空气净化器滤芯的 NTAG213 寿命计数器，免更换或使用手机即可恢复 100%。
Stars: 5 | Forks: 0
# Xiaomi 滤芯重置
一款 [Flipper Zero](https://flipperzero.one/) 应用，用于重置 Xiaomi 空气净化器滤芯上的 **滤芯寿命计数器**，让设备重新显示 **100%** —— 无需更换滤芯，也无需使用智能手机应用。
[](https://github.com/khmm12/flipper-xiaomi-filter-reset/actions/workflows/ci.yml)
[](./LICENSE)
[](https://flipperzero.one/)
## 目录
- [免责声明](#disclaimer)
- [兼容性](#compatibility)
- [工作原理](#how-it-works)
- [截图](#screenshots)
- [安装](#install)
- [使用方法](#usage)
- [从源码构建](#build-from-source)
- [开发](#development)
- [项目结构](#project-layout)
- [贡献](#contributing)
- [致谢](#credits)
- [许可证](#license)
## 免责声明
本工具仅供**研究、互操作性操作以及维修您所拥有的硬件**使用。重置计数器**不会**清洁或恢复物理滤芯本身；饱和的 HEPA/活性炭滤芯仍需清洁或更换以确保空气洁净。您可以使用本工具来避免丢弃仍有剩余寿命的滤芯，或继续使用第三方滤芯。您需对个人的使用方式负责。
不提供任何担保。请参阅 [License](#license)。
## 兼容性
本应用适用于使用 **NTAG213**（ISO 14443-3A / NfcA）标签并采用厂商基于 UID 派生密码方案的 Xiaomi 空气净化器滤芯。这涵盖了许多型号的 Mi Air Purifier 随附的滤芯（社区反馈包括 3H/3C、4/4 Lite/4 Pro 以及 Pro/Pro H 系列）。已在真实硬件上验证了多个不同的滤芯系列，它们可以通过标签上的产品代码（`AP11`、`JDA0` 和 `JD26`）来识别。
完整的重置过程已在 **Mi Air Purifier 4** 和 **Mi Air Purifier 4 Pro** 上进行了端到端确认——包括写入、验证以及设备重新显示 100%。由于应用使用从每个标签自身的 UID 派生的密码进行身份验证，重置成功本身就证明了该标签是受支持的 Xiaomi 滤芯。外来标签将直接无法通过身份验证，且永远不会被写入。
## 工作原理
1. 滤芯的 NTAG213 在第 8 页（page 8）存储了一个使用计数器，并且从第 4 页开始受密码保护（读写均受保护）。
2. 4 字节的 NTAG 密码是标签 7 字节 UID 的确定性函数：从 `SHA-1(UID)` 中固定选取的字节。
3. 应用读取 UID（始终可读），派生出密码，通过 `PWD_AUTH` 进行身份验证，将 `00 00 00 00` 写入计数器页，并回读以进行验证。
完整的逆向工程分析、内存映射以及精确的密码算法详见 [`docs/protocol.md`](./docs/protocol.md)。
## 截图
| 菜单 | 等待标签 | 完成 |
| :---: | :---: | :---: |
|  |  |  |
## 安装
### 选项 A — Flipper App Catalog（发布后推荐）
在 [qFlipper](https://flipperzero.one/update) 或移动应用内的 Apps 目录中搜索 **"Xiaomi Filter Reset"** 并安装。
### 选项 B — 预构建的 `.fap`
1. 从[最新发布版](https://github.com/khmm12/flipper-xiaomi-filter-reset/releases)或 [CI artifacts](https://github.com/khmm12/flipper-xiaomi-filter-reset/actions) 下载 `xiaomi_filter_reset.fap`。
2. 将其复制到您的 Flipper SD 卡的 `apps/NFC/` 目录下。
3. 从 **Apps → NFC → Xiaomi Filter Reset** 启动它。
请确保 `.fap` 与您的固件频道（正式版或开发版）相匹配。CI 会同时构建这两个版本。
## 使用方法
1. 打开 **Apps → NFC → Xiaomi Filter Reset** 并选择 **"Reset filter life"**。
2. 将滤芯的 NFC 标签平贴在您 Flipper 的**背面**。该标签通常是滤芯纸板边缘上的一张贴纸或一个小圆盘。
3. 等待提示 **"Done! Filter life restored to 100%"**。
4. 重新装入滤芯。净化器现在将报告为新滤芯。
如果失败，应用会告诉您原因（不是 Xiaomi 滤芯、标签移动了、写入被拒绝等），并提供**重试**选项。
### 检查滤芯寿命（只读）
**"Check filter life"** 会执行相同的经过身份验证的读取操作，但绝不进行写入。它可以确认该标签是否为真正的 Xiaomi 滤芯，并报告其是**全新**的（计数器为 0）还是**已使用过** —— 这非常适合在重置前验证滤芯，或确认重置是否成功。
它有意**不**显示百分比。标签仅以未知单位存储*消耗时长*；映射到 0% 的满量程值存储在设备内部，并因滤芯型号而异，因此标签上并没有这个数据。任何百分比都只能是猜测，而本应用仅报告硬件实际反馈的内容。
## 从源码构建
构建过程使用 [`ufbt`](https://pypi.org/project/ufbt/)，即微型 Flipper Build Tool。
```
# 1. 安装 ufbt（只需一次）。使用 mise？`mise install` 会从 mise.toml 中进行配置。
python3 -m pip install --user ufbt
# 2. 构建应用（首次运行时会下载匹配的 SDK）
ufbt
# 3. （可选）直接安装到已连接的 Flipper 上
ufbt launch
```
生成的 `xiaomi_filter_reset.fap` 将位于 `dist/` 目录中。
## 开发
| 任务 | 命令 |
| --- | --- |
| 构建 FAP | `ufbt` |
| 在已连接的 Flipper 上运行 | `ufbt launch` |
| 运行主机单元测试 | `make -C test test` |
| 对纯核心代码进行 Lint（严格警告） | `make -C test lint` |
| 检查代码格式 | `ufbt lint` |
| 自动格式化所有源代码 | `ufbt format` |
加密和内存映射逻辑位于 `src/core/` 中，且**不依赖固件**，因此可以在主机上进行完整的单元测试。编译进应用的完全是同一套目标代码，因此测试所覆盖的内容与实际发布的内容完全一致。密码派生过程已根据从真实滤芯标签读取的金标向量进行了验证。
## 项目结构
```
.
├── application.fam # Flipper app manifest
├── mise.toml # optional toolchain (provisions ufbt)
├── xiaomi_filter_reset.c # entry point + app lifecycle
├── xiaomi_filter_reset_i.h # shared app state
├── icons/ # 10x10 app icon
├── scenes/ # UI scenes (start, reset, success, error, about)
├── src/
│ ├── core/ # pure, host-testable core (SHA-1, filter logic)
│ └── nfc/ # NTAG213 poller worker
├── test/ # host unit tests + Makefile
├── docs/protocol.md # reverse-engineering notes
├── catalog/ # Flipper App Catalog submission manifest
└── .github/workflows/ci.yml # build + test + lint
```
与固件耦合的胶水代码 —— 入口点和 UI `scenes/` —— 位于应用根目录下的 `application.fam` 旁边，与 Flipper 自带应用的布局保持一致。可移植且可在主机上测试的逻辑特意隔离在 `src/` 下（`core/` 无固件依赖并经过单元测试；`nfc/` 是轻量级的设备驱动层）。
## 致谢
本应用建立在他人完成的逆向工程基础之上：
- [**flamingo-tech**](https://github.com/Flamingo-tech/xiaomi-air-purifier-reverse-engineering)
— 发现了 UID→密码算法及标签内存映射。
- [**unethical.info**](https://unethical.info/2024/01/24/hacking-my-air-purifier/)
— 关于整个 DRM 方案的出色分析文章。
## 许可证
[GPL-3.0-or-later](./LICENSE)。内置的 SHA-1 实现（`src/core/sha1.*`）属于公共领域（基于 Steve Reid 的实现）。
标签：Flipper Zero, NFC, 客户端加密, 工具, 智能家居, 物联网, 硬件维护