MarkS0485/Ember

# Ember 针对 **HeatGenie / HCalory** 类蓝牙柴油空气加热器的独立、干净环境（clean-room）替代客户端。它们使用与原厂应用相同的 BLE 线上传输协议，但实现了更简洁的代码，并且**无需账户、云服务或互联网依赖**——所有操作均通过低功耗蓝牙（Bluetooth LE）在本地运行。 ## 功能 - **直接 BLE 控制** — 扫描、绑定、启动 / 停止 / 净化排气、设置目标温度或功率级别，以及读取实时遥测数据（温度、电源电压、运行状态、故障代码）。 - **双加热器协议，统一抽象** — `HCalory` 和 `HeatGenie` 传输格式（两者均为 Tuya-BLE 封装）位于通用的协议接口之后；根据设备自动选择合适的编解码器。 - **调度** — 按每个加热器设置每日定时开/关程序。 - **自动启动/停止** — 基于规则的自动化（保持恒温，或在设定时间段内运行）。 - **分组** — 将多个加热器组合为一个逻辑区域进行统一驱动。 - **油箱跟踪** — 根据运行时间和功率级别估算剩余油量，并支持**低油量自动停止**，防止油泵干转。 - **海拔补偿** — 根据当地海拔调整燃油/空气混合比（柴油加热器在高海拔地区会运行得过浓）。 - **远程访问** — 桌面客户端托管一个小型的经过身份验证的 API 服务器（HMAC 签名请求、自签名 TLS、可选的 UPnP 端口转发、二维码配对），Android 应用可与之配对，从而在蓝牙范围之外也能控制加热器。 - **诊断** — 原始数据帧日志、标志 / 开关检查器，以及用于协议开发的手动命令输入框。 ## 仓库结构 ``` android/ Android client — Kotlin + Jetpack Compose, min SDK 31 (Android 12). A foreground service owns the BLE link and survives backgrounding. Package com.emberheat. windows/ Windows client — C# / .NET 10, WPF (MVVM). Direct BLE via Windows.Devices.Bluetooth, plus the optional remote API server (ASP.NET Core Kestrel hosted inside the desktop app). docs/ Protocol documentation — the shared source of truth. OLDSRC/ Decompiled vendor app + reference APKs. Third-party material; git-ignored, never pushed. ``` `docs/BLE_PROTOCOL.md` 是有关帧格式、服务 / 特征值发现、操作码、传感器编码和固件特性的权威参考文档。两个客户端均遵循此文档；如果实际传输协议与文档不一致，会优先修正文档。 ## 架构 两个客户端共享相同的分层设计： - **传输层** — 在加热器的 `0x181A` GATT 服务上使用 Tuya 风格的 BLE 帧（`TuyaBleFrame`）；通过属性位而非硬编码的 UUID 来发现特征值。 - **协议层** — 位于统一接口背后的 `HCalory` 和 `HeatGenie` 实现，暴露通用的遥测数据和特定于型号的功能。 - **控制逻辑** — 调度、自动启动/停止规则、分组分发和燃料跟踪，全部由实时遥测数据流驱动。 - **远程访问** — Windows 应用可以通过经过 HMAC 身份验证的 HTTPS API 暴露其已绑定的加热器；Android 应用与之配对（通过二维码或手动方式），并在超出 BLE 范围时远程控制加热器。 ## 构建 ### Android 需要 JDK 17 和 Android SDK（或 Android Studio Iguana+）。在 `android/` 目录下： ``` ./gradlew :app:installDebug # build + install the debug APK to a connected device ``` 发布构建（`./gradlew :app:assembleRelease`）生成的是未签名版本。 ### Windows 在 Windows 10/11 上需要 **.NET 10 SDK** (x64)。在 `windows/` 目录下： ``` dotnet build Ember.sln dotnet run --project src/Ember # launch the WPF app ``` `src/HcaloryTest` 是一个用于协议调优和抓包的小型控制台工具。 ## 硬件要求 - 一台位于约 10 米范围内且正在广播的 HeatGenie / HCalory 类 BLE 柴油加热器（只要未连接到其他中心设备，它就会持续广播）。 - 蓝牙 4.0+ 模块。在 Windows 上，必须激活 Microsoft BLE 协议栈（即运行 `BthLEEnum` / `Microsoft.Bluetooth.Legacy.LEEnumerator` 服务）。 ## 敏感信息 未提交任何敏感信息。`local.properties`、`google-services.json`、TLS 材料（`*.pfx` / `*.p12`）以及已配对客户端的状态均已被 git 忽略。 ## 安全须知 柴油空气加热器会燃烧燃料并产生废气，其中包括一氧化碳。 这是用于控制燃烧硬件的非官方软件：请务必使用有效的 CO 警报器，切勿在有人占用的封闭空间内运行无排气口的加热器，并谨慎对待远程或自动启动功能。 ## 许可证 基于 **GNU General Public License v3.0** 授权 — 详见 [LICENSE](LICENSE) 获取完整文本。

标签：Android应用, Windows应用, 柴油加热器, 物联网协议, 物联网控制, 自动化控制, 蓝牙低功耗