HR PUSH / 心率推送

中文 | English | 日本語

一个用 Flutter 开发的跨平台 BLE 心率监控与推送工具。连接心率设备后，可将实时 BPM、在线状态与心率百分比同步到 HTTP/WS、OSC、MQTT 等链路，方便在桌面端或周边应用中联动使用。

⚠️ 已知问题

• Windows 平台下中文路径可能会存在运行失败的问题，建议在英文路径目录下执行本程序。

✨ 亮点功能

• BLE 扫描与连接：自动过滤无关广播，优先匹配心率服务/常见穿戴品牌（新增小米手环 10 等设备支持）。
• 智能自动重连：记忆最近成功设备，断连或心率长时间无更新时自动重连。
• 实时展示：全新“Lub-Dub”仿生心跳动画，BPM、上次更新时间、RSSI 信号强度一目了然。
• 多协议推送：HTTP/WS、OSC、MQTT 任意组合启用，统一 JSON payload。
• 调试视图：查看附近广播、Service UUID、RSSI、厂商数据长度。
• 桌面端体验：Windows/macOS/Linux 固定竖屏窗口；Windows 支持托盘最小化。
• Android 常驻通知：全新设计的原生“实时活动”风格通知卡片，支持 Android 12+ (ColorOS 14 等) 系统。

🗺️ 适用场景

• 常驻心率推送：家里/工作室有一台不关机的 Mac mini 或 Windows 主机，手表常开心率广播，回到范围内即可自动连接并持续推送。
• VRChat/自定义程序联动：通过 OSC 或 HTTP/WS/MQTT 订阅心率，用于状态显示、动画驱动或自定义交互。

📷 效果预览

首页	配置页

🚀 快速开始（用户）

1. 启动应用后点击“重新扫描”。
2. 选择心率设备并连接（现已支持更多广播心率的手环/手表）。
3. 在配置页填写推送目标（HTTP/WS、OSC 或 MQTT），保存后即可推送。

若设备仅广播心率但不支持连接，仍可在“广播调试”视图中查看数据与信号，但推送仅在连接并订阅特征后触发。

🔗 协议与数据

推送协议

• HTTP：对 http(s):// 目标发送 JSON（POST，超时 3 秒）。
• WebSocket：对 ws(s):// 目标发送 JSON 文本，连接断开后会自动重连。
• OSC：填写 host:port 后通过 UDP 发送；支持 bool/int/float 与 ChatBox 文本。
• MQTT：填写 Broker 后启用，支持端口/Topic/用户名/密码/Client ID，QoS 1 发布。

数据格式

所有协议发送相同的 JSON payload。

• 心率事件

{
  "event": "heartRate",
  "heartRate": 85,
  "percent": 0.42,
  "connected": true,
  "device": "Polar H10",
  "timestamp": "2025-12-25T09:00:00.000Z"
}

• 连接事件

{
  "event": "connection",
  "connected": false,
  "device": "Polar H10",
  "timestamp": "2025-12-25T09:05:00.000Z"
}

percent = heartRate / 最大心率，范围 0~1。

⚙️ 配置项说明

🎮 VRChat（OSC）

• 推荐搭配默认 OSC 参数插件：booth.pm/zh-cn/items/5531594
• 也可在 Avatar 参数中自行监听上述 OSC 路径。

测试截图

安卓设备状态栏

🧩 设备兼容性

已验证设备

蓝牙广播发送端

1. Garmin Enduro 2（佳明手表，蓝牙广播推送）
2. Xiaomi Smart Band 10 / 9（小米手环9/10，更新固件后开启心率广播）
3. HuaWei Watch GT 4
4. Apple Watch（需配合第三方 App，见下方说明）

蓝牙广播接收端

1. iPhone 15 Pro（无证书可自行签名）
2. OnePlus Ace / ColorOS 14 (Android 14)
3. MacBook Pro M5（macOS Tahoe 26.1）
4. Windows（蓝牙适配器需支持 BLE）

⌚ Apple Watch 准备工作

