v3.5.0

Dies ist die umfangreichste Veröffentlichung seit der Neugestaltung der API vor einem Jahr. Mit Version 3.5.0 werden eine einheitliche 3D-Mathematik-Ebene, vollständige Unterstützung für „ Minverse “, typisierte Ereignisströme, eine umfassende Konfigurations-API sowie eine übersichtlichere HTTP-Schnittstelle eingeführt; außerdem umfasst sie die Fehlerbehebungen und Optimierungen der Benutzererfahrung aus einem ganzen Jahr.

Highlights

• Eine einheitliche 3D-Mathematikebene – eine kombinierbare Transformationspipeline, die Primitive erster Ordnung für das Geräte-Basiskoordinatensystem (basis/frame), die Befestigungstransformation (mount transform), die Arbeitsraumtransformation (workspace transform) und die Navigationtransformation (navigation transform) bereitstellt und explizite Transformationen zwischen lokalen, Sitzungs-, Anwendungs- und internen Räumen unterstützt.
• Bubble Navigation – Navigation durch Formgebungsbereiche (SDF-Elemente) in einem großen virtuellen Arbeitsraum, mit Unterstützung für die Geschwindigkeitssteuerung mittels Speed-Mapping, einer hysterese-sensitiven Kollisionserkennung sowie einer optionalen Drift in Richtung des Cursors. Vollständig über HTTP und WebSocket konfigurierbar und mit Unterstützung für den Wechsel zwischen Anwendungsräumen.
• Typisierte Ereignisströme – spezielle WebSocket-Ereigniskanäle, die den Lebenszyklus des Geräts, Sicherheitswarnungen, Kalibrierungen, den Akkustand, Warnungen zur Steuerungsrate sowie Hinweise zur Ausmusterung abdecken.
• Konfigurations-API – Ein umfassendes Schlüssel-Wert-Konfigurationssystem, das HTTP-CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen), Typhinweise, Bereichsbeschränkungen und Beschreibungen unterstützt und die alten verschachtelten Konfigurationsdateien ersetzt.
• Einheitliche Gerätekonfiguration —— Alle Geräte nutzen ein gemeinsames HTTP-Routing:basis、mount、preset、transform、filters、handedness、torque_scaling、gravity_compensation、home_return。
• Minverse Synchrone Kalibrierung mit dem Stift – Das Gerät und der Stift können nun gemeinsam kalibriert werden; die Kalibrierung bleibt gesperrt, bis der Griff tatsächlich angebracht ist.
• Optimierung der HTTP-Benutzererfahrung —— Indexbasierter Geräte-Selektor (Geräte werden anhand des Indexes angegeben, keine ID erforderlich), einheitliche Anfrage-/Antwortstruktur, die mit WebSocket geteilt wird, optional aktivierbar {ok, error, data} Gehäusestruktur (?format=json) sowie Platzhalter für die Sitzungsauswahl.

Neue Funktionen

Ausrüstung

• Minverse —— Diese Version bietet nun offizielle Unterstützung für: Erkennung, Bereitschaftsprozesse, Sicherheitsbenachrichtigungen sowie Workflows zur synchronen Kalibrierung.
• „Ruko“ und „Kingfisher“ wurden als offizielle Griff-Produkttypen anerkannt.
• Unterstützung für Gerätesimulatoren – Kann simulierte Geräte erkennen und mit ihnen kommunizieren, ist dabei aber auch mit echter Hardware kompatibel.
• Schutz vor Kurzschlüssen —— Ports mit ungewöhnlichem Verhalten werden automatisch gesperrt; dies kann über POST /ports/{port}/reset Zurücksetzen.
• Erkennung des Einsteckens des Stifts —— Zuverlässige Erkennung des Einsteckens bzw. Herausnehmens des Stifts mithilfe einer Entstörungsfunktion.

Sitzungen, Befehle und WebSocket

