OpenHOYI
产品介绍网站 · 功能状态 · 实机验收记录
这是什么
OpenHOYI 是面向 HOYI 咖啡机的开源 Android 应用，使用 Kotlin 原生开发。
通过蓝牙连接咖啡机和电子秤，在手机或平板上选择萃取曲线、观察实时数据，回看每一杯的记录。
项目目前处于 Alpha 阶段，已有双设备连接、受监护萃取与手动停止的实机记录，部分控制功能仍待完整验收。
可以做什么
- 连接设备：连接咖啡机和电子秤，查看实时读数、连接状态与机器告警。
- 选择曲线：浏览 100 条工厂曲线，按分类或名称查找，设置首页的 5 个快捷槽位。
- 观察萃取：实时查看压力、温度、水流、秤流速与重量；启动前确认，萃取中可手动请求停止。
- 管理机器：查看和调整温度、加热、照明、运行模式、拨杆模式与睡眠计划，等待机器回报确认设置结果。
- 回看记录：离线查看萃取历史与采样曲线，导出历史 ZIP；也可导入旧版历史，单独只读查看。
- 排查问题：导出传输与操作日志，帮助定位连接与设备问题。
具体实现与验证进度见功能状态、覆盖矩阵和实机验收记录。
支持什么
平台与咖啡机
| 项目 | 当前范围 |
|---|
| 手机 / 平板 | 支持 BLE 的 Android 8.0（API 26）及以上设备 |
| 界面语言 | 简体中文、English；在应用内切换，旧的其它语言偏好回退为中文 |
| 咖啡机 | HOYI；固件 1.1.3 已实机验收并开放控制；1.1.4、1.1.5 静态协议证据支持放开（含完整流量曲线），待实机启停/设置验收 |
| 萃取曲线 | 可启动已校验的工厂曲线；导入的个人曲线暂只读 |
其他咖啡机固件处于只读范围：首页会显示固件版本与“暂不支持新版固件”，不发送控制帧；认证后读取不到兼容设置帧时会明确提示协议初始化超时，不会无限停留在连接中。目前不提供其他平台的应用。
电子秤
| 品牌 / 型号 | 接入状态 | 可用功能 |
|---|
| BOOKOO（当前已采集协议） | 已接入，有实机连接与归零通知记录 | 重量、设备流速、去皮 |
| Felicita（指定 ASCII 通知协议） | 已接入，待实机验证 | 克单位重量、手动去皮；旧只读绑定须重新扫描选择 |
| TIMEMORE DOT（TES017） | 已按公开协议接入，待实机验证 | 重量、设备流速、电量、手动去皮 |
| TIMEMORE Basic3 Link（TES016） | 已按公开协议接入，待实机验证 | 重量、设备流速、电量、手动去皮 |
旧款 TIMEMORE（广播名 timemore scale） | 实验性只读，待实机验证 | 指定双通道协议的重量读数 |
Acaia A（PROCHBT / ACAIA） | 已接入，待实机验证 | 确认克单位后的重量、手动去皮 |
Acaia AP（LUNAR / PEARL / PYXIS） | 已接入，待实机验证 | 确认克单位后的重量；暂不提供去皮 |
DiFluid（Microbalance / difluid / Mb Ti） | 已接入，待实机验证 | 自带克单位的重量、手动去皮；协议最低固件 Microbalance V300 / Ti V010 |
适配范围以表中型号与协议为准，不代表品牌全系列兼容。
应用与构建
| 应用 / 构建 | 用途 | Android 包名 |
|---|
| OpenHOYI（主包） | 供用户使用，连接真实设备 | io.openhoyi.mobile |
| Mock | 使用模拟设备，体验功能与调试界面 | io.openhoyi.mobile.mock |
| OpenHOYI Lab | 协议采集与连接诊断 | io.openhoyi.lab |
这些应用可与旧版 HOYI App 并存，但同一台设备不能同时供多个 App 连接。旧版数据需手动导出、导入；Mock 结果不代表真实设备验收通过。
如何贡献代码
欢迎修复问题、改善体验、补充文档或参与设备适配。较大的改动请先通过 Issues 讨论范围与验证方式。
- Fork 仓库，从最新
develop 创建短分支，例如 feature/scale-support 或 fix/connection-state。
- 完成改动并补充与风险相称的测试；设备适配请记录型号、固件与脱敏协议证据，不把离线测试当作实机验收。
- 提交 PR 到本仓库的
develop，说明改动目的、验证结果与已知限制，等待必需检查通过；不要直接推送 main / develop。
完整规则见贡献工作流。只想反馈问题也很欢迎，请附上应用与 Android 版本、设备型号与固件、复现步骤及脱敏日志，不要上传设备密码或个人信息。
本地构建
准备 JDK 17 和 Android SDK 35，使用仓库自带的 Gradle Wrapper：
# 将 YOUR_USERNAME 替换为你的 GitHub 用户名
git clone --branch develop https://github.com/YOUR_USERNAME/openhoyi.git
cd openhoyi
git switch -c feature/scale-support
使用 Android Studio 配置 SDK，或设置 ANDROID_HOME；也可在本地 local.properties 中填写 sdk.dir，不要将该文件提交到仓库。
| 构建 | 命令 | APK 路径 |
|---|
| Alpha（Debug） | ./gradlew :mobile:assembleDebug | mobile/build/outputs/apk/debug/mobile-debug.apk |
| Mock | ./gradlew :mobile:assembleMock | mobile/build/outputs/apk/mock/mobile-mock.apk |
| Lab | ./gradlew :app:assembleDebug | app/build/outputs/apk/debug/app-debug.apk |
若无法访问 Google Maven，可在命令后添加 -PgoogleMirror=aliyun。
连接已开启 USB 调试的 Android 设备后，可安装构建产物，例如 Alpha：
adb install -r mobile/build/outputs/apk/debug/mobile-debug.apk
覆盖安装前，请确认咖啡机空闲、签名与原安装一致，并在构建时用 -PhoyiVersionCode=<更大的版本码> 指定递增版本。平板上的 Debug 与 Mock 应从同一源码以相同版本同步更新，不要通过卸载、清数据或降级绕过冲突。签名与升级要求见安装包分发说明。
首次连接时，开启蓝牙并授予扫描、连接权限，断开其他 App，按提示输入咖啡机的六位设备密码；电子秤需单独连接，并按设备说明进入可发现状态。等待设备就绪、实时读数更新后再操作。
项目结构与验证
| 模块 | 职责 |
|---|
mobile | Alpha 应用及 Mock 构建：连接、曲线、萃取、历史与设置 |
app | Lab 应用：诊断、采集与日志导出 |
protocol-core | 协议编解码，无 Android 依赖 |
device-session | 设备会话、命令队列、重连与控制状态机，无 Android 依赖 |
bluetooth-android | Android BLE 扫描、GATT 与设备会话桥接 |
trace-core | 共用日志与 ZIP 导出，无 Android 依赖 |
提交前运行与改动相关的检查，例如：
./gradlew :protocol-core:check :device-session:check :mobile:testDebugUnitTest
涉及启动、停止、去皮或设置写入时，还需要机器回报与实际动作的证据；GATT 写入成功本身不代表设备已经执行。更多开发资料见架构说明、Lab 使用说明与旧版曲线迁移。
赞助与交流
如果 OpenHOYI 帮到了你，可以请我喝杯咖啡；遇到问题或想聊用法，也欢迎进群。赞助完全自愿，不影响功能与支持。
群二维码会过期；失效后请到 issues 留言。
许可证
项目采用 GNU GPL v2 许可证，使用、修改或分发前请阅读许可条款。
免责声明与使用风险
OpenHOYI 是个人开发的开源实验项目，与咖啡机制造商无关联，也未获得其认证。本应用会通过蓝牙向咖啡机发送控制指令；软件缺陷、协议理解偏差或设备兼容性问题，可能导致控制异常、设备无法使用，甚至设备损坏。
Debug / Alpha 版本仅供了解风险的用户自行评估和试用，并非经过完整验证的正式产品，不保证功能正确、持续可用或适用于你的设备。试用时请在机器旁看守，并保留机器本身的停止手段。 出现异常或操作结果未知时，请停止使用并核对机器实际状态，不要反复发送控制指令。
在适用法律允许的最大范围内，本项目及其贡献者按“现状”提供软件，不作任何明示或默示保证，也不对使用或无法使用本项目造成的设备不可用、损坏、数据丢失或其他损失承担责任。本声明不排除或限制适用法律规定不得排除或限制的责任。完整许可条件见 LICENSE。
