mohammed-jaouad/saeco-ble-toolkit-android

# Saeco BLE 调试工具 (Flutter / Android) **逆向工程伴侣应用**，用于解码 Saeco GranBaristo Avanti 的蓝牙低功耗 (BLE) 协议 —— 扫描、配对 (PIN)、连接、唤醒、读取 状态、解码错误、构建并发送饮品指令，并记录每一帧 TX/RX。这是让 [saeco-granbaristo-bridge](https://github.com/mohammed-jaouad/saeco-granbaristo-bridge) 固件得以实现的基础探测工具；其 Dart 协议层随后以 1:1 的比例移植到了该固件的 C++ 库中。 ## 为什么开发它 BLE 设备出厂时没有任何文档。要想控制这台机器，你首先必须*监听*：哪个特征值会通知状态、哪个接收指令、帧是如何构成的、校验和是什么，以及机器是如何应答的。这款应用就是为了在真实硬件上解答这些问题而构建的——它会记录每一个字节、重组分片指示、验证 CRC，并允许你重放指令，直到协议完全显现。 **CRC-16/CCITT-FALSE** 校验和（基于 payload 计算）已被识别，并**通过 15 个已知帧进行了验证**，因此饮品构建器现在可以动态生成有效帧，而无需重放抓取的数据。 ## 功能 - 🔍 **扫描与连接** —— 潜在的 Saeco 设备将被高亮显示并标记为 `SAECO`。 - 🔑 **密钥配对** —— 输入机器显示屏上显示的 PIN。 - 🧩 **机器界面** —— 启用指示、唤醒、轮询；实时原始标志位/进程、解码后的状态和错误。 - ☕ **饮品构建器** —— 选择饮品及参数，查看生成的帧（已确认 CRC），准备就绪后发送，随时可取消。包含逐字节确认的静态帧（Espresso、Ristretto）。 - 🧰 **原始控制台** —— 发送自由格式的十六进制帧（已验证 + CRC 状态），带有时间戳的 TX/RX 历史记录。 - 📜 **日志** —— 过滤 TX/RX/INFO，搜索、复制、导出为 `.txt` / `.json`（通过 Android 分享）。 - ⚙️ **设置** —— PIN、自动重连/唤醒、轮询间隔、初始化帧、CRC 策略、调试模式、移除配对。 ## 项目结构 ``` lib/ ├─ protocol/ pure Dart, zero deps — crc16 · saeco_frame · frame_reassembler · │ commands · drinks · drink_builder · volume_encoder · │ machine_message · machine_errors · known_frames (100% tested) ├─ ble/ saeco_ble_client (scan, GATT, bonding, indications CCCD 02 00, │ wake, writes — sequential GATT op queue) · saeco_uuids · ble_models ├─ state/ saeco_controller (orchestration + polling) · machine_state · │ providers · settings (Riverpod, persisted) └─ ui/ 6 screens + navigation ``` `protocol/` 文件夹是固件中 `saeco_protocol` C++ 库的 Dart 孪生版本——具有相同的 CRC、成帧和解码器，并针对相同的帧进行了交叉验证。 ## 运行 需要 [Flutter SDK](https://docs.flutter.dev/get-started/install) (稳定版) 以及一台 **Android 物理设备**（Android 8.0 / SDK 26+ —— 模拟器上无法运行 BLE），开启蓝牙，且机器在通信范围内。 ``` flutter pub get flutter run # on a USB-connected Android phone (USB debugging on) # 或构建/安装 debug APK： flutter build apk --debug # -> build/app/outputs/flutter-apk/app-debug.apk flutter install ``` 核心依赖项：`flutter_blue_plus` (BLE)、`flutter_riverpod` (状态)、 `shared_preferences` / `path_provider` (持久化存储)。 ## 测试 ``` flutter test # 40 tests ``` 覆盖范围：CRC（校验值 `0x29B1` + 15 个已确认的帧）、帧编解码器、饮品 构建器（精确重建 Espresso/Ristretto 抓取数据）、容量编码、 状态解析，以及累积错误解码。 ## Android 权限 `BLUETOOTH_SCAN`、`BLUETOOTH_CONNECT` (Android 12+)、`ACCESS_FINE_LOCATION` (Android ≤ 11)，在运行时请求。 ## 相关项目 - **[saeco-granbaristo-bridge](https://github.com/mohammed-jaouad/saeco-granbaristo-bridge)** —— ESP32-S3 固件，可将此解码后的协议转换为 Wi-Fi / Home Assistant 桥接。 ## 免责声明 非官方的社区项目，旨在实现互操作性和教育目的。未与 Saeco 或 Philips 存在关联、获得其认可或支持。风险自负。“Saeco”和“GranBaristo”是其各自所有者的商标。 ## 许可证 MIT © Mohammed Jaouad — 参见 [`LICENSE`](LICENSE)。

标签：Android, CRC校验, DSL, Flutter, 云资产清单, 协议分析, 安全助手, 权限提升, 物联网, 蓝牙低功耗, 逆向工程