コンテンツにスキップ
Hapbeat devtools
JA

Q&A

このページは よくある質問（FAQ） と、実運用で見つかった トラブル対応事例（ページ下部）をまとめています。順次追加していきます。

接続関連

Section titled “接続関連”
Studio でデバイスが見つからない
  • ファームウェアが書き込まれ、Wi-Fi 設定が済んでいるか確認
  • PC とデバイスが同じネットワークに繋がっているか
  • ファイアウォールで UDP と mDNS がブロックされていないか
  • Helper が起動しているか（Studio 上部の「Helper 接続中」インジケータ）
  • Helper のログを確認: hapbeat-helper log（Helper をインストール）
Wi-Fi 接続できない
  • Hapbeat は 2.4 GHz 帯のみ対応。5 GHz 専用ルーターでは動作しない
  • Studio の Manage タブから Wi-Fi を再設定: Hapbeat を初期設定する
VR HMD（Quest 等）から直接使いたい
  • Wi-Fi UDP 方式なので HMD が同じネットワークにあれば動く
  • HMD が AP 機能を持たないためルーターなしでは Hapbeat を AP にする必要あり
複数の VR HMD と Hapbeat を 1 対 1 で組み合わせて使いたい

HMD ごとに Hapbeat を紐付ける場合も、player 番号 で分けます。

  1. 各 Hapbeat に別々の player 番号を設定する（本体のボタン操作、または Studio から）
  2. 各 HMD のアプリから、対応する player 番号を指定して送信する

どのデバイスが反応するかは、送信側が指定したアドレス（player / group / position）とデバイス側の設定が一致するかで決まります。番号が重複していると複数台が同時に反応するため、割り当てが重複していないかご確認ください。

確実に分離したい場合は、ペアごとにネットワーク（アクセスポイント）を分ける方法が最も確実です。

詳細: Address の仕組み / ターゲティング

PC でデバイスが 1 台も見つからない（有線 LAN や仮想ネットワークとの併用）

Wi-Fi 以外のネットワークが PC 上で有効になっていると起こります。次の 2 通りがあります。

  • 有線 LAN との併用: 別途センサーなどをイーサネットで繋ぎ、Hapbeat を Wi-Fi で使う構成
  • 仮想ネットワーク: Hyper-V / WSL2 / Docker Desktop / Windows サンドボックスをインストールすると vEthernet (Default Switch) などの仮想アダプターが作られます。これは LAN ケーブルを繋いでいなくても常に有効なため、「有線は使っていないから関係ない」と思える環境でも同じ症状が起きます

原因: Hapbeat のデバイス探索は UDP broadcast と mDNS を使います。PC が複数のネットワークに同時接続していると、探索パケットは Windows が優先する 1 つのネットワークにしか送出されません。そちらに Hapbeat がいなければ 1 台も見つからず、Studio がオフライン表示になります。触覚の送信は本来「見つかったデバイスへの宛先指定（unicast）」ですが、1 台も見つかっていない状態では broadcast にフォールバックするため、同じ理由で届かず、触覚再生にも影響します。

対処 1（推奨）: Unity SDK v0.4.0 以降では、各ネットワークのサブネット宛に送るようになったため、この問題は起きません。SDK を更新できる場合はそれだけで解消します（PC 側の設定変更は不要）。

対処 2: SDK を更新できない場合や、Studio / Helper をお使いの場合は、Wi-Fi アダプターのインターフェイスメトリックを他より小さく（優先度を高く）します。センサーや WSL2 / Docker への通信は宛先指定（unicast）のため、変更後も問題なく動作します。

管理者権限の PowerShell:

# 変更前の値を控える。数値が小さいほど優先度が高い
Get-NetIPInterface -AddressFamily IPv4 | Sort-Object InterfaceMetric | ft InterfaceAlias,InterfaceMetric,ConnectionState


# Wi-Fi を最優先に（エイリアス名は環境に合わせる）
Set-NetIPInterface -InterfaceAlias "Wi-Fi" -InterfaceMetric 5

元に戻す場合:

Set-NetIPInterface -InterfaceAlias "Wi-Fi" -AutomaticMetric Enabled

GUI の場合: アダプター設定 → Wi-Fi の IPv4 プロパティ → 詳細設定 → 「自動メトリック」のチェックを外し、Wi-Fi に小さい値を設定（戻すときはチェックを戻す）。

有線（センサー）と Wi-Fi（Hapbeat）は別サブネットになるようご設定ください。仮想アダプターの無効化は WSL2 / Docker の動作を壊すため推奨しません。