• Filterung und Speicherung von Sitzungsprofilen – Geben Sie den Namen des Sitzungsprofils und die erforderliche SDK-Version an; der Dienst speichert diese Informationen für eine erneute Verbindung. Der Client und die Überwachungstools können anhand dieses Profils Sitzungen filtern und identifizieren.
• Befehlspuffer nach Sitzungen – Eine einzelne langsame Sitzung bremst nun keine anderen Sitzungen mehr aus.
• Die explizite Form von Einmalbefehlen configure Abbildung —— Pro Gerät basis、preset、mount、force_gate、dampingsowie für jede Sitzung profile und basis, jetzt alles zusammen einfügen configure Dabei wird die Übereinstimmung mit der Ausgangskonfigurationszuordnung gewahrt, sodass die gesendeten Inhalte den zurückgelesenen Inhalten eins zu eins entsprechen.
• Anpassbare Geräteeinbindung —— Es stehen integrierte Arbeitsbereichsvoreinstellungen zur Auswahl (defaults、arm_front、arm_front_centered、led_front、led_front_centered), es können auch explizite Transformationen gesendet werden; nach einer manuellen Änderung der Zuordnung wechselt die Voreinstellung automatisch zu custom。
• Benannte Befehlsfelder —— position、vector、angles、torques ersetzt das allgemeine values Array.
• set_angular_torques ersetzt set_angular_torque(Die Singularform ist veraltet).
• Erweiterung des Sitzungsrahmens —— Die Sitzungsrahmen der Versionen v3.0 und v3.1 enthalten nun erweiterbare config、state und status Objekt; 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、noch vielfältiger config.*, sowie status.safety(Standardmäßig ausgeblendet).
• Teilweise Aktualisierung der Transformationen —— Bei der Einbindung, der Arbeitsraumtransformation und der Navigation durch die Geometrie müssen lediglich die zu ändernden Unterfelder gesendet werden (position、rotation、scale).

HTTP

• GET / —— Serviceversion.
• GET/POST/DELETE /settings und /settings/* —— Eine vollständige API für die Konfiguration von Schlüssel-Wert-Paaren.
• GET /sessions/{session} sowie GET/POST/DELETE /sessions/{session}/profile。
• GET /devices?session=<selector> —— Die Gerätekoodinaten werden in den Anwendungsraum der angegebenen Sitzung umgewandelt.
• Indexbasierter Geräteauswähler —— Man kann jedes beliebige Gerät anhand seines Indexes angeben, ohne die Geräte-ID zu kennen (das erste Inverse3 verwenden /inverse3/0/...; Alle Geräte der Inverse-Serie verwenden /inverse*/*/...).
• Einheitliche Anfrage-/Antwortstruktur —— Der POST-/GET-Anfragetext verwendet dasselbe Format wie WebSocket command_data JSON-Struktur; Code, der für eine der beiden Übertragungsarten geschrieben wurde, lässt sich auch auf die andere anwenden.
• Optionale Gehäusekonstruktionen —— Auf einer beliebigen Route hinzufügen ?format=json kann sofort aktiviert werden;/settings* und GET /home_return Standardmäßig zurückkehren {ok, error, data}。Wenn Sie die ursprüngliche Struktur benötigen, verwenden Sie bitte ?format=plain。
• Platzhalter für die Sitzungsauswahl —— im Profilnamen *(beliebige Zeichenfolge) und ?(ein einzelnes Zeichen).
• Dekodierung des Prozentzeichen-Selektors —— %2A、%3A usw. werden vor der Weiterleitung zunächst dekodiert.

Vorfall

• gelegen in communication/events/port der dedizierte WebSocket-Ereignisstrom.
• Insgesamt 24 Ereigniskategorien, darunter Ereignisse zum Lebenszyklus des Geräts, Sicherheitsereignisse (elektronische Bremse (e-brake), Fremdkörpererkennung, Blockierung), fehlgeschlagene Kalibrierung, Batteriealarme, Sitzungswarnungen, niedrige/sehr niedrige Steuerungsrate, Eingabeüberprüfung sowie Hinweise auf die Außerbetriebnahme.

Beobachtbarkeit

