通信モデル

Hapbeat の触覚イベントは Wi-Fi の UDP unicast でデバイスに届く。SDK が発見済みデバイスの IP へ 1 台ずつ送り、各デバイスはパケット内の target（player / group） を見て自分宛てかを判定する。

この経路は既定で有効であり、設定は不要。環境に応じて切り替える必要もない。

経路の選び方

規模・要件	使うもの
〜20 台（大半のプロジェクト）	Wi-Fi unicast（既定・設定不要）
厳密な同時発火が要る	Wi-Fi unicast + `target_time`
数十台以上、または Wi-Fi が使えない	ESP-NOW（後述）

台数と同時性

unicast は台数分を順に送るため、先頭の機体と最後の機体に時間差が出る。

台数	先頭と末尾の差
2 台	0.2〜0.5ms
5 台	0.8〜2ms
10 台	1.5〜4ms
20 台	3〜8ms
50 台	8〜20ms
100 台	15〜40ms

触覚の同時性は概ね 10〜20ms 以内なら知覚されにくいとされる。20 台までは実用上問題なく、50 台で条件次第、100 台では差を感じ得る領域に入る。

厳密な同時性が要る場合

target_time（予約再生） を使う。少し先の時刻を指定して全台に送れば、到着順に関係なく同時に鳴る。SDK は「今すぐ」ではなく「100ms 後に発火」と送り、デバイスは時刻同期した自分の時計でその時点に再生するため、ネットワークの揺らぎがあっても発火タイミングが安定する。

ただし送信側とデバイスの時計合わせが必要なため、大規模な同時駆動では個別の検討を要する。

制約

同一サブネット必須 — デバイス発見（mDNS）はルーターを越えない
2.4 GHz Wi-Fi のみ（ESP32 の制約）
VR HMD は AP 機能を持たない — ルーターなし環境では Hapbeat 自身が SoftAP になる
発見前のデバイスには unicast できない — 既知デバイスが 0 台のときは broadcast にフォールバックするため、起動直後でも触覚は届く

接続シナリオ

シナリオ	構成	用途
A. 単独プレイヤー LAN（推奨）	通常ルーター経由	自宅 / オフィス
B. マルチプレイヤー LAN	ルーター経由、プレイヤー毎に固有 player / group	同一 LAN で複数人プレイ
C. モバイルホットスポット	スマホ / PC テザリング（2.4 GHz 固定）	移動先・出張
D. Hapbeat SoftAP	Hapbeat 1 台が AP、HMD + 他 Hapbeat が STA	ルーターなし環境（Quest 等）
E. 展示ブース隔離	ブースごとに独立 AP、B と同等	イベント・展示会

詳細: Hapbeat を初期設定する / Hapbeat 概要

上位オプション: ESP-NOW

数十台同時、または Wi-Fi が使えない環境では ESP-NOW 経路を使う。

SDK / アプリ
  ↓ UDP / OSC
hapbeat-bridge (PC / ホスト)
  ↓ シリアル
hapbeat-transmitter-firmware (ESP32 送信機)
  ↓ ESP-NOW (2.4 GHz radio, AP 不要)
Hapbeat デバイス（複数台一斉）

AP を経由しないため 1 回の送信で全台に同時に届き、台数に依存しない。 代わりに ACK / 再送が無いので、時間的に分散させた冗長送信で loss を補う設計としている。ルーターも AP も不要。

通常の用途では Wi-Fi unicast で足りるため、ESP-NOW は「大規模パフォーマンス」「Wi-Fi 不在環境」「Hapbeat 専用ネットワークを組みたい」場合に採用する。

設計背景

以下は仕組みを知りたい読者向けの補足であり、通常の導入では読む必要はない。

なぜ broadcast ではなく unicast か

Wi-Fi の broadcast（group-addressed フレーム）には、送信側では回避できない遅延要因がある。

DTIM バッファリング — 同じ AP に省電力状態の端末が 1 台でもいると、AP は group-addressed フレームを次の DTIM ビーコンまで保留する。周期は 100〜300ms 級で、送信側からは制御できない。Hapbeat 本体は省電力を無効化しているが、保留を起こすのは周囲の無関係な端末（スマホ等）であり、本体側の設定では防げない
ACK / 再送が無い — broadcast は最低基本レートで送られ、loss しやすく電波占有時間も長い
unicast は速い — MAC 層の ACK + 再送があり、リンクレートで飛ぶ。10 台程度までは電波占有時間の合計も broadcast より短い

したがって「専用 AP なら broadcast で十分」ではなく、どの環境でも unicast が最良となる。

大規模なら broadcast が有利ではないか — 電波の占有時間だけを見れば、台数が増えるほど broadcast が効率的（unicast は台数分の O(N)、broadcast は O(1)）。ただしその効率と引き換えに、上記の DTIM 遅延と再送なしの取りこぼしを受け入れることになる。「多数へ同時に確実に」を狙う場面ほど、この 2 つが致命的になる。ESP-NOW が推奨になるのは、AP を介さないため DTIM が構造上存在せず、かつ 1 回の送信で全台に届くから。broadcast の利点だけを取り、欠点を捨てた形になっている。

AP の性能では解決しない — DTIM 保留は帯域や処理能力の問題ではなく、省電力端末を起こさないための規格上の動作である。省電力の端末を 1 台も入れず、ビーコン間隔と DTIM 周期を詰められる完全な管理下のネットワークなら保留は避けられるが、そこまで管理できるなら AP を挟まない ESP-NOW の方が構成も単純で有利。

このため broadcast は選択肢ではなくフォールバックとして扱う。SDK も、既知デバイスが 0 台のときだけ自動で broadcast に落ちる。

なぜアプリ層で ACK しないか

触覚は「遅れて届くより消えた方がマシ」

ゲーム中の効果音は、200ms 後に届くより、その回だけ脱落するほうが体験を壊さない。アプリ層の ACK / 再送は遅延変動を大きくするため、Hapbeat は固定遅延を優先する（unicast では MAC 層の ACK / 再送が効く）。

なぜ Bluetooth を主経路にしないか

v1 では Bluetooth を使っていたが、ペアリング管理の煩雑さ、ブロードキャストの不得手さ、PC / Quest / スマホでの API 分断、同時接続数の制約から Wi-Fi UDP に移行した。現行 BT 版は v1 互換維持のために残っているが、新規ユーザーは Wi-Fi 版（Duo WL / Band WL）が前提となる。