Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Dies ist die umfangreichste Version seit der Neugestaltung der API vor einem Jahr. In Version 3.5.0 wurden eine integrierte 3D-Mathematik-Ebene, vollständige Unterstützung für Minverse, typisierte Ereignisströme, eine umfassende Konfigurations-API sowie eine übersichtlichere HTTP-Schnittstelle eingeführt. Darüber hinaus enthält sie die im Laufe des letzten Jahres vorgenommenen Fehlerbehebungen und Verbesserungen der Benutzerfreundlichkeit.
Die wichtigsten Highlights {#highlights}
Integrierte 3D-Mathematik-Ebene – Eine kombinierbare Transformationspipeline, die Gerätebasis (Frame), Befestigungstransformationen, Arbeitsraumtransformationen und Navigationtransformationen als grundlegende Elemente erster Ordnung bereitstellt und zudem explizite Transformationen zwischen lokalen, Sitzungs-, Anwendungs- und internen Räumen unterstützt.Bubble Navigation – Erkundet einen großen virtuellen Arbeitsbereich mithilfe von Formbereichen (SDF-Primitive), die auf Geschwindigkeitskartierung basierende Geschwindigkeitssteuerung, eine Hysterese berücksichtigende Kollisionserkennung sowie eine wählbare Cursor-Richtungsdrift bieten. Vollständig konfigurierbar über HTTP und WebSocket und unterstützt Round-Trip-Kommunikation im App-Bereich.Typ-spezifischer Ereignisstrom – Ein dedizierter WebSocket-Ereigniskanal für den Lebenszyklus von Geräten, Sicherheitshinweise, Kalibrierungen, Akkus, Warnungen zu Steuerungszyklen und Hinweise zur Einstellung der Unterstützung (Deprecation).Einstellungs-API – Ein umfassendes Schlüssel-Wert-Einstellungssystem, das HTTP-CRUD, Typ-Hinweise, Bereichseinschränkungen und Beschreibungen unterstützt und die bisherigen verschachtelten Konfigurationsdateien ersetzt.Einheitliche Gerätekonfiguration — Es wird ein Satz von HTTP-Routen bereitgestellt, der für alle Geräte gilt: Grundlage, Halterung, Voreinstellung, umwandeln, Filter, Handhabung, Drehmomentskalierung, Schwerkraftkompensation, Startseite_Zurück.Minverse und Stift-Synchronisationskalibrierung — Gerät und Stift werden nun gemeinsam kalibriert, und der Kalibrierungsstatus bleibt gesperrt, bis der Griff physisch angeschlossen ist.Verbesserung der Benutzerfreundlichkeit HTTP — Indexbasierter Geräte-Selektor (Geräte werden über einen Index statt über eine ID angegeben), ein einheitliches Anfrage-/Antwortformat, das mit WebSocket geteilt wird, sowie optional nutzbare {ok, Fehler, Daten} Envelope (?format=json), bietet Wildcard-Sitzungsselektoren.Neue Funktionen {#new-features}
Geräte {#devices}
Minverse – Mit dieser Version wurden folgende Funktionen offiziell hinzugefügt: Erkennung, Vorbereitungssequenz, Sicherheitshinweise und synchronisierte Kalibrierungsabläufe.Ruko und Kingfishergelten als offizielle Griff-Produkttypen.Unterstützung für Gerätesimulatoren – Es können sowohl reale Hardware als auch per Software simulierte Geräte erkannt und mit diesen kommuniziert werden.Schutz vor Verbindungsschleifen — Fehlerhafte Ports werden automatisch gesperrt, und POST /ports/{port}/resetkann auf zurückgesetzt werden.Stiftverbindung „Heartbeat“ – Durch den Einsatz von Debounce wird das Anschließen und Trennen des Griffs zuverlässig erkannt.Sitzungen, Befehle und WebSocket {#sessions-commands-websocket}
Filterung und Persistenz von Sitzungsprofilen — Eine Sitzung enthält den Profilnamen und die erforderliche SDK-Version; der Dienst speichert diese Informationen auch nach einer erneuten Verbindung. Clients und Überwachungstools können Sitzungen anhand dieses Profils filtern und als Ziel festlegen.Befehlspuffer pro Sitzung – Eine langsame Sitzung verzögert andere Sitzungen nicht mehr.Explizite `configure`-Zuordnung für einmalige Befehle — nach Gerät Grundlage, Voreinstellung, Halterung, Krafttor, Dämpfungund pro Sitzung Profil sowie GrundlageDas ist nun alles konfigurierenist darin enthalten. Da es auf die Ausgabekonfigurationszuordnung abgestimmt ist, wird der übermittelte Inhalt beim späteren Abrufen in derselben Form zurückgegeben.Benutzerdefinierte Geräte einbinden — Integrierte Arbeitsbereichsvoreinstellungen (Standardwerte, Vorderarm, arm_front_centered, LED-Frontleuchte, led_front_centered) Sie können eine der Optionen auswählen oder eine explizite Transformation übermitteln. Wenn Sie die Zuordnung manuell ändern, wird die Voreinstellung automatisch benutzerdefiniertwird umgeschaltet.Benannte Befehlsfelder — Position, Vektor, Winkel, Drehmomenteist universell einsetzbar Werte Ersetzt das Array.Winkelmomente festlegenga Winkelmoment festlegenersetzt (die Singularform wird nicht mehr unterstützt).Erweiterung des Sitzungsrahmens — Erweiterbar auf die Session-Frames v3.0 und v3.1 Konfiguration, Zustand, Status Es enthält Objekte. Das neue Ausgabefeld enthält current_cursor_force, aktuelle_Cursorposition, aktuelle Drehmomente, aktuelle Winkelposition, Kontrolldomäne, Steuerungsmodus, umwandeln, transform_velocity, noch reichhaltiger config.*, und status.sicherheit(standardmäßig ausgeblendet) ist enthalten.Teilweise Aktualisierung der Transformation — Mount, Arbeitsbereich „transform“, Unterfelder, die in der Navigationsstruktur geändert werden sollen (Position, Rotation, Skala) können nur übertragen werden.HTTP {#http}
GET / — Dies ist eine Service-Version.GET/POST/DELETE /settings sowie /Einstellungen/* — Dies ist die API für alle Schlüssel-Wert-Einstellungen.GET /sessions/{session} sowie GET/POST/DELETE /sessions/{session}/profile.GET /devices?session=<selector> — Wandelt die Gerätekoodinaten in den Anwendungsraum der angegebenen Sitzung um.Indexbasierter Geräteauswähler — Auch wenn die ID nicht bekannt ist, kann ein beliebiges Gerät über den Index angegeben werden (im Fall des ersten Inverse3 /inverse3/0/..., Alle Geräte der Inverse-Serie sind inverse...).Einheitliches Anfrage-/Antwortformat — Der POST-/GET-Body entspricht dem von WebSocket Befehlsdaten Da das JSON-Format verwendet wird, funktioniert der für eine Übertragungsart geschriebene Code auch bei anderen Übertragungsarten.Selektive Hüllkurve — auf allen Routen ?format=jsonkann aktiviert werden. /Einstellungen* sowie GET /home_returnist grundsätzlich {ok, Fehler, Daten} Verwenden Sie den Typ. Um den Rohtyp zu verwenden, ?format=plainBitte geben Sie dies an.Sitzungsselektor-Platzhalter — Aus dem Profilnamen *(beliebige Zeichenfolge) und ?(Einzelzeichen) können verwendet werden.Prozentual entschlüsselte Selektoren — %2A, %3A Diese werden vor dem Routing dekodiert.Veranstaltungen {#events}
Kommunikation/Veranstaltungen/HafenEs handelt sich um einen dedizierten WebSocket-Ereignisstrom, der dort bereitgestellt wird.Es werden 24 festgelegte Ereigniskategorien bereitgestellt, darunter Gerätelebenszyklus, Sicherheit (E-Bremse, Fremdkörpererkennung, Stillstand (Stall)), Kalibrierungsfehler, Akkuwarnung, Sitzungswarnung, niedrige und kritische Steuerzyklen, Eingabevalidierung sowie Hinweise zur Einstellung des Supports.Beobachtbarkeit (Observability) {#observability}
Beim Profiling werden die Protokollmeldungen zusammen mit den stufenbezogenen Farben an Tracy übermittelt.Für alle HTTP-Handler gilt die Tracy-Zone.Dies ist ein Ereignis zur Erfassung von Zeitstatistiken für die Hauptschleife.Sie können das Protokollverzeichnis und den Servernamen konfigurieren (Docker-kompatibel).Wird in Version 3.6 verfügbar sein {#coming-in-36}
Die Arbeiten an SDF Haptic Effects (SDF HFX) wurden in Version 3.5 berücksichtigt (Module, Lebenszyklus, von den Modulen bereitgestellte Befehls- und Zustandsserialisierung). Die öffentliche API wird voraussichtlich in Version 3.6 zusammen mit der vollständigen Dokumentation bereitgestellt.Verbesserungen {#improvements}
Kraft-Schwingungsfilterung – umfasst die Erkennung von Schwingungen pro Achse, eine 8-stufige schrittweise Rückstellung, eine Einstiegsabstimmung mit Hysterese sowie einen asymmetrischen Entlastungsabschnitt.Force-Gate-Filter zur Laufzeit — über WebSocket oder HTTP configure.force_gate.gainkann zusammengestellt werden und unterstützt dauerhafte Standardwerte.Für Präzisionsanwendungen wurde die maximale Frequenz der Hauptschleife auf 32 kHz erhöht.Kleineres WebSocket-Payload — Unterfeld „transform“ mit dem Standardwert „Identität“ (position = 0, Rotation = Identitätsmatrix, Maßstab = 1) wird standardmäßig in der Ausgabe weggelassen, wodurch sich die Nutzdatengröße verringert und die Kompatibilität mit der 4-KB-Nachrichtenbeschränkung älterer Unity-Pakete wiederhergestellt wird. Zwei erweiterte Einstellungen (Serialisierung/explizite Felder, Serialisierung/Transformationen zwangsweise abschließen) können Sie alle Felder erneut einfügen, damit die Verbraucher, die diese Werte benötigen, darauf zugreifen können.Reduzierung des Jitters in der Hauptschleife — Die Verarbeitung von WebSocket-Nachrichten blockiert die Ticks der Hauptschleife auch während der JSON-Analyse und der Netzwerkübertragung nicht. Die Planung der Sitzungs-Ticks wurde vor die Serialisierung der Antworten verlegt.Die Server-Standardeinstellung gilt ausschließlich für „localhost“. — Kommunikation/Alle Schnittstellen binden In den Einstellungen können Sie den Netzwerkzugriff ausdrücklich zulassen.Platzhalter für Geräteauswahl verwenden die Präfix-Syntax(Beispiel: inverse(ist mit allen Geräten der Inverse-Serie kompatibel).Dämpfungsbefehldies Krafttorzusammen mit konfigurieren Sie wurden zur Karte weitergeleitet.Der Rotations-Datei-Loggerersetzt den bisherigen Logger und ermöglicht die Einrichtung von Verzeichnissen.Vom Modul bereitgestellte Befehle und Zustände — Das Modul kann eigene Befehle einfügen, Felder konfigurieren und Zustandsausgaben zu WebSocket-Frames hinzufügen, ohne das Kernschema zu verändern.Änderungen {#fixes}
Es handelt sich um die im Laufe eines Jahres gesammelten Fehlerbehebungen; die wichtigsten Punkte sind im Folgenden aufgeführt.
Ein Problem, bei dem unter bestimmten Bedingungen Unregelmäßigkeiten bei der Sitzungsgeschwindigkeit auftraten.Ein Problem, bei dem der GripHook (Verse Grip Stopper) nicht korrekt gelöst wurde, wenn die Simulation nicht lief.Inverse3 Das Problem, dassdas Timeoutzu kurz war und auf Geräten mit langsamer Systemstartzeit wiederholt zu Verbindungsabbrüchen führte.Windows Ungewöhnliche Beendigung des Dienstes – Der HTTP-Server wurde beim Beenden nicht immer ordnungsgemäß bereinigt.Eine Wiederverbindungsschleife, die auftrat, wenn der Dienst Befehle übermittelte, die von der älteren Firmware-Version nicht unterstützt wurden.Ein Problem, bei dem die Auflistung von Bluetooth-Gerätenauf Systemen mit Bluetooth-Adapter das Protokoll übermäßig füllte.Ein Absturz, der auftrat, wenn der Dienst mehrmals hintereinander neu gestartet wurde.Nach dem Ruhezustand trat auf einem Ubuntu-Laptop ein Absturz des „Wireless Verse Grip“-Dongles auf.Unter Linux und macOS erfolgt nun ein korrekter Fallback, selbst wenn der Handshake mit dem Wireless Verse Gripbeim ersten Versuch fehlschlägt.Speicherort der MacOS-Einstellungsdateien — Die Einstellung verwendet nun statt des falschen Pfads ~/Bibliothek/Application Support/wird dort gespeichert.Behandlung des SIGSEGV-Signals unter Linux und macOS – Wenn die Erfassung von Multithread-Konflikten aktiviert ist, gerät der Prozess bei einem fatalen Signal nicht mehr in eine Endlosschleife.Überschreiben von Befehlen zwischen Sitzungen – Früher konnten die Konfigurationsbefehle einer Sitzung stillschweigend durch Befehle einer anderen Sitzung ersetzt werden, doch nun werden sie ordnungsgemäß gefiltert und zusammengeführt.Problem: Der „Probe“-Befehl überschreibt die Einstellungen — in einer Überwachungssitzung (z. B. „ Haply Hub“) Sondenposition Selbst wenn ein Befehl gesendet wird, werden ausstehende Änderungen an Basis, Voreinstellung oder Profil nicht mehr stillschweigend überschrieben.Anzeige des Prototyp-Griffs — Die Prototyp-Hardware wurde fälschlicherweise mit einem Standardgriff anstelle eines benutzerdefinierten Griffs angezeigt.Für Clients, die noch nicht migriert wurden, wurde eine Anpassung vorgenommen, sodass die alte `set_basis`-Matrixregelwieder gilt.Beim Trennen der Sitzung treten bei „Inverse3 “und „Force Kick“keine Restkraftspitzen mehr auf.Eine Race-Condition beim Verlust der WebSocket-Verbindung, die während schneller Verbindungsaufbau- und -abbauzyklen auftrat.In einigen Übertragungsnutzdaten WebSocket-`session_id` Der Wert 0Das Problem, dass es serialisiert wurde.Unter Windows --dev In Verbindung mit der Option --Protokollstufe Die Option wird nun korrekt angewendet (zuvor wurde sie stillschweigend Debug (auf Level zurückgesetzt).Veraltete Elemente {#deprecations}
Es funktioniert zwar noch, wird aber in einer zukünftigen Hauptversion entfernt. Falls zutreffend, geben Sie in Ihrer Antwort an: Warnung vor veralteten Funktionen Es enthält Felder.
| Auslaufende Artikel | Ersatzartikel |
|---|---|
| POST /force_scale | POSTinverse |
| 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 | Einstellungen-API |
| POST /experimental/features/screensaver_enable | Einstellungen-API |
| WebSocket command_data.values | Position, Vektor, Winkel, Drehmomente |
| WebSocket Winkelmoment festlegen | Winkelmomente festlegen |
| WebSocket Cursorposition abfragen | Sondenposition |
| WebSocket set_coordinate_origin | Konfigurationsvoreinstellung |
| WebSocket-Ebene Basis festlegen | configure.basis |
Hinweise zur Kompatibilität {#compatibility-notes}
Für den 3.4.19 gibt es keine Änderungen, die zu einer Kompatibilitätsbeeinträchtigung führen. Für bestehende Integrationen sind zwei Punkte zu beachten:
In den Antworten von nicht mehr verwendeten HTTP-Endpunkten wird nun Warnung vor veralteten Funktionen Es enthält Felder. Clients, die das Antwortschema streng validieren, müssen diese zusätzlichen Felder zulassen.WebSocket Befehlsdatenvon Werte Das Feld wurde zwar nicht mehr verwendet, wird aber weiterhin ausgewertet. Es wird empfohlen, benannte Felder zu verwenden.Tutorials und Dokumentation {#tutorials-documentation}
Neue Tutorials: 05 Positionssteuerung, 06 Integration (Inverse3 +Verse Grip), 07 Basis und Mount, 08 HTTP-Fernkonfigurator, 09 WebSocket-Fernsteuerung, 10 Event-Stream-Listener.Neue Glaze-Version: Neben der bisherigen nlohmann/json-Version wird in allen C++-Tutorials die Glaze-Version (cpp-glz/) wurde hinzugefügt.Alle Tutorials überarbeiten: API v3.1 (Port 10001, Konfigurationsvoreinstellung, benanntes Befehlsfeld, print_state() Es wurde entsprechend den Vorgaben des „Helpers“ überarbeitet.Das bisherige Tutorial zu „Verse Grip Stopper“ wurde gelöscht– es wurde durch ein neues, umfassendes Tutorial ersetzt.Wir haben die öffentlichen Dokumente– darunter das SDK-Handbuch, die API-Referenz und die Hardware-Seiten – umfassend aktualisiert.