• Bei der Leistungsanalyse werden die Protokollmeldungen an Tracy weitergeleitet und entsprechend der Protokollstufe farblich gekennzeichnet.
• Fügen Sie für jede HTTP-Verarbeitungsfunktion einen Tracy-Bereich hinzu.
• Zeitmessung und Erfassung von Ereignissen in der Hauptschleife.
• Das Protokollverzeichnis und der Hostname des Servers können konfiguriert werden (zur Verwendung mit Docker).

Version 3.6 erscheint in Kürze

• SDF-Haptik-Effekte (SDF HFX) – Die Grundlagen wurden bereits in Version 3.5 fertiggestellt (Module, Lebenszyklus, Serialisierung der von den Modulen bereitgestellten Befehle/Zustände); die öffentliche API und die vollständige Dokumentation werden mit Version 3.6 veröffentlicht.

Verbesserung

• Kraftschwingungsfilterung – Achsenweise Schwingungserkennung, 8-stufige progressive Rückstellung, Abstimmungsbeginn mit Hysterese sowie asymmetrisches Freigabefenster.
• Laufzeit-kraftgesteuerter Filter —— kann über configure.force_gate.gain Die Konfiguration erfolgt über WebSocket oder HTTP und enthält standardmäßig persistente Werte.
• Die maximale Frequenz der Hauptschleife wurde auf 32 kHz erhöht, was für hochpräzise Anwendungen geeignetist.
• Geringere WebSocket-Last —— Transformationsunterfeld für den Standardwert „Identität“ (position = 0、rotation = identity、scale = 1) wird standardmäßig nicht mehr ausgegeben, wodurch das Datenvolumen reduziert und die Kompatibilität mit der in älteren Unity-Versionen geltenden Obergrenze von 4 KB pro Nachricht wiederhergestellt wird. Zwei erweiterte Einstellungen (serialization/explicit_fields、serialization/force_complete_transforms) können alle Felder für Nutzer, die sie benötigen, wieder aktiviert werden.
• Reduzierung des Jitter im Hauptzyklus – Die Verarbeitung von WebSocket-Nachrichten blockiert den Takt des Hauptzyklus während der JSON-Analyse und der Netzwerkübertragung nicht mehr; die Planung des Sitzungstakts wurde vor die Serialisierung der Antwort verlegt.
• Der Server hört standardmäßig nur auf „localhost“. —— Falls Sie einen Internetzugang benötigen, nutzen Sie bitte communication/bind_all_interfaces Einstellung aktivieren.
• Bei den Platzhaltern im Geräteauswahl-Selektor wird nun die Präfix-Syntax verwendet(zum Beispiel inverse* (kompatibel mit allen Geräten der Inverse-Serie).
• Dämpfungsbefehl Wurde verschoben configure Bei der Zuordnung, mit force_gate Zusammenlegen.
• Der rotierende Dateilogger ersetzt den bisherigen Logger und unterstützt die Konfiguration von Verzeichnissen.
• Befehle und Statusangaben von Modulen – Module können eigene Befehle und Konfigurationsfelder einbinden und Statusangaben in WebSocket-Frames schreiben, ohne das Kernschema ändern zu müssen.

Reparatur

Fehlerbehebungen über das gesamte Jahr hinweg; die wichtigsten davon sind im Folgenden aufgeführt.

• Die Verbindungsgeschwindigkeit ist ungewöhnlichund tritt unterbestimmten Bedingungen auf.
• **GripHook (Verse Grip Stopper)** lässt sich nicht sauber lösen, wenn keine Simulation läuft.
• Inverse3 Die Zeitüberschreitungs-Einstellungen sind zu streng, was dazu führt, dass Geräte mit langsamerer Startzeit in eine Endlos-Trennungsschleife geraten.
• Unter Windows werden Dienste nicht ordnungsgemäß beendet– beim Herunterfahren wird der HTTP-Server nicht immer bereinigt.
• Wiederholungsschleife– Tritt auf, wenn der Dienst nicht unterstützte Befehle an ältere Firmware-Versionen sendet.
• Die Erkennung von Bluetooth-Gerätenführt auf Systemen mit Bluetooth-Adapter zu einer hohen Anzahl von Log-Einträgen.
• Bei wiederholten Neustarts des Dienstes kommt es zu einem Absturz.
• Bei Ubuntu-Laptops friert der WLAN-Empfänger „Verse Grip“ nach dem Wechsel in den Ruhezustand bzw. beim Aufwachen ein.
• Der drahtlose „Verse Grip“ führtunter Linux und macOS nach einem ersten Fehlversuch beim Erkennen nun korrekt einen Rückfall durch.
• Speicherort der macOS-Konfigurationsdateien——Die Konfiguration wird nun gespeichert unter ~/Library/Application Support/ Dabei wird der falsche Pfad nicht mehr verwendet.
• Behandlung des SIGSEGV-Signals unter Linux und macOS– Bei aktivierter multithread-basierter Absturzabfangfunktion gerät der Prozess nicht mehr in eine Endlosschleife, wenn ein tödliches Signal auftritt.
• Überschreibung von Befehlen zwischen Sitzungen– Ein Konfigurationsbefehl aus einer Sitzung konnte bisher unbemerkt durch einen Befehl aus einer anderen Sitzung überschrieben werden; dies wird nun korrekt gefiltert und zusammengeführt.
• Konfiguration der Erkennungsbefehle——Überwachung der von einer Sitzung (z. B. Haply Hub) gesendeten Daten probe_position wird die noch nicht in Kraft getretene Änderung an „basis“, „preset“ oder „profile“ nicht mehr stillschweigend überschrieben.
• Fehler bei der Anzeige des Prototyp-Griffs– Die Prototyp-Hardware wird fälschlicherweise als Standardgriff und nicht als benutzerdefinierter Griff angezeigt.
• Alte Version set_basis Matrix-KonventionGilt erneut für noch nicht migrierte Clients.
• Inverse3 Der „Force Kick“ erzeugt bei einer Unterbrechung der Verbindung keine Restkraftspitzen mehr.
• WebSocket-Verbindungsverlust-Race-Condition– tritt während eines schnellen Verbindungsaufbau-/Trennungszyklus auf.
• WebSocket session_id wird in einem Teil der ausgehenden Datenlast serialisiert als 0。
• Unter Windows bei gleichzeitiger Verwendung von --dev Derzeit wird Folgendes befolgt --log-level(zuvor wurde dies stillschweigend zurückgesetzt auf debug).

Veraltete Elemente

Es kann weiterhin normal verwendet werden, wird jedoch in einer zukünftigen Hauptversion entfernt. Gegebenenfalls enthält die Antwort deprecation_warning Feld.

Veraltet	Alternative
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
WebSocket auf Sitzungsebene set_basis	configure.basis

Hinweise zur Kompatibilität

Im Vergleich zur Version 3.4.19 gibt es keine zwingenden, kompatibilitätsbrechenden Änderungen. Es gibt zwei geringfügige Hinweise bezüglich bestehender Integrationen:

1. Veraltete HTTP-Endpunkte enthalten nun in der Antwort deprecation_warning Feld – Clients, die das Antwort-Schema streng überprüfen, sollten dieses zusätzliche Feld zulassen.
2. WebSocket command_data in values Das Feld ist veraltet, wird aber weiterhin ausgewertet; es wird empfohlen, vorrangig benannte Felder zu verwenden.

Anleitungen und Dokumentation

• Neue Tutorials: 05 Positionssteuerung, 06 Kombination (Inverse3 + Verse Grip), 07 Referenzpunkte und Montage, 08 HTTP-Fernkonfigurator, 09 WebSocket-Fernsteuerung, 10 Ereignis-Stream-Listener.
• Für jedes C++-Tutorial eine Glaze-Variante hinzufügen(cpp-glz/), die neben der bestehenden nlohmann/json-Variante existiert.
• Alle Tutorials wurden gemäß der API v3.1 überarbeitet.(Port 10001,configure.preset、Feld für den benannten Befehl、print_state() Hilfsfunktionen).
• Das alteTutorial zum „Verse Grip Stopper“ wurde entferntund durch ein neues Kombinations-Tutorial ersetzt.
• Die öffentlichen Dokumentewurden aktualisiert und umfassen nun SDK-Anleitungen, API-Referenzhandbücher und Hardware-Seiten.