v3.5.0

Dies ist unsere bisher umfangreichste Version seit der API-Überarbeitung vor einem Jahr. 3.5.0 führt eine einheitliche 3D-Mathematikschicht, vollständige Unterstützung für Minverse, einen typisierten Ereignisstrom, eine vollständige Settings-API und eine übersichtlichere HTTP-Schnittstelle ein – dazu ein Jahr voller Fehlerbehebungen und Verbesserungen der Bedienbarkeit.

Highlights

• Einheitliche 3D-Mathematikschicht – eine kombinierbare Transformationspipeline mit vollwertigen Primitiven für Geräte-Basis (Frame), Mount-Transformation, Workspace-Transformation und Navigations-Transformation sowie explizite Umrechnungen zwischen lokalem Raum, Session-Raum, Anwendungsraum und internem Raum.
• Bubble Navigation – Navigation in großen virtuellen Arbeitsbereichen über geformte Zonen (SDF-Primitive) mit geschwindigkeitsabhängiger Ratensteuerung, hysteresebewusster Kollisionserkennung und optionalem Driften zum Cursor. Vollständig konfigurierbar über HTTP und WebSocket mit Round-Trip über den App-Space.
• Typisierter Ereignisstrom – ein eigener WebSocket-Ereigniskanal für den Lebenszyklus der Geräte, Sicherheitswarnungen, Kalibrierung, Akkustatus, Warnungen zur Regelrate und Hinweise auf veraltete Funktionen.
• Settings-API – ein vollständiges Key-Value-Einstellungssystem mit HTTP-CRUD, Typhinweisen, Bereichsbeschränkungen und Beschreibungen, das die bisherige verschachtelte Konfigurationsdatei ersetzt.
• Einheitliche Gerätekonfiguration – ein gemeinsamer Satz von HTTP-Routen für jedes Gerät: basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
• Synchronisierte Minverse- und Stift-Kalibrierung – Gerät und Stift werden nun gemeinsam kalibriert; die Kalibrierung bleibt gesperrt, bis ein Griff physisch angebracht ist.
• Komfortverbesserungen für HTTP – indexbasierte Geräteselektoren (ein Gerät über seinen Index ansprechen, keine ID nötig), eine einheitliche Anfrage-/Antwortstruktur, die mit WebSocket geteilt wird, ein optional aktivierbares {ok, error, data}-Envelope (?format=json) und Wildcard-Session-Selektoren.

Neue Funktionen

Geräte

• Minverse – offizielle Unterstützung in dieser Version: Erkennung, Bereitschaftsablauf, Sicherheitsbenachrichtigungen und der synchronisierte Kalibrierungsablauf.
• Ruko und Kingfisher werden nun als offizielle Griff-Produkttypen erkannt.
• Unterstützung für Gerätesimulatoren – softwaresimulierte Geräte lassen sich neben echter Hardware erkennen und ansprechen.
• Schutz vor Verbindungsschleifen – fehlerhafte Ports werden automatisch blockiert; zurückgesetzt werden sie mit POST /ports/{port}/reset.
• Heartbeat für die Stifterkennung – zuverlässige Erkennung, wann ein Griff angebracht oder abgenommen wird, mit Entprellung.

Sessions, Befehle und WebSocket

• Filterung und Persistenz von Session-Profilen – Sessions geben einen Profilnamen und die erforderliche SDK-Version an; der Dienst merkt sich beides über Wiederverbindungen hinweg. Clients und Überwachungstools können Sessions anhand dieses Profils filtern und gezielt ansprechen.
• Befehlspuffer pro Session – eine langsame Session kann andere nicht mehr ausbremsen.
• Explizite configure-Map für Einmalbefehle – basis, preset, mount, force_gate, damping pro Gerät sowie profile und basis pro Session werden nun alle in configure übergeben und sind auf die Ausgabe-Konfigurations-Map abgestimmt, sodass das Gesendete mit dem Zurückgelesenen übereinstimmt.
• Anpassbarer Geräte-Mount – wählen Sie ein integriertes Workspace-Preset (defaults, arm_front, arm_front_centered, led_front, led_front_centered) oder senden Sie eine explizite Transformation; manuelle Mount-Änderungen setzen das Preset automatisch auf custom.
• Benannte Befehlsfelder – position, vector, angles, torques ersetzen das generische Array values.
• set_angular_torques ersetzt set_angular_torque (die Singularform ist veraltet).
• Erweiterungen des Session-Frames – Die Session-Frames der Versionen v3.0 und v3.1 enthalten nun erweiterbare config-, state- und status-Objekte; neue Ausgabefelder umfassen current_cursor_force, current_cursor_position, current_angular_torques, current_angular_position, control_domain, control_mode, transform, transform_velocity, ausführlichere config.*-Felder und status.safety (standardmäßig ausgeblendet).
• Partielle Transformations-Updates – senden Sie nur die Unterfelder, die Sie ändern möchten (position, rotation, scale), für Mount, Workspace-Transformation und Navigationsform.

