v3.5.0

Dies ist unsere bislang umfangreichste Version seit der Überarbeitung der API vor einem Jahr. Mit Version 3.5.0 werden eine einheitliche 3D-Mathematikschicht, vollständige Unterstützung für „ Minverse “, ein typisierter Ereignisstrom, eine vollständige Settings-API und eine übersichtlichere HTTP-Schnittstelle eingeführt – dazu ein Jahr voller Fehlerbehebungen und Verbesserungen der Benutzerfreundlichkeit.

Highlights

• Einheitliche 3D-Mathematikschicht – eine kombinierbare Transformationspipeline mit vollwertigen Primitiven für Gerätebasis (Frame), Mount-Transformation, Arbeitsbereichstransformation und Navigationtransformation sowie explizite Umrechnungen zwischen lokalem Raum, Sitzungsraum, 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 Abfragefrequenz und Hinweise auf veraltete Funktionen.
• Settings-API – ein umfassendes Key-Value-Einstellungssystem mit HTTP-CRUD, Typangaben, 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 Kalibrierung von „ Minverse “ und Stift – 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 erforderlich), eine einheitliche Anfrage-/Antwortstruktur, die mit WebSocket geteilt wird, eine optional aktivierbare {ok, error, data}-Umschlag (?format=json) und Wildcard-Sitzungsselektoren.

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-Typen erkannt.
• Unterstützung für Gerätesimulatoren – softwaresimulierte Geräte lassen sich neben echter Hardware erkennen und ansteuern.
• 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.

Sitzungen, Befehle und WebSocket

