Referenz der Einstellungen

Dieses Dokument listet alle Einstellungen auf, die der Endpunkt /settings/ zurückgibt, 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 nur lesbar. Sie kann über die Konfigurationsdatei oder über die Einstellungsseite von Haply Hub geändert werden, doch damit Änderungen wirksam werden, ist ein vollständiger Neustart des Dienstes erforderlich. Diese Einstellungen sind in den Tabellen unten mit boot gekennzeichnet.

Konfiguration

Die Konfigurationsdatei, mit der die Einstellungen beim Start des Dienstes ü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 /settings/ HTTP-Route zurückgegeben werden (siehe API-Referenz). Nicht angegebene Schlüssel verwenden den Standardwert des Dienstes.

Zum Beispiel eine Überschreibung der Netzwerkkonfiguration:

{
  "communication/http/port": 8400,
  "communication/websocket/port": 8500,
  "communication/events/port": 9000,
  "communication/bind_all_interfaces": true
}

Typzuordnung

Die von der API zurückgegebenen Typhinweise entsprechen folgenden JSON-Typen:

STRING → string
BOOL → bool
INT → int
FLOAT → float
ARR_STRING → string[]
VEC3 → vec3 (Objekt mit {x, y, z})
GENERIC → json (beliebiger strukturierter Wert)

`communication/…`

Netzwerk-Ports und Bind-Adressen für die HTTP-, WebSocket- und Event-Stream-Server. Die meisten Einträge sind nur beim Booten (boot) wirksam.

Schlüssel	Typ	Einschränkungen	Beschreibung
`communication/serial/enabled`	`bool`	—	Serielle Gerätekommunikation aktivieren oder deaktivieren.
`communication/bind_address`	`string`	boot	IP-Adresse, an die die HTTP- und WebSocket-Server gebunden werden.
`communication/bind_all_interfaces`	`bool`	boot	Server an `0.0.0.0` statt an localhost binden.
`communication/http/port`	`int`	boot	Port der HTTP-REST-API (Standard: `10000`).
`communication/websocket/port`	`int`	boot	Hauptport für WebSocket v3.1 (Standard: `10001`).
`communication/websocket/legacy_port`	`int`	boot	Legacy-Port für WebSocket v3.0 (Standard: `10000`).
`communication/events/port`	`int`	boot	Port für den WebSocket-Event-Stream (Standard: `10020`).

`devices/…`

`devices/detection/…`

Richtlinie für das Scannen serieller Ports. Alle Einträge sind fortgeschrittene Einstellungen.

Schlüssel	Typ	Einschränkungen	Beschreibung
`devices/detection/scan_period_ms`	`int`	Bereich 100–10000; boot	Intervall zwischen den Scans serieller 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-Wiederholungen 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, wenn ein Looping-Port 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 immer 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, nach denen gefiltert wird.
`devices/detection/wireless_verse_grip_description_filter`	`string[]`	—	Teilzeichenfolgen der Port-Beschreibung für die Erkennung von Wireless-VerseGrip.
`devices/detection/inverse3x_description_filter`	`string[]`	—	Teilzeichenfolgen der Port-Beschreibung für die Erkennung von Inverse3x.
`devices/detection/extra_ports` (veraltet)	`string[]`	—	Stattdessen `devices/detection/additional_ports` verwenden. Lese- und Schreibzugriffe werden transparent an den kanonischen Schlüssel weitergeleitet.

`devices/inverse*/…`

Globale Standardwerte, die auf alle Geräte der Inverse3-Familie angewendet werden. Sitzungsspezifische Überschreibungen haben Vorrang.

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, nach dem die Sperre der Gerätesteuerung freigegeben wird (ms).
`devices/inverse*/query_orientation_on_idle`	`bool`	—	Körperausrichtung des Geräts im Leerlauf von der Firmware abfragen.

`devices/presets`