HTTP

• GET / – Dienstversion.
• GET/POST/DELETE /settings und /settings/* – vollständige Settings-API für Key-Value-Paare.
• GET /sessions/{session} und GET/POST/DELETE /sessions/{session}/profile.
• GET /devices?session=<selector> – wandelt Gerätekoordinaten in den Anwendungsraum der angegebenen Session um.
• Indexbasierte Geräteselektoren – sprechen Sie ein beliebiges Gerät über seinen Index an, ohne dessen ID zu kennen (/inverse3/0/... für das erste Inverse3; /inverse*/*/... für alle Geräte der Inverse-Familie).
• Einheitliche Anfrage-/Antwortstruktur – POST- und GET-Anfragen verwenden dieselben command_data-Strukturen von JSON wie WebSocket; Code, der für den einen Transport geschrieben wurde, funktioniert auch mit dem anderen.
• Optional aktivierbares Envelope über ?format=json auf jeder Route; /settings* und GET /home_return verwenden standardmäßig {ok, error, data}. Verwenden Sie ?format=plain für die Rohstruktur.
• Wildcards in Session-Selektoren – * (beliebige Zeichenfolge) und ? (ein einzelnes Zeichen) in Profilnamen.
• Prozentkodierte Selektoren – %2A, %3A usw. werden vor dem Routing dekodiert.

Ereignisse

• Eigener WebSocket-Ereignisstrom auf communication/events/port.
• 24 typisierte Ereigniskategorien, u. a. für den Lebenszyklus der Geräte, Sicherheit (E-Brake, Erkennung von Fremdkörpern, Blockierung), Kalibrierungsfehler, Akkuwarnungen, Session-Warnungen, niedrige und kritische Regelrate, Eingabevalidierung und Hinweise auf veraltete Funktionen.

Observability

• Log-Meldungen werden beim Profiling mit stufenabhängigen Farben an Tracy weitergeleitet.
• Tracy-Zonen für jeden HTTP-Handler.
• Ereignisse mit Timing-Statistiken der Hauptschleife.
• Konfigurierbares Log-Verzeichnis und konfigurierbarer Server-Hostname (Docker-freundlich).

Ausblick auf 3.6

• SDF Haptic Effects (SDF HFX) – Die Grundlagen sind bereits in 3.5 umgesetzt (Modul, Lebenszyklus, Serialisierung von modulbereitgestellten Befehlen und Zuständen), und die öffentliche API mit vollständiger Dokumentation folgt in 3.6.

Verbesserungen

• Filterung von Kraftoszillationen – achsenbezogene Oszillationserkennung, achtstufige, abgestufte Wiederherstellung, Eingangsabstimmung mit Hysterese und asymmetrische Freigabefenster.
• Force-Gate-Filter zur Laufzeit – konfigurierbar über configure.force_gate.gain über WebSocket oder HTTP, mit dauerhaft gespeichertem Standardwert.
• Maximale Frequenz der Hauptschleife auf 32 kHz erhöht für Präzisionsanwendungen.
• Kleinere WebSocket-Nutzlasten – Transformations-Unterfelder mit Identitätswerten als Standard (position = 0, rotation = identity, scale = 1) werden standardmäßig nicht ausgegeben. Dadurch sinkt die Nutzlastgröße, und die Kompatibilität mit dem 4-KB-Nachrichtenlimit älterer Unity-Pakete wird wiederhergestellt. Zwei erweiterte Einstellungen (serialization/explicit_fields, serialization/force_complete_transforms) nehmen alle Felder wieder auf, für Anwendungen, die diese benötigen.
• Geringerer Jitter der Hauptschleife – Die Verarbeitung von WebSocket-Nachrichten blockiert den Takt der Hauptschleife während des Parsens von JSON und beim Netzwerkversand nicht mehr; die Takt-Planung der Sessions wurde vor die Serialisierung der Antworten verlegt.
• Server sind standardmäßig nur über localhost erreichbar – Für Netzwerkzugriff aktivieren Sie die Einstellung communication/bind_all_interfaces.
• Wildcards bei Geräteselektoren nutzen Präfixsyntax (z. B. inverse* trifft alle Geräte der Inverse-Familie).
• Dämpfungsbefehle wurden zusammen mit force_gate in die configure-Map verschoben.
• Rotierender Datei-Logger ersetzt den bisherigen; das Verzeichnis ist konfigurierbar.
• Von Modulen bereitgestellte Befehle und Zustände – Module können eigene Befehle, Konfigurationsfelder und Zustandsausgaben in den WebSocket-Frame einbringen, ohne das Kernschema zu verändern.

Fehlerbehebungen

Ein Jahr voller Fehlerbehebungen; die wirkungsvollsten sind unten aufgeführt.

