Übersicht über die Einstellungen
Dieses Dokument listet alle Einstellungen auf, die vom Endpunkt /settings/ zurückgegeben werden, mit ihrem Schlüssel, ihrem Typ (aus type_hint) und ihre 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- auf der Einstellungsseite geändert werden, doch Damit die Änderungen wirksam werden, ist ein vollständiger Neustart des Dienstes erforderlich. Diese sind in den folgenden Tabellen mit Start 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 eine einfaches 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 Grundlage-Einstellungen zurück. Geben Sie ?advanced=true, um die als „erweitert“ gekennzeichneten Einstellungen einzubeziehen, und ?deprecated=true, um veraltete Aliase einzubeziehen. Versteckte Einstellungen sind für den internen Gebrauch reserviert; sie werden nur angezeigt, wenn misc/hidden_settings über POST /settings/misc/hidden_settings gesetzt wird (dafür gibt es keinen Query-Parameter). Filter-Flags werden mit UND kombiniert – ein Schlüssel, der sowohl advanced sowie hidden … markiert ist, benötigt beide geöffneten Gates. POST- und DELETE-Anfragen für einen bekannten Schlüssel unterliegen keiner Beschränkung durch ein Gate.
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 Laufzeit des Dienstes erhalten:
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
misc/advanced_settings | bool | — | Als advanced markierte Einstellungen in den GET /settings- „Listen“ einschalten (Standard false). Dies entspricht der Übergabe von ?advanced=true bei jeder Anfrage. |
misc/deprecated_settings | bool | — | Als deprecated markierte Einstellungen in den GET /settings- „Listen“ einschalten (Standard false). Dies entspricht der Übergabe von ?deprecated=true bei jeder Anfrage. |
Typzuordnung
Die von der API zurückgegebenen Typangaben werden in folgende JSON-Strukturen 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 über HTTP und WebSocket gebunden werden. |
communication/bind_all_interfaces | bool | Start | Server und 0.0.0.0 statt an „localhost“ zu binden. |
communication/http/port | int | Start | HTTP-REST-API-Port (Standard 10000). |
communication/websocket/port | int | Start | Hauptport 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 für WebSocket-Event-Streams (Standard 10020). |
devices/…
devices/detection/…
Richtlinie zum Scannen von seriellen Schnittstellen. Alle Einträge sind als „erweitert“ gekennzeichnet.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
devices/detection/scan_period_ms | int | Bereich 100–10.000; beim Start | Intervall zwischen den Abtastungen der seriellen Schnittstellen (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 von 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 | — | Die Gerätebereitschaft blockieren, sobald an einem Port ein Schleifenverhalten erkannt wird. |
devices/detection/excluded_ports | json | — | Pfade serieller Anschlüsse, die bei der Erkennung übersprungen werden. |
devices/detection/additional_ports | string[] | — | Zusätzliche Pfade serieller Schnittstellen, die unabhängig von Bedingungen gescannt werden. |
devices/detection/allowed_vendor_id_filter | string[] | — | USB-Hersteller-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 Version 3.5.0 lautete das Muster devices/inverse*/…; das führende * steht nun vor inverse. Konfigurationsdateien mit der alten Schreibweise werden in Version 3.5.1 nicht mehr korrekt übernommen – bitte passen Sie diese entsprechend an. Die Schlüssel selbst bleiben 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 Kraftabgabe, der auf alle Geräte angewendet wird. |
devices/*inverse/filters/force_gate/gain | float | Bereich 0,0–1,0 | Standardmäßige Verstärkung des Kraft-Gates für neue Sitzungen. |
devices/*inverse/control_timeout_ms | int | Bereich 50–10.000 | Zeitlimit, bevor die Gerätesteuerungssperre aufgehoben wird (ms). |
devices/*inverse/query_orientation_on_idle | bool | — | Die Ausrichtung des Gerätekörpers über die Firmware abfragen, wenn sich das Gerät im Leerlauf befindet. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | Sicherheitsflags pro Gerät in den Snapshots von GET /devices/{id} aufnehmen. |
devices/presets
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
devices/presets | json | — | Standard-Gerätekonfigurations-Voreinstellungen pro 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 bei kritischem Akkustand ein Alarm ausgelöst wird. |
devices/wireless_verse_grip/battery/reset_margin | int | — | Hystereseabstand, bevor eine Akkuwarnung zurückgesetzt wird. |
devices/wireless_verse_grip/filters/orientation_filter | json | beim Start | 1-Euro-Filter-Konfiguration zur 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 eingesteckt gilt. |
features/grip_hook/…
Automatisches „Grip-Hook“-Verhalten – sperrt den Cursor, solange der Griff gedrückt gehalten wird.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Die automatische Grip-Hook-Sperre aktivieren, wenn der Griff aufrecht gehalten wird. |
features/grip_hook/use_hall | bool | — | Verwenden Sie für die Griff-Erkennung den Schwellenwert des Hall-Sensors anstelle der Ausrichtung. |
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 aufrechterhalten 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 Blasenmittelpunkts. |
features/navigation/bubble/center_enabled | bool | — | Den konfigurierten center anwenden, wenn ein Blasenverhalten zum ersten Mal aktiviert wird. |
features/navigation/bubble/rotation_enabled | bool | — | Die Drehung 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 Fahrgeschwindigkeit 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 | — | Die Geschwindigkeit auf null zurücksetzen, wenn der Cursor in die Blase eintritt. |
features/navigation/bubble/spring_inner | float | — | Federkoeffizient am Mittelpunkt der Blase (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 Mittelpunkt der Blase (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 auf der Blasenoberfläche (m). |
features/navigation/bubble/bump_stiffness | float | — | Steifigkeit der taktilen Erhebung auf der Blasenoberfläche (N/m). |
features/navigation/bubble/stop_at_collision | bool | — | Verhindern, dass der Mittelpunkt der Blase bei einer aktiven Kollision in Kollisionsrichtung abdriftet. |
features/navigation/bubble/collision_threshold | float | > 0 | Wert 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 | Intervall (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 Fahrspuren aktivieren. |
features/safe_trajectory/max_vel | float | Bereich 0,01–2,0 | Maximal zulässige Geschwindigkeit des Endeffektors (m/s). |
features/screensaver/…
Leerlaufanimation, die auf Inverse3-Geräten abgespielt wird, wenn keine Sitzung aktiv ist.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
features/screensaver/enabled | bool | — | Die Bildschirmschoner-Animation im Leerlauf 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 | — | Das Modul für haptische SDF-Effekte aktivieren oder deaktivieren. |
features/sdf/state_output | bool | — | Den 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 ausgeübte 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 gesunken 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 Kopplungsflä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 der VerseGrip (kabelgebunden) als angebracht gilt. |
features/verse_grip_pairing/hall_threshold_wvg | int | Bereich 1–32 | Hall-Pegel, ab dem der VerseGrip (kabellos) als angebracht gilt. |
features/verse_grip_pairing/detach_debounce_ms | int | Bereich 0–1000 | Entprellfenster, bevor eine Löschung übernommen wird (ms). |
features/verse_grip_pairing/heartbeat_ms | int | Bereich 100–10.000 | Intervall zwischen erzwungenen erneuten Benachrichtigungen (ms). |
features/verse_grip_pairing/force_attached | bool | — | Den Status „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 Version 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 Standardwert der Identität 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 Ausrichtung erfassen (Verse Grip, Wireless Verse Grip) und ansonsten 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/…
Sitzungsplaner.
| Schlüssel | Typ | Einschränkungen | Beschreibung |
|---|---|---|---|
session/min_simulation_rate_hz | int | Bereich 20–500 | Minimale zulässige Gerätesimulationsrate (Hz), bevor eine Warnung ausgelöst wird. |
rate/…
Service-Taktung. In Abschnitt 3.5.1 eingeführt – die vier unten aufgeführten rate/websocket/*-Die 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 werden eingehende Proben unterdrückt (ms). |
rate/websocket/drop_warning_threshold | int | — | Anzahl der verworfenen Befehle innerhalb des Zeitfensters, bevor eine Warnung ausgegeben 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- Den 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 bestimmt — 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, beispielsweise die Ausgabe von Euler-Quaternionen und das Routing für Wireless VerseGrip). Sie dienen zum Debuggen über misc/hidden_settings verfügbar, aber es ist damit zu rechnen, dass sie in einer späteren Minor-Version übertragen, umbenannt oder entfernt werden – machen Sie das Verhalten Ihres Clients nicht davon abhängig.