Schlüssel	Typ	Einschränkungen	Beschreibung
`devices/presets`	`json`	—	Standardgerätekonfigurationen je Gerätetyp (Montagetransformation, 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-Spielraum, bevor eine Akkuwarnung zurückgesetzt wird.
`devices/wireless_verse_grip/filters/orientation_filter`	`json`	boot	Konfiguration des One-Euro-Filters 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 Verhalten des Grip-Hooks – sperrt den Cursor, solange der Griff aufrecht gehalten wird.

Schlüssel	Typ	Einschränkungen	Beschreibung
`features/grip_hook/enabled`	`bool`	—	Automatische Sperre des Grip-Hooks 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 Griffsperre 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, sobald ein bubble-Verhalten erstmals aktiviert wird.

Schlüssel	Typ	Einschränkungen	Beschreibung
`features/navigation/bubble/center`	`vec3`	—	Standardposition des Bubble-Mittelpunkts.
`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 Bubble-Oberfläche (m).
`features/navigation/bubble/reset_velocity_on_entry`	`bool`	—	Geschwindigkeit auf null zurücksetzen, wenn der Cursor in die Bubble eintritt.
`features/navigation/bubble/spring_inner`	`float`	—	Federkoeffizient am Bubble-Mittelpunkt (N/m).
`features/navigation/bubble/spring_surface`	`float`	—	Federkoeffizient an der Bubble-Oberflä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 Bubble-Mittelpunkt (Ns/m).
`features/navigation/bubble/damping_surface`	`float`	—	Dämpfungskoeffizient an der Bubble-Oberflä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 Bubble-Oberfläche (m).
`features/navigation/bubble/bump_stiffness`	`float`	—	Steifigkeit der taktilen Erhebung an der Bubble-Oberfläche (N/m).

`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 Geschwindigkeit des Endeffektors (m/s).

`features/screensaver/…`

Im Leerlauf abgespielte Animation auf Inverse3-Geräten, wenn keine Sitzung sie steuert.

Schlüssel	Typ	Einschränkungen	Beschreibung
`features/screensaver/enabled`	`bool`	—	Die Leerlauf-Bildschirmschoner-Animation auf Inverse3-Geräten aktivieren.
`features/screensaver/speed`	`float`	Bereich 0.001–0.2	Geschwindigkeit der Bildschirmschoner-Animation.
`features/screensaver/distracted_speed`	`float`	Bereich 0.001–0.2	Animationsgeschwindigkeit, wenn sich der Benutzer in der Nähe befindet, 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`	—	Aktiviert oder deaktiviert das Modul für SDF-Haptikeffekte.
`features/sdf/state_output`	`bool`	—	Schließt den SDF-Status standardmäßig in die Ausgabe-Payloads des Geräts ein.
`features/sdf/max_count`	`int`	Bereich 0–128	Maximale Anzahl aktiver SDF-Effekte (`0` = unbegrenzt).
`features/sdf/events/created`	`bool`	—	Gibt ein Ereignis aus, wenn ein neuer SDF-Effekt erstellt wird.
`features/sdf/events/deleted`	`bool`	—	Gibt ein Ereignis aus, wenn ein SDF-Effekt gelöscht wird.
`features/sdf/events/updated`	`bool`	—	Gibt ein Ereignis aus, wenn ein SDF-Effekt aktualisiert wird.
`features/sdf/probe_on_zero_force/enabled`	`bool`	—	SDF-Felder automatisch abfragen, wenn die aufgebrachte Kraft nahe null liegt.
`features/sdf/probe_on_zero_force/delay`	`float`	Bereich 0.001–60.0	Verzögerung vor der automatischen Abfrage, nachdem die Kraft auf null gesunken ist (s).

`features/verse_grip_pairing/…`

Erfassung von Anschluss und Trennung zwischen einem Inverse3 und einem Verse Grip (kabelgebunden oder kabellos). Grundlage der Kopplungs-Oberfläche von Haply Hub.

Schlüssel	Typ	Einschränkungen	Beschreibung
`features/verse_grip_pairing/enabled`	`bool`	—	Aktiviert die Kopplung bzw. die Erfassung von Anschluss und Trennung.
`features/verse_grip_pairing/hall_threshold_vg`	`int`	Bereich 1–32	Hall-Pegel, ab dem ein kabelgebundenes VerseGrip als angeschlossen gilt.
`features/verse_grip_pairing/hall_threshold_wvg`	`int`	Bereich 1–32	Hall-Pegel, ab dem ein kabelloses VerseGrip als angeschlossen gilt.
`features/verse_grip_pairing/detach_debounce_ms`	`int`	Bereich 0–1000	Entprellzeitfenster, bevor eine Trennung ü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`	—	Erzwingt dauerhaft den Zustand „angeschlossen“ (`true`) und umgeht den Hall-Sensor (Workaround bei Hardwarefehlern).

`serialization/…`

Formatierung der Transformationsausgabe – betrifft die Payloads von WebSocket und HTTP JSON.

Schlüssel	Typ	Einschränkungen	Beschreibung
`serialization/explicit_fields`	`bool`	—	Schließt Transformationsfelder, die ihrem Identitäts-Standardwert entsprechen, in die serialisierte Ausgabe ein (z. B. `position: {0,0,0}`, `rotation: {w:1,…}`). Nützlich, wenn Ihr Client verlangt, dass alle Felder explizit vorhanden sind. Standard: `false`.
`serialization/force_complete_transforms`	`bool`	—	Gibt in jeder Transformationsausgabe immer `position`, `rotation` und `scale` aus, auch bei Geräten, die nur die Orientierung erfassen (Verse Grip, Wireless Verse Grip) und ansonsten nur `rotation` ausgeben. Umfasst `serialization/explicit_fields`. Standard: `false`.

`session/…`

Grenzwerte für den Session-Scheduler und die Befehlspipeline.

Schlüssel	Typ	Einschränkungen	Beschreibung
`session/min_simulation_rate_hz`	`int`	Bereich 20–500	Minimal akzeptable Simulationsrate des Geräts (Hz); bei Unterschreitung wird eine Warnung ausgegeben.
`session/commands/zoh_window_ms`	`int`	—	Zero-Order-Hold-Fenster – unterdrückt Abfragen, die innerhalb dieses Fensters eingehen (ms).
`session/commands/drop_warning_threshold`	`int`	—	Anzahl verworfener Befehle innerhalb des Fensters, ab der gewarnt wird.
`session/commands/drop_warning_window_ms`	`int`	—	Größe des gleitenden Fensters zum Zählen verworfener Befehle (ms).
`session/commands/tick_on_empty_batch`	`bool`	—	Plant einen `main_loop`-Tick auch dann ein, wenn ein gesamter WebSocket-Batch verworfen wurde.

Konfiguration​

Typzuordnung​

communication/…​

devices/…​

devices/detection/…​

devices/inverse*/…​

devices/presets​

devices/wireless_verse_grip/…​

features/…​

features/calibration/…​

features/grip_hook/…​

features/navigation/bubble/…​

features/safe_trajectory/…​

features/screensaver/…​

features/sdf/…​

features/verse_grip_pairing/…​

serialization/…​

session/…​