mohammed-jaouad/saeco-granbaristo-bridge

# Saeco BLE Bridge (ESP32-S3) **将一台 Saeco GranBaristo Avanti 浓缩咖啡机变成 Wi-Fi / Home-Assistant 智能设备。** 这是一个 ESP32-S3 固件，它通过逆向工程的蓝牙低功耗与咖啡机进行通信，并在另一端提供实时 Web UI + REST/WebSocket API。 您可以通过网络上的任何浏览器——或者通过 Home Assistant——来萃取一杯咖啡。 ## 功能特性 - ☕ **全面的机器控制** — 14 种饮品、浓度、口感、温度、水量、×2 双份浓缩、萃取和取消。 - 📊 **实时萃取进度** — 直接从机器自身的遥测数据中解码出的实时进度条（研磨 → 压粉 → 萃取）。 - 🌐 **自托管 Web 应用** — "Espresso Noir" 单页应用 (SPA) 由 ESP32 的 flash 提供。无需云端，无需账户，在您的局域网 (LAN) 上离线运行。 - 🔌 **REST + WebSocket API** — WebSocket 用于即时推送，REST (`GET /api/state`, `POST /api/command`) 用于自动化。 - 🏠 **Home Assistant 集成** — 无需 broker（纯 REST）。包含传感器 + 一键萃取脚本。开箱即用的配置位于 [`integrations/homeassistant/`](integrations/homeassistant/)。 - 📶 **强制门户 Wi-Fi 设置** — 首次启动会开启一个 AP；选择您的网络，完成。凭据存储在 NVS 中。 - 💡 **支持无头运行** — RGB 状态指示灯会提示 AP / 连接中 / BLE / 准备就绪 / 错误，因此它可以在没有串口控制台的情况下独立运行。 - ✅ **经过主机测试的协议** — BLE 协议是一个无依赖的 C++ 库，包含 24 个可在您的笔记本电脑上运行单元测试。 ## 工作原理 ``` Browser / Home Assistant │ HTTP (gzipped SPA from LittleFS) + WebSocket /ws + REST /api/* ESP32-S3 (Arduino + FreeRTOS) ├─ src/net/ web_api (AsyncWebServer + WebSocket + REST) · wifi_manager (AP→STA→mDNS) ├─ src/app/ machine_controller (state machine, polling, brew) · machine_state · config_nvs ├─ src/ble/ saeco_ble_client (NimBLE central: scan / pair / indications / TX) └─ lib/saeco_protocol/ crc16 · saeco_frame · frame_reassembler · commands · drinks · drink_builder · machine_message · machine_errors │ Bluetooth Low Energy (pairing passkey shown on the machine display) Saeco GranBaristo Avanti ``` **协议层** (`lib/saeco_protocol/`) 是纯头文件 C++，**没有 Arduino/BLE/Wi-Fi 依赖**，因此可以在本地针对捕获的 参考帧进行测试。其他所有内容都构建在它之上。所有跨任务工作 （AsyncTCP 服务器任务和 NimBLE 主机任务）都在锁的 保护下调配到主循环中——该固件经过了并发审计。 ## 协议简述 - **帧 (Frame):** `FE FF 0F 00 ` - **校验和:** CRC-16/CCITT-FALSE (多项式 `0x1021`, 初始值 `0xFFFF`)，**仅对 payload 计算**。 - **ACK:** 机器以 `action + 1` 进行回复。 - **指示消息是分段的**，在解析前必须进行重组。 - **配对** 需要机器显示屏上显示的通行密钥 (passkey)。 - **实时遥测:** 轮询 `0C AF 30` 会返回 `31 7B` (阶段 `0x01` 研磨 · `0x0A` 压粉 · `0x03` 萃取 · `0x10` 过渡)。 关于逆向工程（以及背后的折腾故事）的更完整记录在我的博客上。 ## 快速开始 需要 [PlatformIO](https://platformio.org/) 和一块 ESP32-S3 开发板 （`board = esp32-s3-devkitc-1`；Super Mini 也可以）。NimBLE-Arduino、 ESPAsyncWebServer 和 ArduinoJson 会自动安装。 ``` # 在你的机器上运行 protocol 单元测试（无需硬件） pio test -e native # 24 tests # 构建 + 烧录 firmware pio run -e esp32-s3 -t upload # 构建 + 上传 web UI（LittleFS filesystem image） pio run -e esp32-s3 -t uploadfs # Serial monitor（可选） pio device monitor -b 115200 ``` ## 首次设置 (Wi-Fi) 1. 首次启动时，bridge 会开启一个接入点 **`SaecoBridge-XXXX`**（强制门户位于 `192.168.4.1`）。 2. 连接它，选择您的家庭 Wi-Fi 和密码 → bridge 会将它们保存到 NVS 并重启。 3. 它会作为站点 (station) 加入，关闭 AP，发布 mDNS **`saeco.local`**，并提供 UI 访问。打开 `http://saeco.local/`。 ## API 完整的 WebSocket + REST 参考文档位于 [`API.md`](API.md)。重点如下： - `GET /api/state` — 完整的机器状态（与 WebSocket 的 `state` 消息格式相同） - `POST /api/command` — 与 WebSocket 相同的 JSON 命令，例如 `{"cmd":"brew"}`, `{"cmd":"selectDrink","id":5}`, `{"cmd":"cancel"}` - `GET /api/catalogue`, `GET /api/wifi/scan`, `POST /api/wifi`, `POST /api/config` 串口调试控制台: `i` 指示 · `w` 唤醒 · `p` 轮询 · `d` 详细轮询 · `b` 萃取 · `c` 取消 · `v` 详细输出 · `wifi |` · `factory`。 ## Home Assistant 将 [`integrations/homeassistant/configuration.yaml`](integrations/homeassistant/configuration.yaml) 放入您的 HA 配置中（设置您的 bridge IP），重启后，您将获得连接性/ 就绪/萃取中/进度等传感器，以及 `script.saeco_espresso`, `saeco_ristretto`, `saeco_cappuccino` 等脚本。无需 MQTT broker。您还可以将 Web UI 嵌入为 全屏 HA 面板。请参阅该文件夹中的 README。 ## 配置和机密 机器特定的值（BLE 地址、通行密钥、Wi-Fi、bridge IP）**不会** 被编译进去——bridge 在运行时进行配置，并将凭据存储在 NVS 中。 对于本地脚本配置，请在仓库根目录下复制 `.env.example` → `.env`（已被 git 忽略）。 ## 相关项目 - **[saeco-ble-toolkit-android](https://github.com/mohammed-jaouad/saeco-ble-toolkit-android)** — Flutter/Android 逆向工程工具包，用于解码此固件所使用的协议。 ## 免责声明 这是一个非官方的社区项目。不隶属于 Saeco 或 Philips，也未获得其认可或支持。 风险自负——您必须对自己的硬件负责。 "Saeco" 和 "GranBaristo" 是其各自所有者的商标。 ## 许可证 MIT © Mohammed Jaouad — 详见 [`LICENSE`](LICENSE)。

标签：REST API, TCP SYN 扫描, WebSocket, Web UI, 云资产清单, 依赖分析, 嵌入式固件, 智能家居, 物联网, 网络测绘, 蓝牙低功耗, 逆向工程