設定リファレンス
このドキュメントでは、/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
}
型のマッピング
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/…
シリアルポートのスキャンポリシーです。すべての項目は詳細設定です。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
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 系デバイスに適用されるグローバルなデフォルト設定です。セッションごとの上書き設定が優先されます。
| キー | 型 | 制約 | 説明 |
|---|---|---|---|
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 | ブート | ワイヤレス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 ハブのペアリング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 のティックをスケジュールします。 |