v3.5.0

Unsere umfangreichste Veröffentlichung seit der Neugestaltung der API vor einem Jahr. Version 3.5.0 bietet eine einheitliche 3D-Mathematik-Ebene, vollständige Minverse , einen typisierten Ereignisstrom, eine umfassende Einstellungs-API und eine übersichtlichere HTTP-Schnittstelle – sowie ein Jahr voller Fehlerbehebungen und Verbesserungen der Benutzerfreundlichkeit.

Highlights

• Einheitliche 3D-Mathematikebene – eine modulare Transformationspipeline mit erstklassigen Primitiven für die Gerätebasis (Frame), die Mount-Transformation, die Arbeitsbereichstransformation und die Navigationtransformation sowie explizite Konvertierungen zwischen lokalen, Sitzungs-, Anwendungs- und internen Räumen.
• Bubble Navigation – Navigation durch große virtuelle Arbeitsbereiche mithilfe von geformten Zonen (SDF-Primitive) mit geschwindigkeitsabhängiger Steuerung, hysteresefähiger Kollisionserkennung und optionaler Drift-in-Richtung-des-Cursors. Vollständig konfigurierbar über HTTP und WebSocket mit Round-Trip-Kommunikation zwischen Anwendung und Arbeitsbereich.
• Typisierter Ereignisstrom – ein spezieller WebSocket-Ereigniskanal für den Geräte-Lebenszyklus, Sicherheitswarnungen, Kalibrierung, Akku, Warnungen zur Steuerungsrate und Hinweise auf die Auslaufphase.
• Einstellungs-API – ein umfassendes Schlüssel-Wert-Einstellungssystem mit HTTP-CRUD, Typangaben, Bereichsbeschränkungen und Beschreibungen, das die alte verschachtelte Konfigurationsdatei ersetzt.
• Einheitliche Gerätekonfiguration — ein Satz von HTTP-Routen für jedes Gerät: basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
• Synchronisierte Minverse Stiftkalibrierung – das Gerät und der Stift werden nun gemeinsam kalibriert; die Kalibrierung bleibt gespeichert, bis ein Griff physisch angebracht wird.
• HTTP für mehr Lebensqualität — indexbasierte Geräteauswahl (Auswahl eines Geräts anhand des Index, keine ID erforderlich), ein einheitliches Anfrage-/Antwortformat, das auch bei WebSocket verwendet wird, eine Opt-in-Funktion {ok, error, data} Umschlag (?format=json) sowie Platzhalter für Sitzungsselektoren.

Neue Funktionen

Geräte

• Minverse — Offizielle Unterstützung in dieser Version: Erkennung, Bereitschaftssequenz, Sicherheitsbenachrichtigungen und der synchronisierte Kalibrierungsablauf.
• Ruko und Kingfisher wurden als offizielle Griffmodelle anerkannt.
• Unterstützung für Gerätesimulatoren – Erkennung und Kommunikation mit softwaremäßig simulierten Geräten neben echter Hardware.
• Schutz der Verbindungsschleife — Ports, die sich verdächtig verhalten, werden automatisch blockiert; Zurücksetzen mit POST /ports/{port}/reset.
• Stift-Anschluss „Herzschlag“ – zuverlässige Erkennung des An- und Abnehmens mit Entprellung.

Sitzungen, Befehle und WebSocket

• Filterung und Persistenz von Sitzungsprofilen – Sitzungen geben einen Profilnamen und die erforderliche SDK-Version an, die der Dienst auch bei erneuten Verbindungen speichert; Clients und Überwachungstools können Sitzungen anhand dieses Profils filtern und gezielt ansprechen.
• Befehlspuffer pro Sitzung – eine langsame Sitzung kann eine andere nicht mehr blockieren.
• Ausdrücklich configure Zuordnung für einmalige Befehle — basis, preset, mount, force_gate, damping pro Gerät, zuzüglich profile und basis pro Sitzung, jetzt alle live in configure — abgestimmt auf die Ausgabekonfigurationszuordnung, sodass die gesendeten Daten mit den zurückgelesenen Daten übereinstimmen.
• Anpassbare Gerätehalterung — Wählen Sie eine integrierte Arbeitsbereichsvoreinstellung (defaults, arm_front, arm_front_centered, led_front, led_front_centered) oder eine explizite Transformation senden; bei manuellen Änderungen der Einbindung wird die Voreinstellung automatisch auf custom.
• Benannte Befehlsfelder — position, vector, angles, torques den Platzhalter ersetzen values Array.
• set_angular_torques ersetzt set_angular_torque (Singular veraltet).
• Erweiterungen des Sitzungsrahmens — Die Session-Frames der Versionen 3.0 und 3.1 sind nun erweiterbar config, stateund status Objekte; zu den neuen Ausgabefeldern gehören current_cursor_force, current_cursor_position, current_angular_torques, current_angular_position, control_domain, control_mode, transform, transform_velocity, reichhaltiger config.*und status.safety (standardmäßig ausgeblendet).
• Aktualisierungen von Teiltransformationen — Sende nur die Unterfelder, die du ändern möchtest (position, rotation, scale) in Bezug auf die Montage, die Arbeitsbereichstransformation und die Navigationsform.

