設定を参照
この文書は /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/)は基本的に 基本（basic） 設定のみを返します。advancedフラグが指定された設定を含めるには、 ?advanced=trueを、非推奨フラグが指定されたエイリアスを含めるには ?deprecated=trueを転送してください。「非表示」設定は内部用途に限定されており、 POST /settings/misc/hidden_settingsを通じて misc/hidden_settings設定されている場合にのみ表示されます（該当するクエリパラメータはありません）。フィルタフラグはANDで結合されます。 advancedわあ hidden すべてのフラグが指定されたキーについては、両方のゲートが開いている必要があります。既知のキーに対するPOSTおよびDELETEは、ゲートの制限を受けません。
正規キー（canonical key）を正確に使用すれば、単一キーによる検索（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、およびイベントストリームサーバーのネットワークポートとバインドアドレスです。ほとんどの項目は起動時専用です。
| キー | タイプ | 制約条件 | 説明 |
|---|---|---|---|
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/…
シリアルポートスキャンに関するポリシーです。すべての項目は「詳細（advanced）」設定です。
| キー | タイプ | 制約条件 | 説明 |
|---|---|---|---|
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 | — | カーソルがバブルに入ったとき、速度を0にリセットします。 |
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 | — | 「安全軌道（safe-trajectory）」速度制限機能を有効にします。 |
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 | — | 加わる力が0に近い場合、SDFフィールドを自動的にプローブします。 |
features/sdf/probe_on_zero_force/delay | float | 範囲 0.001～60.0 | 力が0になった後、自動プローブが開始されるまでの遅延時間（秒）です。 |
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/…
出力形式の変換 — WebSocket および HTTP JSON ペイロードに影響します。これらのキーは、セッションごとの範囲を反映するため、バージョン 3.5.1 から serialization/*から session/serialization/*に移動されました。従来のパスは、非推奨（deprecated）のエイリアスを介して引き続き解決されます。
| キー | タイプ | 制約条件 | 説明 |
|---|---|---|---|
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/* 以下に配置されており、従来のパスは非推奨（deprecated）のエイリアスを通じて引き続き解決されます。
| キー | タイプ | 制約条件 | 説明 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | ゼロ次ホールド（zero-order-hold）ウィンドウ — このウィンドウ内に受信されたプローブを抑制します（ms）。 |
rate/websocket/drop_warning_threshold | int | — | 警告が発生する前の、Windows内にドロップされたコマンドの数です。 |
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を通じてアクセスできますが、今後のマイナーバージョンで優先順位が変更されたり、名前が変更されたり、削除されたりする可能性があるため、クライアントの動作をこの設定に依存させないでください。