設定リファレンス
このドキュメントでは、/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
}
型のマッピング
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; boot | シリアルポートのスキャン間隔（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 系デバイスに適用されるグローバルなデフォルト設定です。セッションごとの上書き設定が優先されます。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
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/presets
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
devices/presets | json | — | デバイスタイプごとのデフォルトのデバイス構成プリセット（inverse_arm_front_*、inverse_led_front_*、minverse_*、verse_grip_default、wireless_verse_grip_default、custom_verse_grip_default 向けのマウント変換や basis など）。 |
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 | boot | ワイヤレス 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/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/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 Hub のペアリング 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 に固定します（ハードウェア故障時の回避策）。 |
serialization/…
トランスフォーム出力のフォーマット設定です。WebSocket と HTTP JSON のペイロードに影響します。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
serialization/explicit_fields | bool | — | シリアライズ済み出力に、単位元（identity）のデフォルト値と等しいトランスフォームフィールドを含めます（例: position: {0,0,0}、rotation: {w:1,…}）。クライアントがすべてのフィールドの明示的な指定を要求する場合に有用です。デフォルト: false。 |
serialization/force_complete_transforms | bool | — | 向きのみを扱うデバイス（Verse Grip、Wireless Verse Grip）を含め、すべてのトランスフォーム出力で position、rotation、および scale を常に出力します。通常は rotation のみを出力するデバイスも対象です。serialization/explicit_fields の機能を包含します。デフォルト: false。 |
session/…
セッションスケジューラーとコマンドパイプラインの上限値です。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 範囲 20–500 | 警告が発生するまでに許容されるデバイスのシミュレーションレートの下限（Hz）です。 |
session/commands/zoh_window_ms | int | — | ゼロ次ホールド・ウィンドウです。このウィンドウ内に受信したプローブを抑制します（ms）。 |
session/commands/drop_warning_threshold | int | — | 警告が発生するまでに、ウィンドウ内で破棄されたコマンドの数です。 |
session/commands/drop_warning_window_ms | int | — | 破棄されたコマンドを数えるためのスライディングウィンドウのサイズです（ms）。 |
session/commands/tick_on_empty_batch | bool | — | WebSocket のバッチ全体が破棄された場合でも、main_loop のティックをスケジュールします。 |