HTTP

• GET / — Serviceversion.
• GET/POST/DELETE /settings und /settings/* — Vollständige API für Schlüssel-Wert-Einstellungen.
• GET /sessions/{session} und GET/POST/DELETE /sessions/{session}/profile.
• GET /devices?session=<selector> — Gerätekoordinaten in den Anwendungsraum einer bestimmten Sitzung umrechnen.
• Indexbasierte Geräteauswahl — jedes Gerät anhand seines Indexes ansprechen, ohne dessen ID zu kennen (/inverse3/0/... für das erste Inverse3; /inverse*/*/... (für alle Geräte der Inverse-Familie).
• Einheitliches Anfrage-Antwort-Schema — POST-/GET-Body-Daten verwenden dasselbe command_data JSON lässt sich als WebSocket nutzen; Code, der für das eine Transportprotokoll geschrieben wurde, funktioniert auch für das andere.
• Umschlag für die Einwilligung über ?format=json auf jeder Strecke; /settings* und GET /home_return Standardmäßig {ok, error, data}. Verwenden ?format=plain für die Rohform.
• Platzhalter für die Sitzungsauswahl — * (beliebige Folge) und ? (einzelnes Zeichen) in Profilnamen.
• Prozentual entschlüsselte Selektoren — %2A, %3A, usw. werden vor der Weiterleitung decodiert.

Veranstaltungen

• Spezieller WebSocket-Ereignisstrom auf communication/events/port.
• 24 vordefinierte Ereigniskategorien, darunter Gerätelebenszyklus, Sicherheit (E-Bremse, Fremdkörpererkennung, Blockieren), Kalibrierungsfehler, Batteriewarnungen, Sitzungswarnungen, niedrige/kritische Steuerungsrate, Eingabevalidierung und Hinweise auf veraltete Funktionen.

Beobachtbarkeit

• Log-Meldungen, die bei der Profilerstellung an Tracy weitergeleitet werden, werden je nach Schweregrad farblich gekennzeichnet.
• Tracy wird auf jeden HTTP-Handler angewendet.
• Ereignisse zur Zeitmessung in der Hauptschleife.
• Konfigurierbares Protokollverzeichnis und Server-Hostname (Docker-kompatibel).

Erscheint in Version 3.6

• SDF Haptic Effects (SDF HFX) – die Grundlagen wurden bereits in Version 3.5 implementiert (Modul, Lebenszyklus, durch das Modul bereitgestellte Befehls-/Zustandsserialisierung), und die öffentliche API wird in Version 3.6 zusammen mit einer vollständigen Dokumentation veröffentlicht.

Verbesserungen