Studio / Helper 側の同様の対応は今後の課題です。

Kit / コンテンツ関連

Section titled “Kit / コンテンツ関連”
Studio でビルドした Kit が転送できない
  • Helper が起動中か、WebSocket（localhost:7703）に接続できているか
  • Studio 上部の「Helper 接続中」インジケータを確認
  • 対象デバイスがオンラインで Studio から見えているか確認
振動が鳴らない
  • Kit が転送されているか（Studio の Kit タブで対象デバイスへの転送状態を確認）
  • Event ID が合っているか
  • デバイスの音量（Volume）が十分高いか

その他

Section titled “その他”
複数台同時に別々の振動を出したい

player 番号で分けるのが基本です。各デバイスに player 番号（player_1、player_2 …）を割り当て、送信側で対象の player を指定すると、その番号のデバイスだけが振動します。

  • デバイス側: 本体のボタン操作、または Studio から player 番号を設定（番号は本体ディスプレイに表示されます）
  • 送信側（Unity）: EventMap の Targeting で Player を指定

Group ID も同じ仕組みで指定でき、player 番号と併用すると「チーム単位で一斉に鳴らす」といった分け方ができます。

詳細: Address の仕組み

何台まで同時に使える？ 台数が多いときの注意点

20 台程度までは、標準の Wi-Fi UDP（既定の unicast）のままで問題なくご利用いただけます。特別な構成は必要ありません。

台数が増えるときは 再生方式 にご注意ください。Hapbeat には、デバイスに事前登録した波形をコマンドで呼び出す FIRE 方式 と、音声データをリアルタイムに送信する CLIP 方式 があります。CLIP 方式は音声データを送り続けるため、台数が増えるほど通信量が増え、動作が不安定になることがあります。

  • まずは手軽に試せる CLIP 方式 で検証する
  • 本番運用は FIRE 方式 に切り替えるのがおすすめ（台数が多いほど有利）

詳細: Fire と Clip の違い

数十台規模をご検討の場合は、専用の無線方式（ESP-NOW）を使う構成もあります: 通信モデル

事例（トラブル対応事例）

Section titled “事例（トラブル対応事例）”

実際の問い合わせから一般化した事例と対処をまとめています。

バッテリー駆動中に電源が切れ、USB 給電でのみ復帰する（Band）

症状: バッテリー駆動で何度か振動させると OLED が消えて動作しなくなる。電源スイッチの入切では戻らず、USB Type-C を接続すると復帰する。電源に接続した状態では発生しない。

原因: 強い振動を再生すると一瞬だけ大きな電流が流れ、バッテリーの電圧が瞬間的に下がります。これを過放電とみなしてバッテリーの保護回路が働くと電源が遮断されます。この保護は充電（USB）を与えないと解除されないため、電源スイッチでは戻らず USB でのみ復帰します。強い振動・低い周波数の振動・残量の低下・バッテリーの劣化は、いずれもこの電圧低下を起こしやすくする要因です。

対処:

  • 再生する振動を強くしすぎない（再生強度・音量を下げる。最も効果的）
  • 低い周波数の強い振動を避ける
  • 早めに充電する／連続して頻繁に使う場合は USB 給電をしながら使う
  • バッテリー残量表示は目安として扱う（実際より多めに表示されることがあります）
  • 上記でも実用上支障がある場合はバッテリー劣化の可能性があるため、交換をご相談ください
インストール済み Kit が「events なし」と表示される（再起動すると直る）

症状: Kit をデバイスにデプロイした後、Manage（インストール済み Kit）で Kit は表示されるものの「events なし」（イベント 0 件）になる。一方、Manage の再生テストで Event ID を手入力すると振動は再生される。Helper と Studio を再起動すると直ることがある。

原因: PC に常駐する Helper のバージョンが古いと、Studio のログ表示を開いている間に、デバイスとの通信（Kit のイベント一覧取得）が一時的に不安定になることがあります。振動の再生（手入力の再生テスト）は別の通信経路のため影響を受けず、「一覧は空なのに再生はできる」状態になります。Helper / Studio を再起動すると通信状態がリセットされ、一時的に解消します。この不具合は新しい Helper（v0.1.4 以降）で修正済みです。

対処:

  • Helper を最新版に更新する（ターミナルで pipx upgrade hapbeat-helper を実行し、更新後に Helper を再起動）
  • Helper のバージョンは Studio 上部の Helper 表示、またはターミナルの pipx list で確認できます
  • 更新後は、再起動での対処は不要になります