⚠️ 重要提示： Apple Watch 不原生支持标准 BLE 心率广播协议。你需要安装第三方 App 将心率数据转发为标准 BLE 信号后，HR PUSH 才能接收。

为什么需要第三方 App？

HR PUSH 通过标准 BLE 心率服务（UUID: 0x180D）接收心率数据。Apple Watch 默认不广播此服务，而是将心率数据保留在 Apple HealthKit 生态内。因此需要借助第三方 App 将心率转发为标准 BLE 信号。

推荐方案：HeartCast（免费）

HeartCast 是一款免费 App，可将 Apple Watch 心率通过 iPhone 以标准 BLE 心率服务广播出去。

设置步骤：

1. 在 iPhone 和 Apple Watch 上安装 HeartCast
2. 确保 iPhone 和 Apple Watch 已配对并正常连接
3. 在 Apple Watch 上打开 HeartCast，点击 Start 开始广播
4. 在运行 HR PUSH 的设备上点击"重新扫描"
5. 在设备列表中找到类似 HeartCast 或 iPhone (xxx) 的设备并连接

注意事项：

• HeartCast 通过 iPhone 中转广播，因此 HR PUSH 实际连接的是 iPhone 而非 Apple Watch
• 需保持 HeartCast 在 Apple Watch 前台运行，或开启后台模式
• iPhone 需开启蓝牙且与 HR PUSH 接收端在同一范围内

其他可选方案

🛡️ 平台支持与权限

• Android：需要 BLE 扫描/连接权限（Android 12+ 无需定位，11 及以下需定位权限）。若想显示状态栏卡片，请允许通知权限。
  • ColorOS/MIUI/HyperOS 等：需在系统设置中打开应用通知，并允许后台运行/自启动，否则可能看不到常驻卡片或后台停止更新。
• iOS/macOS：首次启动会请求蓝牙权限。

🔧 开发与构建

• 主要代码：lib/main.dart（UI 与交互）、lib/heart_rate_manager.dart（扫描、连接、心率订阅与推送）。
• 依赖安装：flutter pub get。
• 运行：flutter run -d <device>。
• 测试：flutter test。
• 打包：flutter build apk|ios|windows|macos|linux。
• 代码风格：2 空格缩进；dart format .；启用 flutter_lints。

🧾 更新日志

v1.7.0

• CI/CD 优化：新增 CI 工作流（代码分析 + 测试）；优化 Release 构建时间，合并步骤并移除冗余操作。
• 版本自动同步：新增 sync-version.sh 脚本，发布时自动同步版本号到代码中。
• 文档补充：新增 CONTRIBUTING.md 贡献指南和 ARCHITECTURE.md 架构文档。
• 国际化完善：中/英/日三语种新增 15+ 翻译键值，支持更多 UI 状态本地化。
• 代码架构优化：新增 lib/services/ 模块，提取 OSC、MQTT、HTTP/WS 推送服务为独立类。

v1.6.1

• Android 优化：更新 Proguard 规则，优化构建混淆。
• BLE 适配器微调：优化 universal_ble 适配层，提升连接稳定性。
• Windows 构建增强：升级 C++ 标准至 20，并修复编译告警；CI 现在会自动上传 Windows 构建产物。

v1.6.0

• BLE 架构升级：引入 universal_ble 库，使用原生 WinRT API 替代不稳定的 win_ble，大幅提升 Windows 平台蓝牙连接稳定性。
• 跨平台统一：新增 BLE 抽象层 (lib/ble/)，同一套代码支持 Windows/macOS/iOS/Android/Linux。
• 设备兼容性增强：支持所有标准 BLE 心率服务 (0x180D) 设备，包括 Polar、Garmin、Wahoo、小米手环等。
• 代码优化：移除 Windows 专用的连接重试逻辑和设备名编码修复，由统一的 BLE 层处理。

v1.5.0