• Unregelmäßige Geschwindigkeit der Session unter bestimmten Bedingungen.
• GripHook (Verse Grip Stopper) wurde nicht sauber freigegeben, wenn keine Simulation lief.
• Inverse3-Timeouts waren zu aggressiv und verursachten Verbindungsschleifen bei langsam startenden Geräten.
• Unsauberes Beenden des Dienstes bei Windows — der HTTP-Server wurde beim Herunterfahren nicht immer bereinigt.
• Wiederverbindungsschleife, wenn der Dienst nicht unterstützte Befehle an ältere Firmware-Versionen sendete.
• Aufzählung der Bluetooth-Geräte überflutete das Log auf Systemen mit Bluetooth-Adaptern.
• Absturz beim mehrmaligen Neustart des Dienstes hintereinander.
• Einfrieren des kabellosen Verse-Grip-Dongles auf Ubuntu-Laptops nach Ruhezustand/Aufwachen.
• Handshake des kabellosen Verse Grip auf Linux und macOS greift jetzt korrekt auf den Fallback zurück, wenn der erste Erkennungsversuch fehlschlägt.
• Speicherort der macOS-Konfigurationsdatei — die Konfiguration wird jetzt in ~/Library/Application Support/ statt am falschen Pfad gespeichert.
• Behandlung des SIGSEGV-Signals auf Linux und macOS — der Prozess läuft bei fatalen Signalen nicht mehr in einer Schleife, wenn die Absturzerfassung für mehrere Threads aktiviert ist.
• Überschreiben von Befehlen über Sitzungen hinweg — Konfigurationsbefehle aus einer Sitzung konnten stillschweigend durch Befehle aus einer anderen Sitzung ersetzt werden; sie werden jetzt korrekt gefiltert und zusammengeführt.
• Probe-Befehle überschreiben die Konfiguration — Überwachungssitzungen (z. B. Haply Hub), die probe_position senden, überschreiben ausstehende Änderungen an Basis / Preset / Profil nicht mehr stillschweigend.
• Anzeige der Prototyp-Griffe — Prototyp-Hardware wurde fälschlicherweise als Standardgriff statt als benutzerdefinierter Griff angezeigt.
• Die veraltete Matrixkonvention von set_basis wird für Clients, die noch nicht migriert wurden, wieder berücksichtigt.
• Kraftimpuls von Inverse3 beim Trennen der Sitzung erzeugt keine Restkraftspitze mehr.
• Race Condition beim Verbindungsverlust von WebSocket bei schnell aufeinanderfolgenden Verbindungs- und Trennvorgängen.
• WebSocket session_id wurde in einigen ausgehenden Payloads als 0 serialisiert.
• Bei Windows wird --log-level jetzt auch in Kombination mit --dev berücksichtigt (zuvor wurde er stillschweigend auf debug zurückgesetzt).

Veraltete Elemente

Weiterhin funktionsfähig, wird jedoch in einer zukünftigen Hauptversion entfernt. Antworten enthalten gegebenenfalls ein Feld deprecation_warning.

Veraltet	Ersatz
POST /force_scale	POST /settings/devices/inverse*/filters/force_scale/gain
POST /gravity_compensation	POST /{device}/{id}/config/gravity_compensation
POST /torque_scaling	POST /{device}/{id}/config/torque_scaling
POST /device_handedness	POST /{device}/{id}/config/handedness
POST /serial_enable	POST /settings/communication/serial/enabled
POST /experimental/features/grip_dropped_simulation_stopper	Settings API
POST /experimental/features/screensaver_enable	Settings API
WebSocket command_data.values	position, vector, angles, torques
WebSocket set_angular_torque	set_angular_torques
WebSocket probe_cursor_position	probe_position
WebSocket set_coordinate_origin	configure.preset
WebSocket session-level set_basis	configure.basis

Kompatibilitätshinweise

Gegenüber 3.4.19 gibt es keine harten Breaking Changes. Zwei weiche Hinweise für bestehende Integrationen:

1. Veraltete HTTP-Endpunkte enthalten jetzt ein Feld deprecation_warning in der Antwort — Clients, die Antwortschemata strikt validieren, sollten das zusätzliche Feld zulassen.
2. Das Feld values in WebSocket command_data ist veraltet, wird aber weiterhin geparst; verwenden Sie bevorzugt die benannten Felder.

Tutorials und Dokumentation

• Neue Tutorials: 05 Positionsregelung, 06 Kombiniert (Inverse3 + Verse Grip), 07 Basis und Montage, 08 HTTP Remote Configurator, 09 WebSocket Remote Control, 10 Event-Stream-Listener.
• Neue Glaze-Variante jedes C++-Tutorials (cpp-glz/) neben der bestehenden nlohmann/json-Variante.
• Alle Tutorials wurden für die v3.1-API neu geschrieben (Port 10001, configure.preset, benannte Befehlsfelder, print_state()-Hilfsfunktionen).
• Das alte Verse-Grip-Stopper-Tutorial wurde entfernt — ersetzt durch das neue kombinierte Tutorial.
• Die öffentliche Dokumentation wurde über die SDK-Leitfäden, die API-Referenz und die Hardware-Seiten hinweg aktualisiert.