• Kraftschwingungsfilterung – Schwingungserkennung pro Achse, 8-stufige abgestufte Rückstellung, Eingangsabfrage mit Hysterese und asymmetrische Freigabefenster.
• Laufzeit-Force-Gate-Filter — konfigurierbar über configure.force_gate.gain über WebSocket oder HTTP mit einer dauerhaften Verbindung.
• Die maximale Frequenz der Hauptschleife wurde für Präzisionsanwendungen auf 32 kHz erhöht.
• Kleinere WebSocket-Datenpakete — Unterfelder der Standardidentitätstransformation (position = 0, rotation = identity, scale = 1) werden standardmäßig in der Ausgabe weggelassen, wodurch die Datenmenge reduziert und die Kompatibilität mit der 4-KB-Nachrichtenbegrenzung älterer Unity-Pakete wiederhergestellt wird. Zwei erweiterte Einstellungen (serialization/explicit_fields, serialization/force_complete_transforms) alle Felder für Verbraucher wiederherstellen, die diese benötigen.
• Geringerer Jitter in der Hauptschleife – Die Verarbeitung von WebSocket-Nachrichten blockiert den Tick der Hauptschleife während der JSON-Analyse und des Netzwerk-Sendevorgangs nicht mehr; die Planung des Session-Ticks wurde vor die Serialisierung der Antwort verlegt.
• Server sind standardmäßig auf „nur localhost“ eingestellt — den Netzwerkzugang über das communication/bind_all_interfaces Einstellung.
• Platzhalter für die Geräteauswahl verwenden eine Präfix-Syntax (z. B. inverse* (gilt für alle Geräte der Inverse-Familie).
• Dämpfungsbefehle zog in das configure Karte daneben force_gate.
• Der Logger für rotierende Dateien ersetzt den bisherigen und verfügt über ein konfigurierbares Verzeichnis.
• Von Modulen bereitgestellte Befehle und Zustände – Module können ihre eigenen Befehle, Konfigurationsfelder und Zustandsdaten in den WebSocket-Frame einfügen, ohne das Kernschema zu verändern.

Korrekturen

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

• Unter bestimmten Umständen unregelmäßige Sitzungsgeschwindigkeit.
• GripHook (Verse Grip Stopper) löste sich nicht ordnungsgemäß, wenn keine Simulation lief.
• Inverse3 waren zu streng und führten bei Geräten mit langsamer Startzeit zu Endlosschleifen bei der Trennung der Verbindung.
• Unbeendeter Dienst 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 Erfassung von Bluetooth-Geräten hat das Protokoll auf Systemen mit Bluetooth-Adaptern überflutet.
• Absturz beim mehrmaligen Neustart des Dienstes hintereinander.
• Der Wireless Verse Grip-Dongle friert auf Ubuntu-Laptops nach dem Ruhezustand bzw. beim Aufwachen ein.
• Der Wireless-Verse-Grip-Handshake unter Linux und macOS weicht nun korrekt auf einen Fallback zurück, wenn der erste Erkennungsversuch fehlschlägt.
• Speicherort der MacOS-Konfigurationsdatei — Die Konfiguration wird nun gespeichert in ~/Library/Application Support/ statt den falschen Weg einzuschlagen.
• Behandlung von SIGSEGV-Signalen unter Linux und macOS – Der Prozess läuft bei fatalen Signalen nicht mehr in einer Endlosschleife, wenn die Multi-Thread-Absturzerfassung aktiviert ist.
• Überschreiben von Befehlen zwischen Sitzungen – Konfigurationsbefehle aus einer Sitzung konnten bisher unbemerkt durch Befehle aus einer anderen Sitzung ersetzt werden; sie werden nun gefiltert und korrekt zusammengeführt.
• Befehle zum Überschreiben der Konfiguration — Übertragungen von Überwachungssitzungen (z. B. Haply ) probe_position Änderungen an Basis-, Voreinstellungen und Profilen werden nicht mehr stillschweigend überschrieben.
• Anzeige der Prototyp-Griffe – die Prototyp-Hardware wurde fälschlicherweise als Standardgriff statt als benutzerdefinierter Griff angezeigt.
• Vermächtnis set_basis Matrix-Konvention wieder für Kunden gewährt, die nicht migriert waren.
• Inverse3 bei einer Sitzungsunterbrechung verursacht keinen Restkraftspitzenwert mehr.
• Bei schnellen Verbindungsaufbau- und -abbruchzyklen kam es zu einem Wettlauf um die WebSocket-Verbindung.
• WebSocket session_id wurde als Fortsetzungsroman veröffentlicht 0 in einigen ausgehenden Datenpaketen.
• Unter Windows, --log-level wird nun berücksichtigt, wenn es mit --dev (wurde zuvor stillschweigend zurückgesetzt auf debug).

Verwerfungen

Noch funktionsfähig, wird aber in einer zukünftigen Hauptversion entfernt. Zu den Antworten gehört ein deprecation_warning Feld, sofern zutreffend.

Abgelehnt	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

Keine gravierenden Kompatibilitätsänderungen gegenüber 3.4.19. Zwei Hinweise für bestehende Integrationen:

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

Anleitungen & Dokumentation

• Neue Tutorials: 05 Positionssteuerung, 06 Kombiniert (Inverse3 Verse Grip), 07 Basis und Halterung, 08 HTTP-Fernkonfigurator, 09 WebSocket-Fernsteuerung, 10 Event-Stream-Listener.
• Neue Glasurvariante in jedem C++-Tutorial (cpp-glz/) neben der bestehenden nlohmann/json-Variante.
• Alle Tutorials wurden überarbeitet für die API v3.1 (Port 10001, configure.preset, benannte Befehlsfelder, print_state() Helfer).
• Das alte Tutorial zum „Verse Grip Stopper“ wurde entfernt – es wurde durch das neue kombinierte Tutorial ersetzt.
• Die öffentliche Dokumentation wurde in den SDK-Anleitungen, der API-Referenz und auf den Hardware-Seiten aktualisiert.