個人開発 » beatoraja

詳細設計（2026-06-13）／実装着手¶

ユーザー方針確認の結果：データ源＝本体が直接BLE、取得経路＝本体が取得し /state.json に乗せる、表示＝現在BPM＋過去数分グラフ。

技術調査の結論¶

• Windows 上の純Java で BLE 心拍計を読む実用手段は無い（OSS の純Java BLE は Linux/BlueZ 専用、Windows 対応は商用 IPWorks のみ）。
• 「本体が直接BLE（クラウド非経由）」を保つため、小さなネイティブ BLE ブリッジを同梱する方式を採用（ユーザー承認済み）。

アーキテクチャ¶

HW706 (BLE GATT 0x180D/0x2A37)
  │ BLE notify
  ▼
hrm-bridge (Rust+btleplug, 単一バイナリ)  ── stdout NDJSON {"bpm":142} ──►  beatoraja本体
   ▲ heartRateEnabled 時に子プロセス起動                 HeartRateService(子プロセス管理/stdout読取/再接続)
                                                          └ ObsState: 1秒サンプリングのリングバッファ＋ゾーン算出
                                                          └ /state.json: heartRate{...}
                                                              ▲ overlay 1秒ポーリング
                                                          overlay: #heartrate 値＋#hrgraph 折れ線＋ゾーン色

ネイティブブリッジ tools/hrm-bridge/（Rust + btleplug）¶

• btleplug（MIT/Apache, WinRT/CoreBluetooth/BlueZ をラップ）で 0x180D を広告する HRM をスキャン→接続→0x2A37 を購読。
• 0x2A37 の先頭フラグバイト bit0 で UINT8/UINT16(LE) を判別して bpm を抽出。
• stdout に1行1JSON（{"bpm":142} / 診断用 {"event":"connected|disconnected|error",...}）。切断時はバックオフ再接続、stdin EOF / SIGTERM で終了。
• デバイス選択：既定は最初に見つけた HRM。--name/--address フィルタ任意。
• CI に Rust を入れず、既存 natives/*.dll と同様にプリビルドバイナリを natives/ にコミット（Windows 版は実機 Windows で cargo build --release）。tools/hrm-bridge/README にビルド手順。

本体 Java 側¶

• 設定追加（Config/ConfigPersistenceDto）：heartRateEnabled=false、heartRateMaxHr=190（ゾーン算出用）、heartRateDeviceFilter=""（任意）、heartRateBridgePath=""（空=OS/arch から natives/ 自動解決）。
• 新規 HeartRateService（stream/obs）：ブリッジ子プロセスの起動/監視/再起動、stdout 読取→bpm 解析→ObsState.setHeartRate(bpm)。バイナリ不在時は警告ログのみで no-op（グレースフル）。
• ObsState：心拍を Snapshot に保持。1秒ティックで最新 bpm をリングバッファ（既定180サンプル=3分）へ。10秒以上更新が無ければ stale→heartRate=null。ゾーンは maxHr に対する%で Z1..Z5。
• /state.json 拡張："heartRate": null | { "bpm":142, "zone":"Z3", "zoneIndex":3, "min":120, "max":150, "sampleSec":1, "history":[...] }（history は古い→新しい順の bpm 整数列、x軸は sampleSec で暗黙）。
• 起動条件：obsEnabled && heartRateEnabled。ObsController.start()/dispose() で起動/破棄。無効時ゼロ影響。
• 設定 UI：既存 OBS 設定と同じ PlayConfigurationView(+FXML, i18n) に「心拍数表示」「最大心拍数」「デバイスフィルタ」を追加。

オーバーレイ（web）¶

• 予約枠 #heartrate の数値表示を有効化（heartRate.bpm 既存バインド）。zoneIndex で色分け（CSS変数 Z1..Z5）。
• 新規 #hrgraph：heartRate.history を依存ライブラリ無しの inline SVG/canvas で折れ線描画（差分時のみ再描画、min/max/現在値ラベル）。?blocks= トグル対応。テーマは既存 control deck HUD に統一。
• README のブロック説明を「予約枠」→ライブ機能に更新、state.sample.json に heartRate サンプル追加。

テスト/検証¶

• Java 単体：heartRate の JSON 形（null/充填）、ゾーン境界、リングバッファ上限/stale、ブリッジ stdout 行解析（不正行は無視）。xvfb-run -a ./gradlew test。
• ブリッジ：0x2A37 フラグ解析（UINT8/UINT16 LE）の Rust 単体テスト。
• オーバーレイ：node --check ＋ DOM シムで history→グラフ点の契約検証（#182 と同方式）。
• BLE 実機（HW706→ブリッジ→グラフ）は Windows ホスト＋実機でのみ検証可能。コンテナでは Java compile/test・overlay 静的検査・ダミーブリッジ（{"bpm":...} 出力）での end-to-end を担保。

本コメントは詳細設計であり実装着手の記録。作業ブランチ feature/185-heart-rate。

MR !27 承認・develop へマージ完了につき完了。

実装サマリ（OBS連携 心拍数表示）¶

beatoraja 本体が BLE 心拍計（標準 GATT Heart Rate Service 0x180D / Measurement 0x2A37、例：CooSpo HW706）に、同梱ネイティブブリッジ（Rust+btleplug）経由で直接接続し、/state.json の heartRate{bpm,zone,zoneIndex,min,max,sampleSec,history[]} に乗せて OBS オーバーレイが現在 BPM ⊕ 直近数分の推移グラフを表示。クラウド非経由、obsEnabled=false 時ゼロ影響。

• ブリッジ：tools/hrm-bridge（スキャン→接続→0x2A37購読→フラグ解析→stdout NDJSON、再接続/終了処理）。Windows バイナリ natives/hrm-bridge-win-x64.exe を同梱。
• 本体：HeartRateService（子プロセス管理/1秒サンプリング/バックオフ再起動/不在時 no-op）、ObsState 拡張（リングバッファ3分・ゾーン算出・stale復帰・snapshot 単一ロック直列化）。
• 設定：心拍表示有効 / 最大心拍数 / デバイスフィルタ（PlayConfigurationView + i18n）。
• overlay：#heartrate に BPM ⊕ MIN/MAX ⊕ SVG 折れ線グラフ。配色は他ブロックと同一テーマ色に統一。

テスト：xvfb-run -a ./gradlew test 成功、Rust フラグ解析単体テスト、overlay DOM シム契約テスト、実機（HW706 + Windows）動作確認済み。

今後の余地：Linux/Mac 版ブリッジバイナリの同梱、heartRate.zone/zoneIndex を用いたテーマ別のゾーン色分け（データは既に /state.json に存在）。