i12bp8/wmbuster

## 功能 - **支持所有四种欧盟模式** — T1、C1、T+C 组合、S1。 T+C 是默认模式，可通过后同步字节检测（`0xCD` / `0x3D` / 直通） 在单一芯片配置上解码 T-mode (3-of-6) 和 C-mode (NRZ 格式 A & B)。 - **EN 13757-3 应用层** — DIF/VIF 遍历器，覆盖能量、 体积、质量、功率、体积流量、质量流量、供水/回水/外部 温度、温差、压力、运行时间、工作时间、 日期、日期时间、HCA 单位、制造编号、总线地址。 - **AES-128 模式 5 解密** — 将 `keys.csv` 放到 SD 卡上， 加密仪表将自动解密为可读行。 - **制造商驱动** — Techem (HCA / 热量 / 水 / 烟雾)、Kamstrup、 Diehl / Hydrometer / Sappel / IZAR、Qundis / ista / Brunata、BMeters、 Engelmann、Sontex、Zenner、Apator、GWF、BFW 等。 - **自定义 Canvas UI** — 带有 RSSI 条、数据包计数的仪表列表， 以及包含解析值、原始十六进制和帧统计信息的每块仪表详情页。 - **SD 日志记录** — 原始 + 已解析的报文保存至 `/ext/apps_data/wmbuster/`， 以便使用 `rtl_433` 或 `wmbusmeters` 进行离线分析。 ## 不能做什么 - **绝不发射。** 设计上排除了 T2 / C2 双向通信和仪表唤醒请求。 - **无 N-mode**（169 MHz 窄带）— Flipper 的 CC1101 在硬件上 被锁定在 300 / 430 / 868 MHz 的 SRD 频段。 - **不支持美国协议** — Itron ERT、Sensus FlexNet、Neptune R900 属于独立的无线电协议栈，目前不受支持。相关理由请参阅 [项目主页](https://i12bp8.github.io/wmbuster/)。 - **无密钥破解，无重放，无欺骗。** 这是一个查看器。 ## 安装 ### 从源代码构建 ``` # 安装 ufbt (Flipper 的 build tool) pip install --upgrade ufbt ufbt update --channel=release # Clone 与 build git clone https://github.com/i12bp8/wmbuster.git cd wmbuster ufbt # produces dist/wmbuster.fap ufbt launch # flash + start on a connected Flipper ``` 主机端回归测试（无需 Flipper）： ``` make -C tests check ``` ## 解密（AES-128 模式 5） 较新的欧盟仪表（Techem v0x6A、Kamstrup MULTICAL 等）出厂时启用了 AES-128。将一个 CSV 文件放到 SD 卡的以下路径： ``` /ext/apps_data/wmbuster/keys.csv ``` 每行对应一个仪表，允许使用 `#` 注释： ``` # 制造商 (3 字符), 8 位十六进制 ID, 32 位十六进制 AES-128 key TCH,27404216,0123456789ABCDEF0123456789ABCDEF KAM,12345678,FEDCBA9876543210FEDCBA9876543210 ``` 重启应用程序以重新加载文件。从主菜单打开 **Keys** 以 确认已加载的条目（仅显示每个密钥的指纹）。当 文件中存在匹配的密钥时，仪表行将从 `ENC` 翻转为 `DEC`，并显示 解码后的读数。 ## 模式选择 | 模式 | 频率 | 比特率 | 编码 | 备注 | |-------|------------|-------------------|-----------------------|-----------------------------| | T1 | 868.95 MHz | 100 kchip/s | 3-of-6 | 旧版 Techem 固件 | | C1 | 868.95 MHz | 100 kbit/s | NRZ, 格式 A/B 自动 | 新版 Techem, 大多数 Kamstrup | | T+C | 868.95 MHz | 100 kbit/s | T1 或 C1, 自动检测 | **默认** — 覆盖最广 | | S1 | 868.30 MHz | 32.768 kbit/s | Manchester | 旧版水表 / 燃气表 | ## 外部 CC1101 如果您有一个按照标准 Flipper 引脚分配连接到 GPIO 的 CC1101 模块，请切换至 **Settings → Module → External**。如果未检测到模块， 应用程序将回退到内部无线电。 ## 文档 - **[项目主页](https://i12bp8.github.io/wmbuster/)** — 着陆页、 屏幕截图、安装步骤。 - **[CHANGELOG](CHANGELOG.md)** — 版本说明，逐版本记录。 - **[DISCLAIMER](DISCLAIMER.md)** — 完整法律条款、禁止用途、 频谱 / AES 政策。 - **[drivers/CONTRIBUTING.md](drivers/CONTRIBUTING.md)** — 如何在一个 C 文件中添加新的制造商驱动。 - **[drivers/README.md](drivers/README.md)** — 驱动布局参考。 ## 项目布局 ``` wmbuster/ ├── application.fam # ufbt manifest ├── wmbus_app.[ch] # entry point, scene wiring, settings ├── meters_db.[ch] # bounded in-RAM meter table ├── key_store.[ch] # AES-key CSV loader ├── logger.[ch] # SD logging (raw + parsed) ├── protocol/ │ ├── wmbus_3of6.[ch] # EN 13757-4 §6.2.1.1 chip decoder (T1) │ ├── wmbus_manchester.[ch]# Manchester decoder (S1) │ ├── wmbus_crc.[ch] # CRC-16/EN-13757 + Format A/B verifiers │ ├── wmbus_link.[ch] # L/C/M/A/CI parsing, encryption-mode tag │ ├── wmbus_app_layer.[ch] # DIF/VIF walker + renderer │ ├── wmbus_aes.[ch] # AES-CBC over furi_hal_crypto │ ├── wmbus_manuf.[ch] # 16-bit manuf code <-> 3-letter ASCII │ └── wmbus_medium.[ch] # device-type code -> human string ├── subghz/ │ ├── wmbus_worker.[ch] # CC1101 worker, slicer, CRC, dispatch │ ├── wmbus_hal_rx.c # FIFO drain via SPI (int + ext handles) │ └── wmbus_radio.[ch] # int/ext device selector (ProtoPirate-style) ├── drivers/ │ ├── engine/ # registry + uniform driver interface │ ├── _oms_split.h # shared "OMS prefix -> mfct trailer" helper │ ├── CONTRIBUTING.md # how to add a new driver │ └── europe/ │ ├── techem/ # FHKV-3/4 HCA, heat, water, smoke, MK-Radio │ ├── kamstrup/ # MULTICAL family │ ├── diehl/ # Hydrometer / Sappel / IZAR │ ├── qundis/ # Qundis / ista / Brunata HCAs │ ├── bmeters/ # Hydrodigit │ ├── engelmann/ # Hydroclima HCA │ ├── sontex/ # RFM-TX1 water (legacy + OMS firmwares) │ ├── zenner/ # Zenner B.One │ ├── apator/ # NA-1 │ ├── misc/ # GWF water, BFW 240-Radio │ └── ... # see drivers/README.md ├── views/ # canvas widgets + scenes └── tests/ # host-side regression tests (no Flipper) ``` ## 添加驱动 我们尽可能地简化了添加制造商驱动的工作。通常 情况下只需**一个 C 文件，约 50 行**：将其放入 `drivers/europe//.c`，添加到 `application.fam` 和 注册表中。 关于从 `wmbusmeters` 移植的实际示例，请参见 [**drivers/CONTRIBUTING.md**](drivers/CONTRIBUTING.md)。在 `tests/test_ports.c` 中 包含回归测试的 Pull Request 会被最快合并。 ## 测试 主机测试套件使用公开的 `wmbusmeters` 参考报文对每个制造商驱动进行了验证： ``` make -C tests check ``` 要针对 SDR 进行真实环境验证，请使用 `rtl_433` 捕获同一空间的无线电信号： ``` rtl_433 -f 868.95M -s 1.6M -Y minmax -R 104 -R 105 -F json > capture.jsonl ``` （`-R 104` 是 rtl_433 的 wM-Bus T+C 解码器，`-R 105` 是 S-mode 解码器。） ## 标准与参考 - **EN 13757-4** — wM-Bus PHY / 链路层。 - **EN 13757-3** — 应用层（DIF/VIF）。 - **OMS 规范第 2 卷** — 配置文件 + 加密。 - **TI SWRA522** — CC1101 wM-Bus 实现说明。 解码器已与以下内容进行了交叉核对： - **您自己的仪表** — 根据欧盟指令 2018/2002 第 9-11 条，消费者拥有法定权利访问其自身的消费数据，因此 读取通常是合法的。然而，运营商在法律上没有义务 提供 RF 接口的 AES-128 密钥，因为对称密钥通常 会带来安全和配置风险。一些供应商可能会在收到请求后 将其提供给您，但获取密钥是您个人的责任。 非欧盟司法管辖区存在同等效力的法规。 - **其他仪表** — 可能构成非法拦截私人 通信以及违反 GDPR（或同等法律）非法处理个人数据。 在将此应用程序对准非您所有的仪表之前，请查阅您所在国家/地区的法规。 ## 贡献 欢迎贡献 — 错误报告、驱动移植、UI 优化、文档。 1. **先开 issue**，对于非平凡的更改，以便我们可以对方案进行初步评估。 2. **坚持现有风格**：`Makefile` 中使用制表符，C 语言使用 4 个空格缩进， 不使用 Doxygen，注释解释*为什么*而不是*是什么*。 3. **添加测试**，在任何新驱动的 `tests/test_ports.c` 中 — 取自 `wmbusmeters/tests/test_*.txt` 的报文均可直接使用。 4. **在本地运行** `make -C tests check && ufbt` 并确保两者均通过。 5. **不要提交真实密钥、明文的真实仪表 ID，或非您所有的仪表的** 已解密捕获数据。包含这些内容的 PR 将被强制推送清理。 驱动演练请参阅 [drivers/CONTRIBUTING.md](drivers/CONTRIBUTING.md)， 数据卫生策略请参阅 [DISCLAIMER §5](DISCLAIMER.md#5-aes-keys)。 ## 路线图 - 为仍然缺失的大部分欧盟水表移植驱动 （Maddalena、Aquametro、Sensus iConA、Itron Cyble、Elster v200H）。 - 应用内密钥指纹搜索（粘贴十六进制值，查找使用它的仪表）。 - 详情页上每个仪表的 RSSI 历史记录迷你图。 - 翻译。 美国协议（Itron ERT、Neptune R900 等）**不在范围之内** — 它们属于不同的无线电协议栈。如果有人想编写，一个独立的姊妹应用 将是合适的载体。 ## 致谢 站在巨人的肩膀上 — 见上文的 [标准与参考](#standards--references)。 特别感谢 wmbusmeters 的维护者，他们将每一个欧盟仪表的怪异特性 都用清晰的代码记录下来；并感谢 Flipper Zero 开源社区提供的 SubGHz 设备插件抽象，使得支持外部 CC1101 成为一项仅十来行代码的工作。 ## 许可证 在 **GNU General Public License v3.0 或更高版本** 下发布 — 完整文本请参阅 [`LICENSE`](LICENSE)。简而言之：您可以使用、学习、 修改和重新分发本软件，但任何重新分发的副本或 衍生作品必须保留在 GPLv3 下，并随附其完整的 相应源代码。开发期间使用的 `_refs/` 目录 未随 `.fap` 一起分发，并保留其上游许可证。

标签：868MHz, AES-128, CC1101, DIF/VIF解析, EN 13757-3, Flipper Zero, OMS, 客户端加密, 射频分析, 射频模块, 嵌入式开发, 开源硬件, 无线M-Bus, 无线电接收, 无线监听, 智能电表, 气表, 水表, 热能表, 物联网协议解析, 物联网安全, 硬件黑客, 防御绕过