• UI 重构：首页心率动画重构，采用更自然的仿生“Lub-Dub”跳动节奏与波纹扩散效果。
• 功能增强：Android 端状态栏通知全新改版为 Native 布局（类似 iOS 实时活动风格），适配 Android 12+ (ColorOS 14) 系统，修复了部分机型不显示通知的问题。
• 兼容性：修复了小米手环 10 (Xiaomi Smart Band 10) 及部分以 Mi / Xiaomi 命名的设备无法被扫描到的问题；增加了详细的 BLE 服务发现日志以便排查连接问题。
• 优化：移除未使用的资源文件，精简代码逻辑。

v1.4.0

• Android：状态栏/导航栏颜色同步与沉浸式刷新优化（含部分定制 ROM 适配）。
• Android：常驻通知通道与样式升级，权限请求与颜色配置更稳定。
• Android：Play Core 适配 targetSdk 34（迁移至 feature-delivery），Release 构建签名更完整。
• 性能：心率 UI 刷新节流，降低无效重建提升流畅度。
• 工程：全平台包名统一为 moe.iacg.hrpush。

v1.3.4

• OSC：新增 ChatBox 心率推送，支持 {hr}/{percent} 模板与节流/去重，避免刷屏。
• UI：设置页新增 ChatBox 开关与模板输入；移除旧的 ChatBox 建议提示文案。
• 文档与仓库：README 结构重构；新增 MIT License；.gitignore 增加本地发布脚本忽略。

v1.3.3

• UI：应用标题统一为“心率推送”（桌面窗口、应用标题、iOS 显示名、测试文案）。
• UI：主页/配置页布局调整，设置按钮与保存按钮样式统一。
• OSC：推送心率时强制同步在线状态，避免状态滞后。
• Android：常驻通知通道更新，避免旧通道冲突。
• CI：Release 流程移除未签名 iOS 打包步骤。
• Release：发布包命名统一为 hr-push 前缀（macOS/Windows）。
• 文档：新增/更新 VRChat 与安卓截图、补充已测试设备清单与 Windows 中文路径已知问题说明。
• 资源：替换主界面/配置页/VRChat 截图。
• 开发：忽略 .vscode/settings.json，测试用例标题同步新名称。

v1.3.1

• Windows：最小化到托盘后支持点击托盘图标恢复窗口。
• Windows：掉线后自动重连更稳定（扫描卡死自愈、广播心率候选识别增强、陈旧连接句柄清理）。
• UI：减少无关重建，整体交互更流畅。
• OSC：/avatar/parameters/hr_connected 更贴合实际在线状态（抗抖动与掉线恢复）。

v1.3.0

• 新增 MQTT 推送（Broker 填写即启用，端口/Topic/鉴权可配）。
• Android 新增通知栏常驻心率卡片，并自动按刷新间隔更新。
• RSSI 轮询刷新间隔与配置一致，连接后持续刷新信号。
• 自动重连逻辑与按钮状态修复，避免重连死锁和重复连接。
• Windows：BLEServer 在中文用户名/路径下运行更稳定（Public ASCII 临时目录 + 正确工作目录）。

v1.2.2

• Windows：最小化自动隐藏到系统托盘，悬停显示在线状态与心率摘要。
• Android：发布构建启用 R8 混淆、资源压缩与 ABI 分包；Windows/macOS/iOS 开启链接优化以减小体积。

v1.2.1

• Windows：BLE 连接在数据长时间未更新时会主动重连，提升掉线恢复成功率。

v1.2.0

• Windows/macOS/Android/iOS 统一使用 images/logo.png 生成应用图标。
• Windows：最小化/失焦时暂停心跳动画，降低 GPU 占用；检测心率数据长时间未更新时主动重连。
• README 补充中文路径构建提示。
• 依赖配置同步：flutter_launcher_icons 扩展桌面平台支持。

📜 开源协议

本项目采用 MIT License，详见 LICENSE。

🌐 多语言 README

• English: README_EN.md
• 日本語: README_JA.md

🤝 贡献与反馈

欢迎提交 Issue / PR，一起完善 BLE 兼容性与推送链路。若在特定设备或平台遇到问题，请附上日志与环境信息，便于复现。