• Filterung und Persistenz von Sitzungsprofilen – Sitzungen geben einen Profilnamen und die erforderliche SDK-Version an; der Dienst speichert beides über mehrere Verbindungsaufbauten hinweg. Clients und Überwachungstools können Sitzungen anhand dieses Profils filtern und gezielt ansprechen.
• Befehlspuffer pro Sitzung – eine langsame Sitzung kann andere nicht mehr ausbremsen.
• Explizite configure-Karte für Einmalbefehle – basis, preset, mount, force_gate, damping pro Gerät sowie profile und basis pro Sitzung werden nun alle in configure übergeben und sind auf die Ausgabe-Konfigurations-Map abgestimmt, sodass das Gesendete mit dem Zurückgelesenen übereinstimmt.
• Anpassbare Gerätehalterung – Wählen Sie eine integrierte Workspace-Voreinstellung (defaults, arm_front, arm_front_centered, led_front, led_front_centered) oder senden Sie eine explizite Transformation; bei manuellen Mount-Änderungen wird 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).
• Teilweise 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 Schlüssel-Wert-Paare.
• GET /sessions/{session} und GET/POST/DELETE /sessions/{session}/profile.
• GET /devices?session=<selector> – wandelt Gerätekoordinaten in den Anwendungsraum der angegebenen Sitzung um.
• Indexbasierte Geräteselektoren – sprechen Sie ein beliebiges Gerät über seinen Index an, ohne dessen ID zu kennen (/inverse3/0/... Zunächst einmal Inverse3; /inverse*/*/... (für alle Geräte der Inverse-Familie).
• Einheitliche Struktur für Anfragen und Antworten – POST- und GET-Anfragen verwenden dieselben command_data-JSON-Strukturen wie WebSocket; Code, der für das eine Transportprotokoll geschrieben wurde, funktioniert auch mit dem anderen.
• Optional aktivierbarer Envelope über ?format=json auf jeder Strecke; /settings* und GET /home_return verwenden standardmäßig {ok, error, data}. Verwenden Sie ?format=plain für die Rohstruktur.
• Platzhalter in Sitzungsselektoren – * (beliebige Zeichenfolge) und ? (ein einzelnes Zeichen) in Profilnamen.
• Prozentcodierte Selektoren – %2A, %3A usw. werden vor dem Routing dekodiert.

Ereignisse

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

Beobachtbarkeit

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

Ausblick auf 3.6

• SDF Haptic Effects (SDF HFX) – Die Grundlagen wurden bereits in Version 3.5 umgesetzt (Modul, Lebenszyklus, Serialisierung der vom Modul bereitgestellten Befehle und Zustände), und die öffentliche API mit vollständiger Dokumentation folgt in Version 3.6.

Verbesserungen

• Filterung von Kraftschwingungen – achsenbezogene Schwingungserkennung, 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.
• Die maximale Frequenz der Hauptschleife wurde für Präzisionsanwendungen auf 32 kHz erhöht.
• Kleinere WebSocket-Nutzdaten – Transformations-Unterfelder mit Identitätswerten als Standard (position = 0, rotation = identity, scale = 1) werden standardmäßig nicht ausgegeben. Dadurch verringert sich 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) stellen alle Felder wieder zur Verfügung – 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 Taktplanung der Sessions wurde vor die Serialisierung der Antworten verlegt.
• Server sind standardmäßig nur über „localhost“ erreichbar. – Um den Netzwerkzugriff zu aktivieren, nehmen Sie folgende Einstellung vor: communication/bind_all_interfaces.
• Bei Geräteselektoren werden Platzhalter in der Präfixsyntax verwendet (z. B. inverse* (gilt für alle Geräte der Inverse-Familie).
• Dämpfungsbefehle wurden zusammen mit force_gate in die configure-Karte verschoben.
• Der rotierende 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 wirksamsten sind unten aufgeführt.

• Unregelmäßige Geschwindigkeit der Sitzung unter bestimmten Bedingungen.
• GripHook (Verse Grip Stopper) wurde nicht ordnungsgemäß freigegeben, wenn keine Simulation lief.
• Inverse3-Die Timeouts waren zu aggressiv und führten bei Geräten mit langsamer Startzeit zu Endlosschleifen bei der Verbindung.
• Unkorrektes Beenden des Dienstes unter Windows – der HTTP-Server wurde beim Herunterfahren nicht immer ordnungsgemäß beendet.
• Wiederverbindungsschleife, wenn der Dienst nicht unterstützte Befehle an ältere Firmware-Versionen gesendet hat.
• Die Auflistung der Bluetooth-Geräte überflutete das Protokoll auf Systemen mit Bluetooth-Adaptern.
• Absturz beim mehrmaligen aufeinanderfolgenden Neustart des Dienstes.
• Einfrieren des kabellosen Verse-Grip-Dongles auf Ubuntu-Laptops nach dem Ruhezustand bzw. dem Aufwachen.
• Der Handshake des kabellosen Verse Grip unter Linux und macOS greift nun korrekt auf den Fallback zurück, wenn der erste Erkennungsversuch fehlschlägt.
• Speicherort der macOS-Konfigurationsdatei — Die Konfiguration wird nun in ~/Library/Application Support/ statt im falschen Pfad gespeichert.
• Verarbeitung des SIGSEGV-Signals unter Linux und macOS – Der Prozess läuft bei fatalen Signalen nicht mehr in einer Schleife, wenn die Absturzprotokollierung für mehrere Threads aktiviert ist.
• Überschreiben von Befehlen über Sitzungen hinweg — Konfigurationsbefehle aus einer Sitzung konnten bisher stillschweigend durch Befehle aus einer anderen Sitzung ersetzt werden; sie werden nun korrekt gefiltert und zusammengeführt.
• Probe-Befehle überschreiben die Konfiguration — Überwachungssitzungen (z. B. Haply Hub), die probe_position Ausstehende Änderungen an Basis / Voreinstellung / Profil werden nicht mehr stillschweigend übernommen.
• 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.
• Der Kraftimpuls, der beim Beenden der Sitzung von Inverse3 erzeugt wird, verursacht keine Restkraftspitze mehr.
• Race Condition bei Verbindungsverlust des WebSockets bei schnell aufeinanderfolgenden Verbindungs- und Trennungsvorgängen.
• WebSocket session_id wurde in einigen ausgehenden Payloads als 0 serialisiert.
• Unter 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	Einstellungs-API
POST /experimental/features/screensaver_enable	Einstellungs-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
auf WebSocket-Sitzungsebene set_basis	configure.basis

Hinweise zur Kompatibilität

Im Vergleich zur Version 3.4.19 gibt es keine gravierenden Breaking Changes. Zwei kleinere Hinweise für bestehende Integrationen:

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

Anleitungen und Dokumentation

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