Referenz der Einstellungen
Dieses Dokument listet alle Einstellungen auf, die vom Endpunkt /settings/ zurückgegeben werden, mit ihrem Schlüssel, ihrem Typ (aus type_hint) und ihren Einschränkungen (aus metadata.constraint.range + locked, sofern zutreffend).
Eine locked-Einstellung ist zur Laufzeit schreibgeschützt. Sie kann über die Konfigurationsdatei oder über die Haply Hub-Einstellungsseite geändert werden, doch damit Änderungen wirksam werden, ist ein vollständiger Neustart des Dienstes erforderlich. Diese sind in den folgenden Tabellen mit boot gekennzeichnet.
Konfiguration
Die Konfigurationsdatei, mit der die Einstellungen beim Dienststart überschrieben werden, befindet sich hier:
| Plattform | Speicherort |
|---|---|
| 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 |
Die Konfigurationsdatei ist ein flaches JSON-Objekt, das Einstellungsschlüssel auf Überschreibungswerte abbildet. Schlüssel müssen gültige Einstellungsschlüssel sein, die von der HTTP-Route /settings/ zurückgegeben werden (siehe API-Referenz). Für jeden nicht angegebenen Schlüssel wird der Standardwert des Dienstes verwendet.
Zum Beispiel eine Überschreibung der Netzwerkkonfiguration:
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
Sichtbarkeit und Filterung
Die Listen-Endpunkte /settings (GET /settings, GET /settings/) liefern standardmäßig nur Basis-Einstellungen zurück. Übergeben Sie ?advanced=true, um als advanced markierte Einstellungen einzuschließen, und ?deprecated=true, um veraltete Aliase einzuschließen. Versteckte Einstellungen sind für die interne Verwendung reserviert; sie erscheinen nur, wenn misc/hidden_settings über POST /settings/misc/hidden_settings gesetzt wird (es gibt dafür keinen Query-Parameter). Filter-Flags werden mit UND kombiniert — ein Schlüssel, der sowohl advanced als auch hidden markiert ist, benötigt beide geöffneten Gates. POST und DELETE auf einen bekannten Schlüssel sind nicht durch ein Gate eingeschränkt.
Lesezugriffe auf einzelne Schlüssel (GET /settings/<key>) umgehen das Advanced-/Deprecated-Gate, wenn Sie den exakten kanonischen Schlüssel verwenden — nützlich für Clients mit Vorwissen. Versteckte Schlüssel bleiben weiterhin gesperrt.
Drei Laufzeitschalter initialisieren die Gates; ihre Werte bleiben für die gesamte Lebensdauer des Dienstes erhalten:
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
misc/advanced_settings | bool | — | Als advanced markierte Einstellungen in den GET /settings-Listen einschließen (Standard false). Entspricht der Übergabe von ?advanced=true bei jeder Anfrage. |
misc/deprecated_settings | bool | — | Als deprecated markierte Einstellungen in den GET /settings-Listen einschließen (Standard false). Entspricht der Übergabe von ?deprecated=true bei jeder Anfrage. |
Typzuordnung
Die von der API zurückgegebenen Typhinweise werden in diese Strukturen von JSON abgebildet:
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3(Objekt mit{x, y, z})GENERIC→json(beliebiger strukturierter Wert)
communication/…
Netzwerkports und Bind-Adressen für die Server HTTP, WebSocket und Event-Stream. Die meisten Einträge werden nur beim Start übernommen.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
communication/serial/enabled | bool | — | Serielle Gerätekommunikation aktivieren oder deaktivieren. |
communication/bind_address | string | Start | IP-Adresse, an die die Server HTTP und WebSocket gebunden werden. |
communication/bind_all_interfaces | bool | Start | Server an 0.0.0.0 statt an localhost binden. |
communication/http/port | int | Start | HTTP-REST-API-Port (Standard 10000). |
communication/websocket/port | int | Start | Haupt-Port von WebSocket v3.1 (Standard 10001). |
communication/websocket/legacy_port | int | Start | Legacy-Port von WebSocket v3.0 (Standard 10000). |
communication/events/port | int | Start | Port des Event-Streams WebSocket (Standard 10020). |
devices/…
devices/detection/…
Richtlinie für das Scannen serieller Ports. Alle Einträge sind als erweitert markiert.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
devices/detection/scan_period_ms | int | Bereich 100–10000; beim Start | Intervall zwischen den Scans der seriellen Ports (ms). |
devices/detection/handshake_timeout_s | int | Bereich 1–15 | Handshake-Timeout pro Port (s). |
devices/detection/max_retries | int | Bereich 1–10 | Maximale Anzahl an Handshake-Wiederholungsversuchen pro Port. |
devices/detection/failure_log_delay_s | int | Bereich 1–60 | Verzögerung, bevor ein Erkennungsfehler erneut protokolliert wird (s). |
devices/detection/block_looping_ports | bool | — | Gerätebereitschaft blockieren, sobald ein Port mit Schleifenverhalten erkannt wird. |
devices/detection/excluded_ports | json | — | Pfade serieller Ports, die bei der Erkennung übersprungen werden. |
devices/detection/additional_ports | string[] | — | Zusätzliche Pfade serieller Ports, die unabhängig von Bedingungen gescannt werden. |
devices/detection/allowed_vendor_id_filter | string[] | — | USB-Vendor-IDs, die bei der Port-Aufzählung zugelassen sind. |
devices/detection/port_name_substring_filter | string[] | — | Plattformspezifische Teilzeichenfolgen von Portnamen zum Abgleich. |
devices/detection/wireless_verse_grip_description_filter | string[] | — | Teilzeichenfolgen der Portbeschreibung zur Erkennung von wireless VerseGrip. |
devices/detection/inverse3x_description_filter | string[] | — | Teilzeichenfolgen der Portbeschreibung zur Erkennung von Inverse3x. |
devices/detection/extra_ports (veraltet) | string[] | — | Verwenden Sie stattdessen devices/detection/additional_ports. Lese- und Schreibzugriffe werden transparent an den kanonischen Schlüssel weitergeleitet. |
devices/*inverse/…
Globale Standardwerte, die auf jedes Gerät der Inverse3-Familie angewendet werden. Sitzungsspezifische Überschreibungen haben Vorrang.
In 3.5.0 lautete das Muster devices/inverse*/…; das führende * steht nun vor inverse. Konfigurationsdateien mit der alten Schreibweise werden in 3.5.1 nicht mehr korrekt übernommen – bitte passen Sie sie an. Die Schlüssel selbst sind ansonsten unverändert.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | Bereich 0.0–2.0 | Globaler Multiplikator für die Kraftausgabe, der auf alle Geräte angewendet wird. |
devices/*inverse/filters/force_gate/gain | float | Bereich 0.0–1.0 | Standardverstärkung des Kraft-Gates für neue Sitzungen. |
devices/*inverse/control_timeout_ms | int | Bereich 50–10000 | Timeout, bevor die Gerätesteuerungssperre freigegeben wird (ms). |
devices/*inverse/query_orientation_on_idle | bool | — | Ausrichtung des Gerätekörpers aus der Firmware abfragen, wenn das Gerät im Leerlauf ist. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | Sicherheitsflags pro Gerät in die Snapshots von GET /devices/{id} aufnehmen. |
devices/presets
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
devices/presets | json | — | Standard-Gerätekonfigurations-Voreinstellungen pro Gerätetyp (Montage-Transformation, Basis usw. für inverse_arm_front_*, inverse_led_front_*, minverse_*, verse_grip_default, wireless_verse_grip_default, custom_verse_grip_default). |
devices/wireless_verse_grip/…
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | Akkustand in Prozent, unterhalb dessen eine Warnung bei niedrigem Akkustand ausgelöst wird. |
devices/wireless_verse_grip/battery/critical_threshold | int | — | Akkustand in Prozent, unterhalb dessen ein Alarm bei kritischem Akkustand ausgelöst wird. |
devices/wireless_verse_grip/battery/reset_margin | int | — | Hysterese-Abstand, bevor eine Akkuwarnung zurückgesetzt wird. |
devices/wireless_verse_grip/filters/orientation_filter | json | beim Start | One-Euro-Filter-Konfiguration für die Ausrichtung des wireless VerseGrip. |
features/…
features/calibration/…
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/calibration/hall_threshold | int | Bereich 1–32 | Hall-Sensor-Pegel, ab dem der Stift bei der Kalibrierung als angesteckt gilt. |
features/grip_hook/…
Automatisches Grip-Hook-Verhalten — sperrt den Cursor, solange der Griff aufrecht gehalten wird.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Automatische Grip-Hook-Sperre aktivieren, wenn der Griff aufrecht gehalten wird. |
features/grip_hook/use_hall | bool | — | Für die Griff-Erkennung den Hall-Sensor-Schwellenwert statt der Ausrichtung verwenden. |
features/grip_hook/hall | int | Bereich 1–32 | Hall-Sensor-Schwellenwert, der die Grip-Sperre auslöst. |
features/grip_hook/hold_duration | int | Bereich 10–1000 | Dauer, für die die Sperre nach dem Auslösen gehalten wird (ms). |
features/navigation/bubble/…
Standardwerte des Bubble-Navigationsmoduls — werden an die Sitzung übergeben, wenn ein bubble-Verhalten erstmals aktiviert wird. Die Laufzeitsemantik der einzelnen Felder finden Sie auf der Seite Navigationsmodul.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | Standardmäßige Position des Mittelpunkts der Blase. |
features/navigation/bubble/center_enabled | bool | — | Den konfigurierten center anwenden, wenn ein Blasenverhalten erstmals aktiviert wird. |
features/navigation/bubble/rotation_enabled | bool | — | Die Rotation des Arbeitsraums auf die Navigationsrichtung anwenden. |
features/navigation/bubble/scale_enabled | bool | — | Den Maßstab des Arbeitsraums auf die Navigationsgeschwindigkeit anwenden. |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | Driftgeschwindigkeit (m/s) im Mittelpunktmodus auto_follow. |
features/navigation/bubble/max_velocity | float | — | Maximale Navigationsgeschwindigkeit in der Geschwindigkeitszone (m/s). |
features/navigation/bubble/velocity_zone_width | float | — | Breite der Geschwindigkeitszone außerhalb der Blasenoberfläche (m). |
features/navigation/bubble/reset_velocity_on_entry | bool | — | Geschwindigkeit auf null zurücksetzen, wenn der Cursor in die Blase eintritt. |
features/navigation/bubble/spring_inner | float | — | Federkoeffizient am Blasenmittelpunkt (N/m). |
features/navigation/bubble/spring_surface | float | — | Federkoeffizient an der Blasenoberfläche (N/m). |
features/navigation/bubble/spring_outer | float | — | Federkoeffizient an der äußeren Grenze (N/m). |
features/navigation/bubble/damping_inner | float | — | Dämpfungskoeffizient am Blasenmittelpunkt (Ns/m). |
features/navigation/bubble/damping_surface | float | — | Dämpfungskoeffizient an der Blasenoberfläche (Ns/m). |
features/navigation/bubble/damping_outer | float | — | Dämpfungskoeffizient an der äußeren Grenze (Ns/m). |
features/navigation/bubble/wall_stiffness | float | — | Steifigkeit der harten Wand an der äußeren Grenze (N/m). |
features/navigation/bubble/bump_width | float | — | Breite der taktilen Erhebung an der Blasenoberfläche (m). |
features/navigation/bubble/bump_stiffness | float | — | Steifigkeit der taktilen Erhebung an der Blasenoberfläche (N/m). |
features/navigation/bubble/stop_at_collision | bool | — | Verhindern, dass der Blasenmittelpunkt bei aktiver Kollision in Kollisionsrichtung driftet. |
features/navigation/bubble/collision_threshold | float | > 0 | Betrag der äußeren Kraft (N), bei dem eine Kollision erkannt wird. |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | Multiplikator, der während einer aktiven Kollision auf velocity_zone_width angewendet wird. |
features/navigation/bubble/collision_exit_ratio | float | Bereich (0,1] | Hysterese-Verhältnis – Kollision verlassen, wenn |ext_force| unter collision_threshold × this fällt. 1.0 deaktiviert die Hysterese. |
features/navigation/bubble/avatar_boundary_enabled | bool | — | Die Weltposition des Avatars auf die konfigurierte SDF-Form avatar_boundary begrenzen. |
features/safe_trajectory/…
Geschwindigkeitsbegrenzer für die Bewegung des Endeffektors.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | Den Geschwindigkeitsbegrenzer für sichere Trajektorien aktivieren. |
features/safe_trajectory/max_vel | float | Bereich 0.01–2.0 | Maximal zulässige Endeffektor-Geschwindigkeit (m/s). |
features/screensaver/…
Leerlaufanimation, die auf Inverse3-Geräten abgespielt wird, wenn keine Sitzung sie steuert.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/screensaver/enabled | bool | — | Die Leerlauf-Bildschirmschoneranimation auf Inverse3-Geräten aktivieren. |
features/screensaver/speed | float | Bereich 0.001–0.2 | Geschwindigkeit der Bildschirmschoneranimation. |
features/screensaver/distracted_speed | float | Bereich 0.001–0.2 | Animationsgeschwindigkeit, wenn sich der Benutzer in der Nähe aufhält, aber nicht interagiert. |
features/sdf/…
Modul für haptische Effekte auf Basis von Signed-Distance-Fields (SDF HFX).
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/sdf/enabled | bool | — | Das Modul für haptische SDF-Effekte aktivieren oder deaktivieren. |
features/sdf/state_output | bool | — | SDF-Zustand standardmäßig in die Ausgabedaten des Geräts aufnehmen. |
features/sdf/max_count | int | Bereich 0–128 | Maximale Anzahl aktiver SDF-Effekte (0 = unbegrenzt). |
features/sdf/events/created | bool | — | Ein Ereignis auslösen, wenn ein neuer SDF-Effekt erstellt wird. |
features/sdf/events/deleted | bool | — | Ein Ereignis auslösen, wenn ein SDF-Effekt gelöscht wird. |
features/sdf/events/updated | bool | — | Ein Ereignis auslösen, wenn ein SDF-Effekt aktualisiert wird. |
features/sdf/probe_on_zero_force/enabled | bool | — | SDF-Felder automatisch abtasten, wenn die aufgebrachte Kraft nahe null liegt. |
features/sdf/probe_on_zero_force/delay | float | Bereich 0.001–60.0 | Verzögerung vor dem automatischen Abtasten, nachdem die Kraft auf null gefallen ist (s). |
features/verse_grip_pairing/…
Erfassung des Anbringens und Lösens zwischen Inverse3 und einem (kabelgebundenen oder kabellosen) Verse Grip. Grundlage für die Kopplungs-Oberfläche von Haply Hub.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | Kopplung und Erfassung des Anbringens und Lösens aktivieren. |
features/verse_grip_pairing/hall_threshold_vg | int | Bereich 1–32 | Hall-Pegel, ab dem VerseGrip (kabelgebunden) als angebracht gilt. |
features/verse_grip_pairing/hall_threshold_wvg | int | Bereich 1–32 | Hall-Pegel, ab dem VerseGrip (kabellos) als angebracht gilt. |
features/verse_grip_pairing/detach_debounce_ms | int | Bereich 0–1000 | Entprellfenster, bevor ein Lösen übernommen wird (ms). |
features/verse_grip_pairing/heartbeat_ms | int | Bereich 100–10000 | Intervall zwischen erzwungenen erneuten Benachrichtigungen (ms). |
features/verse_grip_pairing/force_attached | bool | — | Den Zustand „angebracht“ dauerhaft auf true setzen und den Hall-Sensor umgehen (Workaround bei Hardwarefehlern). |
session/serialization/…
Formatierung der Transform-Ausgabe — betrifft die Payloads von WebSocket und HTTP JSON. Diese Schlüssel wurden in 3.5.1 von serialization/* nach session/serialization/* verschoben, um ihren sitzungsbezogenen Geltungsbereich widerzuspiegeln. Die alten Pfade werden weiterhin über veraltete Aliase aufgelöst.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | Transform-Felder, die dem Identitäts-Standardwert entsprechen, in die serialisierte Ausgabe aufnehmen (z. B. position: {0,0,0}, rotation: {w:1,…}). Nützlich, wenn Ihr Client verlangt, dass jedes Feld explizit vorhanden ist. Standard: false. |
session/serialization/force_complete_transforms | bool | — | Immer position, rotation und scale in jeder Transform-Ausgabe ausgeben, auch bei Geräten, die nur die Orientierung erfassen (Verse Grip, Wireless Verse Grip) und sonst nur rotation ausgeben. Schließt session/serialization/explicit_fields ein. Standard: false. |
serialization/explicit_fields (veraltet) | bool | — | Verwenden Sie stattdessen session/serialization/explicit_fields. Lese- und Schreibzugriffe werden transparent an den kanonischen Schlüssel weitergeleitet. |
serialization/force_complete_transforms (veraltet) | bool | — | Verwenden Sie stattdessen session/serialization/force_complete_transforms. Lese- und Schreibzugriffe werden transparent an den kanonischen Schlüssel weitergeleitet. |
session/…
Session-Scheduler.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
session/min_simulation_rate_hz | int | Bereich 20–500 | Minimale akzeptable Geräte-Simulationsrate (Hz), bevor eine Warnung ausgelöst wird. |
rate/…
Service-Taktung. In 3.5.1 eingeführt — die vier unten aufgeführten rate/websocket/*-Schlüssel befanden sich zuvor unter session/commands/*; die alten Pfade werden weiterhin über veraltete Aliase aufgelöst.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | Zero-Order-Hold-Fenster — innerhalb dieses Fensters eingehende Probes werden unterdrückt (ms). |
rate/websocket/drop_warning_threshold | int | — | Anzahl verworfener Befehle innerhalb des Fensters, bevor gewarnt wird. |
rate/websocket/drop_warning_window_ms | int | — | Größe des gleitenden Fensters zur Zählung verworfener Befehle (ms). |
rate/websocket/tick_on_empty_batch | bool | fortgeschritten | Einen main_loop-Tick einplanen, auch wenn ein gesamter WebSocket-Batch verworfen wurde. |
session/commands/zoh_window_ms (veraltet) | int | — | Verwenden Sie stattdessen rate/websocket/zoh_window_ms. Lese- und Schreibzugriffe werden transparent weitergeleitet. |
session/commands/drop_warning_threshold (veraltet) | int | — | Verwenden Sie stattdessen rate/websocket/drop_warning_threshold. Lese- und Schreibzugriffe werden transparent weitergeleitet. |
session/commands/drop_warning_window_ms (veraltet) | int | — | Verwenden Sie stattdessen rate/websocket/drop_warning_window_ms. Lese- und Schreibzugriffe werden transparent weitergeleitet. |
session/commands/tick_on_empty_batch (veraltet) | bool | — | Verwenden Sie stattdessen rate/websocket/tick_on_empty_batch. Lese- und Schreibzugriffe werden transparent weitergeleitet. |
Nur intern verwendete Einstellungen
In 3.5.1 werden mehrere Einstellungsgruppen als hidden ausgeliefert und sind für den internen Gebrauch reserviert — rate/dispatch/* (AIMD-Obergrenze für die Dispatch-Rate und Backpressure-Schwellenwerte), session/freeform/* (Verhaltens-Fingerprinting) und session/serialization/preview/* (Serialisierungsexperimente vor der Veröffentlichung, etwa die Ausgabe von Euler-Quaternionen und das Routing für Wireless VerseGrip). Sie sind zum Debuggen über misc/hidden_settings erreichbar, aber es ist damit zu rechnen, dass sie in einer späteren Minor-Version überführt, umbenannt oder entfernt werden — machen Sie das Verhalten Ihres Clients nicht von ihnen abhängig.