設定の参考
このドキュメントでは、以下の内容を記載しています。 /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 「advanced」とマークされた設定を含めることができ、以下を指定します。 ?deprecated=true 廃止されたエイリアスを含めることができます。この設定は内部使用のみを目的としており、 POST /settings/misc/hidden_settings 設定 misc/hidden_settings その後表示されます（対応するクエリパラメータがありません）。フィルタフラグ間の関係は論理積（AND）であり、つまり、すべてにチェックが入っている場合 advanced 和 hidden このキーに対しては、2つの制限を同時に解除する必要があります。既知のキーに対するPOSTおよびDELETE操作については、上記の制限は適用されません。
正確な仕様キーを使用して、1つのキーを読み取る（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 | ブート | サーバーを 0.0.0.0 localhost ではなく。 |
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；起動時に有効になる | シリアルポートのスキャン間隔（ミリ秒）。 |
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 | デバイス制御ロックを解除するまでのタイムアウト時間（ミリ秒）。 |
devices/*inverse/query_orientation_on_idle | bool | — | デバイスがアイドル状態のときに、ファームウェアから機体の姿勢情報を取得する。 |
devices/*inverse/safeties/expose_in_snapshot | bool | — | で GET /devices/{id} スナップショットには、各デバイスのセキュリティフラグが含まれています。 |
devices/presets
| キー | タイプ | 制約 | 説明 |
|---|---|---|---|
devices/presets | json | — | 各デバイスタイプのデフォルトのデバイス設定プリセット（インストール変換、basis などを含み、以下に適用されます） 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 | — | グリップを直立させた状態で、grip-hook の自動ロック機能が有効になります。 |
features/grip_hook/use_hall | bool | — | ホールセンサーのしきい値（姿勢ではなく）を用いて、グリップの検出を行う。 |
features/grip_hook/hall | int | 範囲 1～32 | グリップのロックを起動するホールセンサーの値の閾値。 |
features/grip_hook/hold_duration | int | 範囲 10～1000 | トリガー発生後のロック状態の維持時間（ミリ秒）。 |
features/navigation/bubble/…
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 ハブのペアリング画面に対応しています。
| キー | タイプ | 制約 | 説明 |
|---|---|---|---|
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 | — | 各 transform の出力には、常に以下が含まれます position、rotation 和 scale、姿勢情報のみを提供するデバイス（Verse Grip、Wireless Verse Grip）を含め、これらのデバイスは本来、 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 | — | 零次保持（ZOH）ウィンドウ：このウィンドウ内で受信した検出メッセージを抑制する（ms）。 |
rate/websocket/drop_warning_threshold | int | — | 警告が発生する前に、ウィンドウ内で破棄されるコマンドの数。 |
rate/websocket/drop_warning_window_ms | int | — | 破棄されたコマンドの数を集計するためのスライディングウィンドウのサイズ（ms）。 |
rate/websocket/tick_on_empty_batch | bool | 上級 | WebSocketのバッチ全体が破棄された場合でも、1回スケジューリングされる 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 デバッグのためにアクセスできますが、これらは今後のマイナーバージョンで正式な設定に変更されたり、名前が変更されたり、削除されたりする可能性があるため、クライアントの動作をこれらに依存させないでください。