設定リファレンス
このドキュメントでは、/settings/エンドポイントが返すすべての設定を、それぞれのキー、型（type_hint（から）、および制約（metadata.constraint.range、および該当する場合はlocked（から）とともに一覧にまとめています。
lockedの設定は、実行時は読み取り専用です。設定ファイルから、またはHaply設定ページから変更できますが、変更を反映させるにはサービスの完全な再起動が必要ですです。これらは、以下の表でブートと記載されています。
構成
サービスの起動時に設定を上書きするための構成ファイルは、次の場所にあります：
| プラットフォーム | 場所 |
|---|---|
| Windows | C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json |
| macOS | /Library/Application Support/Haply/Inverse/haply-inverse-service-config.json |
| Linux | /etc/haply-inverse-service/haply-inverse-service-config.json |
設定ファイルは、設定キーと上書き値を対応付けるフラットなJSONオブジェクトです。キーは、/settings/ HTTPルート（API リファレンス（参照）が返す有効な設定キーである必要があります。指定されていないキーについては、サービスの既定値が使用されます。
例えば、ネットワーク構成の上書き設定は次のとおりです：
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
表示と絞り込み
/settings一覧エンドポイント（GET /settings、GET /settings/）は、デフォルトでは基本設定のみを返します。詳細な設定を含めるには?advanced=trueを、非推奨のエイリアスを含めるには?deprecated=trueを指定してください。「非表示」の設定は内部使用のために予約されており、POST /settings/misc/hidden_settingsを通じてmisc/hidden_settingsが設定されている場合にのみ表示されます（同等のクエリパラメータはありません）。フィルターフラグは AND 条件で組み合わされます。advancedとhidden両方のフラグが設定されたキーについては、両方のゲートを開く必要があります。既知のキーに対する POST および DELETE は、ゲートの対象外です。
正規のキーを正確に指定した場合、単一キーの読み取り（GET /settings/<key>）は、advanced/deprecated のゲートを迂回します。事前の知識を持つクライアントにとって便利です。非表示のキーは引き続きゲートの対象となります。
3つのランタイムトグルにより、ゲートの初期値が設定されます。これらの値は、サービスの稼働期間中ずっと保持されます：
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
misc/advanced_settings | bool | — | GET /settingsの一覧にadvancedフラグが設定された項目を含めます（既定値はfalse）。すべてのリクエストにおいて?advanced=trueを渡すことと同じです。 |
misc/deprecated_settings | bool | — | GET /settingsの一覧にdeprecatedフラグが設定された項目を含めます（既定値はfalse）。すべてのリクエストにおいて?deprecated=trueを渡すことと同じです。 |
型のマッピング
APIが返す型ヒントは、以下のJSON形式に対応しています：
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3（{x, y, z}（そのオブジェクト）GENERIC→json（任意の構造化された値）
communication/…
HTTP、WebSocket、およびイベントストリームサーバーのネットワークポートとバインドアドレスです。ほとんどのエントリは、boot時のみ有効です。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
communication/serial/enabled | bool | — | シリアルデバイス通信を有効または無効にします。 |
communication/bind_address | string | ブート | HTTPおよびWebSocketサーバーがバインドするIPアドレス。 |
communication/bind_all_interfaces | bool | ブート | localhost の代わりに、サーバーを0.0.0.0にバインドします。 |
communication/http/port | int | ブート | HTTP REST API のポート（デフォルト値 10000）。 |
communication/websocket/port | int | ブート | メインの v3.1 WebSocket ポート（デフォルト値 10001）。 |
communication/websocket/legacy_port | int | ブート | レガシーの v3.0 WebSocket ポート（既定値 10000）。 |
communication/events/port | int | ブート | イベントストリームの WebSocket ポート（既定値 10020）。 |
devices/…
devices/detection/…
シリアルポートのスキャンポリシーです。すべてのエントリは詳細設定です。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 範囲 100～10000；起動時 | シリアルポートのスキャン間隔（ms）。 |
devices/detection/handshake_timeout_s | int | 範囲 1～15 | ポートごとのハンドシェイクのタイムアウト（秒）。 |
devices/detection/max_retries | int | 範囲 1～10 | ポートごとのハンドシェイクの最大再試行回数。 |
devices/detection/failure_log_delay_s | int | 範囲 1～60 | 検出失敗が再度ログに記録されるまでの遅延（秒）。 |
devices/detection/block_looping_ports | bool | — | ループするポートが検出された場合、デバイスの準備完了状態をブロックします。 |
devices/detection/excluded_ports | json | — | 検出時にスキップするシリアルポートのパス。 |
devices/detection/additional_ports | string[] | — | 無条件でスキャンする追加のシリアルポートのパス。 |
devices/detection/allowed_vendor_id_filter | string[] | — | ポート列挙時に許可するUSBベンダーID。 |
devices/detection/port_name_substring_filter | string[] | — | 一致させる、プラットフォーム固有のポート名の部分文字列。 |
devices/detection/wireless_verse_grip_description_filter | string[] | — | ワイヤレスVerseGrip検出用の、ポート説明の一部文字列。 |
devices/detection/inverse3x_description_filter | string[] | — | Inverse3x 検出用の、ポート説明の部分文字列。 |
devices/detection/extra_ports (非推奨) | string[] | — | その代わりに devices/detection/additional_ports を使用してください。読み取りと書き込みは、正規のキーに透過的に転送されます。 |
devices/*inverse/…
これは、すべてのInverse3ファミリーのデバイスに適用されるグローバルなデフォルト値です。セッションごとの上書き設定が優先されます。
3.5.0 では、グロブは devices/inverse*/… でした。現在は、先頭の * が inverse の前に配置されます。古いリテラルを使用している設定ファイルは、バージョン 3.5.1 ではバインドに失敗するため、更新してください。キー自体については、それ以外の変更はありません。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | 範囲 0.0～2.0 | すべてのデバイスに適用される、出力値のグローバルな乗数。 |
devices/*inverse/filters/force_gate/gain | float | 範囲 0.0～1.0 | 新しいセッションのデフォルトのフォースゲートゲイン。 |
devices/*inverse/control_timeout_ms | int | 範囲 50～10000 | デバイスの制御ロックが解除されるまでのタイムアウト（ms）。 |
devices/*inverse/query_orientation_on_idle | bool | — | デバイスがアイドル状態のとき、ファームウェアから本体の向きを問い合わせます。 |
devices/*inverse/safeties/expose_in_snapshot | bool | — | デバイスごとの安全フラグを GET /devices/{id} のスナップショットに含めます。 |
devices/presets
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
devices/presets | json | — | デバイスタイプごとのデフォルトのデバイス構成プリセット（マウント変換や基底など。対象は inverse_arm_front_*、inverse_led_front_*、minverse_*、verse_grip_default、wireless_verse_grip_default、custom_verse_grip_default）。 |
devices/wireless_verse_grip/…
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | バッテリー残量（%）がこの値を下回ると、バッテリー残量低下警告が表示されます。 |
devices/wireless_verse_grip/battery/critical_threshold | int | — | バッテリー残量（%）がこの値を下回ると、バッテリー危険アラートが発生します。 |
devices/wireless_verse_grip/battery/reset_margin | int | — | バッテリー警告が解除されるまでのヒステリシスマージン。 |
devices/wireless_verse_grip/filters/orientation_filter | json | 起動時 | ワイヤレスVerseGripの向きに応じたOne Euro Filterの設定。 |
features/…
features/calibration/…
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/calibration/hall_threshold | int | 範囲 1～32 | キャリブレーション中に、ペンが装着されていると判定されるホールセンサーのレベル。 |
features/grip_hook/…
グリップフックの自動動作です。グリップが垂直に保持されている間、カーソルをロックします。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/grip_hook/enabled | bool | — | グリップが垂直に保持されているときに、グリップフックによる自動ロックを有効にします。 |
features/grip_hook/use_hall | bool | — | グリップの検出には、向きではなくホールセンサーのしきい値を使用します。 |
features/grip_hook/hall | int | 範囲 1～32 | グリップロックをトリガーするホールセンサー値のしきい値。 |
features/grip_hook/hold_duration | int | 範囲 10～1000 | トリガー後にロックを維持する時間（ms）。 |
features/navigation/bubble/…
バブルナビゲーションモジュールのデフォルト値です。bubble の動作が初めて有効になると、セッションに渡されます。各フィールドの実行時の意味については、ナビゲーションモジュール 該当ページをご覧ください。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | バブルの中心位置のデフォルト値。 |
features/navigation/bubble/center_enabled | bool | — | バブル動作が初めて有効化された際に、設定された center を適用します。 |
features/navigation/bubble/rotation_enabled | bool | — | ワークスペースの回転をナビゲーション方向に適用します。 |
features/navigation/bubble/scale_enabled | bool | — | ワークスペースのスケールをナビゲーション速度に適用します。 |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | auto_follow 中心モードにおけるドリフト速度（m/s）。 |
features/navigation/bubble/max_velocity | float | — | 速度ゾーン内の最大ナビゲーション速度（m/s）。 |
features/navigation/bubble/velocity_zone_width | float | — | バブル表面の外側にある速度ゾーンの幅（m）。 |
features/navigation/bubble/reset_velocity_on_entry | bool | — | カーソルがバブル内に入ったとき、速度をゼロにリセットします。 |
features/navigation/bubble/spring_inner | float | — | バブル中心におけるばね定数 (N/m)。 |
features/navigation/bubble/spring_surface | float | — | バブル表面におけるばね定数 (N/m)。 |
features/navigation/bubble/spring_outer | float | — | 外側境界におけるばね定数 (N/m)。 |
features/navigation/bubble/damping_inner | float | — | バブル中心における減衰係数 (Ns/m)。 |
features/navigation/bubble/damping_surface | float | — | バブル表面における減衰係数 (Ns/m)。 |
features/navigation/bubble/damping_outer | float | — | 外側境界における減衰係数 (Ns/m)。 |
features/navigation/bubble/wall_stiffness | float | — | 外側境界にある硬い壁の剛性（N/m）。 |
features/navigation/bubble/bump_width | float | — | バブル表面における触覚バンプの幅（m）。 |
features/navigation/bubble/bump_stiffness | float | — | バブル表面における触覚バンプの剛性（N/m）。 |
features/navigation/bubble/stop_at_collision | bool | — | 衝突が有効な間、バブルの中心が衝突方向へずれるのを防ぎます。 |
features/navigation/bubble/collision_threshold | float | > 0 | 衝突を検出する外力の大きさ（N）。 |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | 衝突が有効な間、velocity_zone_width に適用される乗数。 |
features/navigation/bubble/collision_exit_ratio | float | 範囲 (0,1] | ヒステリシス比。|ext_force| が collision_threshold × this を下回ると、衝突を解除します。1.0 この場合は、ヒステリシスが無効になります。 |
features/navigation/bubble/avatar_boundary_enabled | bool | — | アバターのワールド上の位置を、設定済みの avatar_boundary SDF 形状の範囲内に制限します。 |
features/safe_trajectory/…
エンドエフェクタの動きに対する速度リミッターです。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | セーフトラジェクトリの速度リミッターを有効にします。 |
features/safe_trajectory/max_vel | float | 範囲 0.01～2.0 | エンドエフェクタの許容最大速度（m/s）。 |
features/screensaver/…
セッションによって操作されていないとき、Inverse3 デバイスで再生されるアイドルアニメーションです。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/screensaver/enabled | bool | — | Inverse3 デバイスで、アイドル時のスクリーンセーバーアニメーションを有効にします。 |
features/screensaver/speed | float | 範囲 0.001～0.2 | スクリーンセーバーのアニメーションの速度。 |
features/screensaver/distracted_speed | float | 範囲 0.001～0.2 | ユーザーが近くにいるものの、操作していないときのアニメーション速度。 |
features/sdf/…
符号付き距離場（SDF）の触覚エフェクトモジュール（SDF HFX）。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/sdf/enabled | bool | — | SDF 触覚エフェクトモジュールを有効または無効にします。 |
features/sdf/state_output | bool | — | デフォルトでは、デバイスの出力ペイロードに SDF の状態を含めます。 |
features/sdf/max_count | int | 範囲 0～128 | 有効な SDF エフェクトの最大数（0 = 無制限）。 |
features/sdf/events/created | bool | — | 新しい SDF エフェクトが作成されたときにイベントを発行します。 |
features/sdf/events/deleted | bool | — | SDFエフェクトが削除されたときにイベントを発行します。 |
features/sdf/events/updated | bool | — | SDF エフェクトが更新されたときにイベントを発行します。 |
features/sdf/probe_on_zero_force/enabled | bool | — | 印加力がほぼゼロのとき、SDFフィールドを自動的にプローブします。 |
features/sdf/probe_on_zero_force/delay | float | 範囲 0.001～60.0 | 力がゼロになった後、自動プローブが開始されるまでの遅延（s）。 |
features/verse_grip_pairing/…
Inverse3 （有線または無線の）Verse Grip との取り付け／取り外しの履歴を追跡します。これは、Haply ハブのペアリングUIの基盤となります。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | ペアリングおよび取り付け／取り外しの追跡を有効にします。 |
features/verse_grip_pairing/hall_threshold_vg | int | 範囲 1～32 | 有線のVerseGripが取り付けられていると判定されるホールレベル。 |
features/verse_grip_pairing/hall_threshold_wvg | int | 範囲 1～32 | VerseGrip（無線式）が取り付けられていると判定されるホールレベル。 |
features/verse_grip_pairing/detach_debounce_ms | int | 範囲 0～1000 | 取り外しを確定するまでのデバウンス時間（ms）。 |
features/verse_grip_pairing/heartbeat_ms | int | 範囲 100～10000 | 強制的な再通知の間隔（ms）。 |
features/verse_grip_pairing/force_attached | bool | — | ホールセンサーをバイパスして、取り付け状態を常に true 強制します（ハードウェア障害時の回避策）。 |
session/serialization/…
「Transform」の出力フォーマット — WebSocket および HTTP JSON ペイロードに影響します。これらのキーは、セッション単位のスコープを反映するために、3.5.1 で serialization/* から session/serialization/* に移動しました。古いパスは、非推奨のエイリアスを介して引き続き解決されます。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | シリアル化された出力には、恒等（アイデンティティ）のデフォルト値と同じ値を持つ transform フィールドを含めます（例： position: {0,0,0}、rotation: {w:1,…}）。クライアントがすべてのフィールドの明示的な存在を要求する場合に役立ちます。デフォルト: false。 |
session/serialization/force_complete_transforms | bool | — | 向きのみを検出するデバイス（Verse Grip、Wireless Verse Grip）を含め、すべての transform 出力に position、rotation、および scale を常に出力します。これらのデバイスは通常 rotation のみを出力します。session/serialization/explicit_fields の上位互換であり、その機能を含んでいます。デフォルト: false。 |
serialization/explicit_fields (非推奨) | bool | — | その代わりに session/serialization/explicit_fields を使用してください。読み取りと書き込みは、正規のキーに透過的に転送されます。 |
serialization/force_complete_transforms (非推奨) | bool | — | その代わりに session/serialization/force_complete_transforms を使用してください。読み取りと書き込みは、正規のキーに透過的に転送されます。 |
session/…
セッションスケジューラ。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 範囲 20～500 | 警告が発生する前の、デバイスシミュレーションレートの最小許容値（Hz）。 |
rate/…
サービスのペーシング。3.5.1 で導入されました — 以下の 4 つの rate/websocket/* キーは、以前は session/commands/* の下にありました。古いパスは、非推奨のエイリアスを介して引き続き解決されます。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | ゼロ次ホールドウィンドウ — このウィンドウの範囲内で受信したプローブを抑制します（ms）。 |
rate/websocket/drop_warning_threshold | int | — | 警告が表示されるまでに、ウィンドウ内にドロップされたコマンドの数。 |
rate/websocket/drop_warning_window_ms | int | — | ドロップされたコマンドをカウントするためのスライディングウィンドウのサイズ（ms）。 |
rate/websocket/tick_on_empty_batch | bool | 上級 | WebSocket バッチ全体が破棄された場合でも、main_loop のティックをスケジュールします。 |
session/commands/zoh_window_ms (非推奨) | int | — | その代わりに rate/websocket/zoh_window_ms を使用してください。読み取りと書き込みは透過的に転送されます。 |
session/commands/drop_warning_threshold (非推奨) | int | — | その代わりに rate/websocket/drop_warning_threshold を使用してください。読み取りと書き込みは透過的に転送されます。 |
session/commands/drop_warning_window_ms (非推奨) | int | — | その代わりに rate/websocket/drop_warning_window_ms を使用してください。読み取りと書き込みは透過的に転送されます。 |
session/commands/tick_on_empty_batch (非推奨) | bool | — | その代わりに rate/websocket/tick_on_empty_batch を使用してください。読み取りと書き込みは透過的に転送されます。 |
内部専用の設定
3.5.1 では、いくつかの設定ファミリーが hidden として提供されており、内部利用専用として予約されています — rate/dispatch/*（AIMD のディスパッチレートの上限およびバックプレッシャーのしきい値）、session/freeform/*（挙動フィンガープリンティング）、および session/serialization/preview/*（オイラー四元数の出力や Wireless VerseGrip のルーティングなどのプレリリース版のシリアル化実験）。これらはデバッグ用に misc/hidden_settings からアクセスできますが、今後のマイナーバージョンで優先順位が変更されたり、名称が変更されたり、削除されたりする可能性があります。クライアントの動作をこれらに依存させないでください。