設定リファレンス
このドキュメントでは、/settings/エンドポイントが返すすべての設定を、それぞれのキー、型（type_hintから）、および制約（metadata.constraint.range、および該当する場合はlockedから）とともに一覧にしています。
lockedの設定は、実行時には読み取り専用です。設定ファイルから、またはHaply Hubの設定ページから変更できますが、変更を反映させるにはサービスの完全な再起動が必要です。これらは、以下の表でbootと表記されています。
構成
サービスの起動時に設定を上書きするための構成ファイルは、次の場所にあります：
| プラットフォーム | 場所 |
|---|---|
| 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 | boot | HTTPおよびWebSocketサーバーがバインドする IP アドレス。 |
communication/bind_all_interfaces | bool | boot | localhost の代わりに、サーバーを0.0.0.0にバインドします。 |
communication/http/port | int | boot | HTTP REST API のポート（既定値 10000）。 |
communication/websocket/port | int | boot | メインの v3.1 WebSocket ポート（既定値 10001）。 |
communication/websocket/legacy_port | int | boot | レガシーの v3.0 WebSocket ポート（既定値 10000）。 |
communication/events/port | int | boot | イベントストリーム WebSocket ポート（既定値 10020）。 |
devices/…
devices/detection/…
シリアルポートのスキャンポリシーです。すべてのエントリーは高度な設定です。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 範囲 100–10000; 起動時 | シリアルポートのスキャン間隔（ms）。 |
devices/detection/handshake_timeout_s | int | 範囲 1–15 | ポートごとのハンドシェイクのタイムアウト（s）。 |
devices/detection/max_retries | int | 範囲 1–10 | ポートごとのハンドシェイクの最大再試行回数。 |
devices/detection/failure_log_delay_s | int | 範囲 1–60 | 検出失敗を再度ログに記録するまでの遅延（s）。 |
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 | range 0.01–2.0 | エンドエフェクタの許容最大速度 (m/s)。 |
features/screensaver/…
セッションによって操作されていないとき、Inverse3 デバイスで再生されるアイドルアニメーションです。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/screensaver/enabled | bool | — | Inverse3 デバイスでアイドル時のスクリーンセーバーアニメーションを有効にします。 |
features/screensaver/speed | float | range 0.001–0.2 | スクリーンセーバーアニメーションの速度。 |
features/screensaver/distracted_speed | float | range 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 | range 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 | range 0.001–60.0 | 力がゼロに低下してから自動プローブを開始するまでの遅延 (s)。 |
features/verse_grip_pairing/…
Inverse3 と（有線または無線の）Verse Grip との間の取り付け／取り外しを追跡します。Haply Hub のペアリング UI の基盤となります。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | ペアリングおよび取り付け／取り外しの追跡を有効にします。 |
features/verse_grip_pairing/hall_threshold_vg | int | range 1–32 | 有線の VerseGrip が取り付けられていると判定されるホールレベル。 |
features/verse_grip_pairing/hall_threshold_wvg | int | range 1–32 | 無線の VerseGrip が取り付けられていると判定されるホールレベル。 |
features/verse_grip_pairing/detach_debounce_ms | int | range 0–1000 | 取り外しを確定するまでのデバウンス時間 (ms)。 |
features/verse_grip_pairing/heartbeat_ms | int | range 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 からアクセスできますが、後のマイナーバージョンで昇格、名称変更、または削除される可能性があります。クライアントの挙動をこれらに固定しないでください。