Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Dies ist unser größtes Versions-Update seit der Neugestaltung der API vor einem Jahr. Mit Version 3.5.0 werden eine einheitliche 3D-Mathematik-Schicht, vollständige Unterstützung für Minverse, typisierte Ereignisströme, eine umfassende Konfigurations-API sowie eine übersichtlichere HTTP-Schnittstelle eingeführt. Zudem enthält diese Version alle Fehlerbehebungen und Verbesserungen der Benutzererfahrung, die im Laufe des letzten Jahres vorgenommen wurden.
Highlights {#highlights}
Einheitliche 3D-Mathematikebene – eine kombinierbare Transformationspipeline, die eine einheitliche Basisebene für das gerätebasierte Koordinatensystem (Frame), die Installationstransformation, die Arbeitsraumtransformation und die Navigationtransformation bereitstellt und explizite Konvertierungen zwischen lokalen, Sitzungs-, Anwendungs- und internen Räumen unterstützt.Bubble Navigation – Navigation durch Formungsbereiche (SDF-Elemente) in einem großen virtuellen Arbeitsraum mit Unterstützung für geschwindigkeitsabhängige Steuerung, kollisionserkennende Trägheit sowie optionaler Drift in Richtung des Cursors. Vollständig über HTTP und WebSocket konfigurierbar und mit Unterstützung für den Hin- und Rückweg im Anwendungsraum.Typisierte Ereignisströme – Spezielle WebSocket-Ereigniskanäle für den Gerätelebenszyklus, Sicherheitswarnungen, Kalibrierungen, den Akkustand, Warnungen zur Steuerungsrate und Hinweise zur Außerbetriebnahme.Konfigurations-API – Ein umfassendes Schlüssel-Wert-Konfigurationssystem, das HTTP-CRUD, Typhinweise, Wertebereichseinschränkungen und Beschreibungen unterstützt und die alten verschachtelten Konfigurationsdateien ersetzt.Einheitliche Gerätekonfiguration — Alle Geräte nutzen ein gemeinsames HTTP-Routing:Grundlage、Halterung、Voreinstellung、umwandeln、Filter、Handhabung、Drehmomentskalierung、Schwerkraftkompensation、Startseite_Zurück。Synchrone Kalibrierung von Minverse und Stift – Das Gerät und der Stift können nun gemeinsam kalibriert werden; die Kalibrierung bleibt gesperrt, bis der Griff tatsächlich angeschlossen ist.Verbesserungen der Benutzerfreundlichkeit bei HTTP — Indexbasierter Geräte-Selektor (keine ID erforderlich, Geräte werden anhand des Indexes angegeben), der die gleiche Anfrage-/Antwortstruktur wie WebSocket nutzt und optional aktiviert werden kann {ok, Fehler, Daten} Verpackung (?format=json) sowie Platzhalter für die Sitzungsauswahl.Neue Funktionen {#new-features}
Geräte {#devices}
Minverse – Diese Version bietet nun offizielle Unterstützung für: Geräteerkennung, Inbetriebnahme, Sicherheitsbenachrichtigungen sowie den Workflow zur Synchronisationskalibrierung.„Ruko“ und „Kingfisher“ wurden als offizielle Griff-Produkttypen anerkannt.Unterstützung für Gerätesimulatoren – Erkennung und Kommunikation mit simulierten Geräten, die parallel zur realen Hardware betrieben werden können.Schutz vor Kurzschlüssen — Ports mit ungewöhnlichem Verhalten werden automatisch gesperrt; dies kann über POST /ports/{port}/reset Zurücksetzen.Der Stift ist mit dem Herzschlag verbunden – zuverlässige Erkennung des Ein- und Ausschaltens des Griffs bei Erschütterungen.Sitzungen, Befehle und WebSocket {#sessions-commands-websocket}
Filterung und Speicherung von Sitzungskonfigurationsdateien – In der Sitzungsdeklaration werden der Name der Konfigurationsdatei und die erforderliche SDK-Version angegeben; der Dienst merkt sich diese Informationen nach dem erneuten Verbindungsaufbau; Client und Überwachungstools können Sitzungen anhand dieser Konfigurationsdatei filtern und zuordnen.Befehlspuffer nach Sitzungen – Eine langsame Sitzung blockiert nun keine anderen Sitzungen mehr.Explizite `configure`-Zuordnung für einmalige Befehle — Für jedes Gerät Grundlage、Voreinstellung、Halterung、Krafttor、Dämpfungsowie für jede Sitzung Profil und Grundlage, die sich derzeit alle in konfigurieren Dabei wird die Zuordnung zur Ausgabekonfiguration beibehalten, sodass die gesendeten und die gelesenen Inhalte in beide Richtungen übereinstimmen.Anpassbare Montagearten für Geräte — Es stehen integrierte Arbeitsbereichsvoreinstellungen zur Auswahl (Standardwerte、Vorderarm、arm_front_centered、LED-Frontleuchte、led_front_centered), es können auch explizite Umwandlungen gesendet werden; bei manueller Änderung der Installationsart wechselt die Voreinstellung automatisch zu benutzerdefiniert。Feld für den benannten Befehl — Position、Vektor、Winkel、Drehmomente ersetzt das allgemeine Werte Array.Winkelmomente festlegen ersetzt Winkelmoment festlegen(Die Singularform ist veraltet).Erweiterung des Sitzungsrahmens — Die Sitzungsrahmen der Versionen v3.0 und v3.1 enthalten nun erweiterbare Konfiguration、Zustand und Status Objekt; Zu den neuen Ausgabefeldern gehören current_cursor_force、aktuelle_Cursorposition、aktuelle Drehmomente、aktuelle Winkelposition、Kontrolldomäne、Steuerungsmodus、umwandeln、transform_velocity、noch vielfältiger config.*, sowie status.sicherheit(Standardmäßig ausgeblendet).Teilweise Aktualisierung der Transformationen — Bei der Montageart, der Arbeitsraumtransformation und der Navigationsform müssen lediglich die zu ändernden Unterfelder gesendet werden (Position、Rotation、Skala).HTTP {#http}
GET / — Serviceversion.GET/POST/DELETE /settings und /Einstellungen/* — Eine vollständige API für die Konfiguration von Schlüssel-Wert-Paaren.GET /sessions/{session} und GET/POST/DELETE /sessions/{session}/profile。GET /devices?session=<selector> — Die Gerätekoodinaten werden in den Anwendungsraum der angegebenen Sitzung umgerechnet.Indexbasierter Geräteauswähler — Man kann jedes beliebige Gerät anhand des Indexes lokalisieren, ohne die ID zu kennen (/inverse3/0/... Verweist auf die erste Seite Inverse3;inverse... (gilt für alle Geräte der Inverse-Serie).Einheitliche Anfrage-/Antwortstruktur — Der Request-Body bei POST/GET-Anfragen entspricht dem bei WebSocket Befehlsdaten JSON-Struktur; Code, der für eine bestimmte Übertragungsart geschrieben wurde, kann auch für eine andere verwendet werden.Optionale Gehäusekonstruktionen — Auf beliebigen Routen verwenden ?format=json kann sofort aktiviert werden;/Einstellungen* und GET /home_return Standardmäßig wird verwendet {ok, Fehler, Daten}。Wenn Sie die ursprüngliche Struktur benötigen, verwenden Sie bitte ?format=plain。Platzhalter für die Sitzungsauswahl — im Namen der Konfigurationsdatei *(beliebige Zeichenfolge) und ?(ein einzelnes Zeichen).Selektoren zur Dekodierung von Prozentzeichen — %2A、%3A … werden vor der Weiterleitung dekodiert.Ereignisse {#events}
in Kommunikation/Veranstaltungen/Hafen Dort wird ein spezieller WebSocket-Ereignisstrom bereitgestellt.Insgesamt 24 Ereigniskategorien, darunter Ereignisse zum Gerätelebenszyklus, Sicherheitsereignisse (Not-Aus, Fremdkörpererkennung, Stillstand), fehlgeschlagene Kalibrierungen, Batteriealarme, Sitzungswarnungen, zu niedrige/extrem niedrige Steuerungsrate, Eingabeüberprüfung und Hinweise auf die Außerbetriebnahme.Beobachtbarkeit {#observability}
Wenn die Leistungsanalyse aktiviert ist, werden die Protokollmeldungen entsprechend ihrer Schweregradstufe farblich gekennzeichnet und an Tracy weitergeleitet.Jeder HTTP-Handler verfügt über einen Tracy-Bereich.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 {#coming-in-36}
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 wird mit Version 3.6 veröffentlicht und enthält eine vollständige Dokumentation.Verbesserungen {#improvements}
Kraftschwingungsfilter – Schwingungserkennung pro Achse, 8-stufige progressive Rückstellung, Abstimmungsmechanismus mit Verzögerung sowie asymmetrisches Freigabefenster.Laufzeit-Gatterfilter — Kann über WebSocket oder HTTP genutzt werden configure.force_gate.gain Konfiguration mit persistenten Standardwerten.Die maximale Frequenz des Hauptzyklus wurde auf 32 kHz erhöht, was fürPräzisionsanwendungen ausgelegt ist.Geringere WebSocket-Last — Standardmäßig werden Unterfelder, deren Standardwert die Identitätstransformation ist, in der Ausgabe weggelassen (position = 0、Rotation = Identitätsmatrix、Maßstab = 1), wodurch die Datenmenge reduziert und die Kompatibilität mit der 4-KB-Nachrichtenlängenbeschränkung älterer Unity-Pakete wiederhergestellt wird. Zwei erweiterte Einstellungen (Serialisierung/explizite Felder、Serialisierung/Transformationen zwangsweise abschließen) 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 Hauptzyklus während der JSON-Parsierung und der Netzwerkübertragung nicht mehr; die Planung der Sitzungszyklen wurde auf den Zeitpunkt vor der Serialisierung der Antwort vorverlegt.Der Server hört standardmäßig nur auf „localhost“. — Um den Netzwerkzugriff zu aktivieren, aktivieren Sie bitte Kommunikation/Alle Schnittstellen binden Einstellungen.Die Platzhalter im Geräteauswahl-Selektor verwenden die Präfix-Syntax(zum Beispiel inverse (kompatibel mit allen Geräten der Inverse-Serie).Dämpfungsbefehl Es wurde bereits mit Krafttor Gemeinsam einziehen konfigurieren Wird zugeordnet.Der Rotations-Datei-Logger ersetzt den bisherigen Logger und unterstützt konfigurierbare Verzeichnisse.Befehle und Statusangaben von Modulen – Module können benutzerdefinierte Befehle, Konfigurationsfelder und Statusangaben in WebSocket-Frames einfügen, ohne das Kernschema ändern zu müssen.Korrekturen {#fixes}
Ein Jahr lang werden Fehler behoben; die wichtigsten davon sind im Folgenden aufgeführt.
Die Verbindungsgeschwindigkeit ist unbeständigund tritt unter bestimmten Bedingungen auf.GripHook (Verse Grip Stopper) lässt sich ohne Simulationslauf nicht ordnungsgemäß lösen.Inverse3 Die Zeitüberschreitungist zu kurz eingestellt, was dazu führt, dass Geräte mit langsamerem Start in eine Endlos-Trennungsschleife geraten.Bei Beendigung des Dienstes unter Windows wurde keine vollständige Bereinigung durchgeführt – der HTTP-Server wird beim Beenden nicht immer bereinigt.Eine Wiederverbindungsschleife tritt auf, wenn ein Dienst nicht unterstützte Befehle an eine ältere Firmware-Version sendet.Die Erkennung von Bluetooth-Gerätenerzeugt auf Systemen mit Bluetooth-Adapter eine große Menge an Protokoll-Einträgen.Bei wiederholten Neustarts des Dienstes kommt es zu einem Absturz.Der drahtlose Verse Grip-Empfänger friert ein, und zwar nach dem Wechsel in den Ruhezustand bzw. dem Aufwachen eines Ubuntu-Laptops.Der drahtlose „Verse Grip“(Linux und macOS) führt nun bei einem fehlgeschlagenen ersten Erkennungsversuch korrekt einen Rollback durch.Speicherort der MacOS-Konfigurationsdateien — Die Konfiguration wird nun gespeichert unter ~/Bibliothek/Application Support/ … und nicht der falsche Weg.SIGSEGV-Signalbehandlung 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 – Konfigurationsbefehle aus einer Sitzung konnten bisher stillschweigend durch Befehle 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 Sondenposition In diesem Fall werden die zu verarbeitenden Änderungen an Basis, Voreinstellung und Profil nicht mehr stillschweigend überschrieben.Problem bei der Anzeige des Prototyp-Griffs – Die Prototyp-Hardware wird fälschlicherweise als Standardgriff und nicht als benutzerdefinierter Griff angezeigt.Die alte Konvention für `set_basis`-Matrizentritt wieder in Kraft und steht Clients zur Verfügung, die noch nicht migriert wurden.Inverse3 Der Kraftstoß erzeugt bei einer Unterbrechung der Verbindung keine Restkraftspitzen mehr.Die Race-Condition beim Verlust der WebSocket-Verbindungtritt während eines schnellen Verbindungsaufbau- und -abbruchzyklus auf.WebSocket-`session_id` in einem Teil der externen Lasten serialisiert als 0。Unter Windows ,--Protokollstufe und --dev Bei gleichzeitiger Verwendung wird dies nun beachtet (zuvor wurde es stillschweigend zurückgesetzt auf Debug).Veraltete Elemente {#deprecations}
Es kann weiterhin normal verwendet werden, wird jedoch in einer zukünftigen Hauptversion entfernt. Gegebenenfalls enthält die Antwort Warnung vor veralteten Funktionen Feld.
| Veraltet | Ersatz |
|---|---|
| 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 auf Sitzungsebene Basis festlegen | configure.basis |
Hinweise zur Kompatibilität {#compatibility-notes}
Im Vergleich zu 3.4.19 gibt es keine zwingenden, kompatibilitätsbrechenden Änderungen. Es gibt zwei geringfügige Hinweise bezüglich bestehender Integrationen:
Veraltete HTTP-Endpunkte enthalten nun in der Antwort Warnung vor veralteten Funktionen Feld – Clients, die das Antwort-Schema streng überprüfen, sollten dieses zusätzliche Feld zulassen.WebSocket Befehlsdaten in Werte Das Feld ist veraltet, wird aber weiterhin ausgewertet; es wird empfohlen, vorrangig benannte Felder zu verwenden.Anleitungen und Dokumentation {#tutorials-documentation}
Neue Tutorials: 05 Positionssteuerung, 06 Kombiniert (Inverse3 + Verse Grip), 07 Basis und Montage, 08 HTTP-Fernkonfigurator, 09 WebSocket-Fernsteuerung, 10 Event-Stream-Listener.Neue „Glaze“-Variante hinzugefügt: Für jedes C++-Tutorial neu hinzugefügt cpp-glz/ Variante, die parallel zur bestehenden nlohmann/json-Variante existiert.Alle Tutorials wurden überarbeitet, um die API v3.1 zu unterstützen (Port 10001,Konfigurationsvoreinstellung、Feld für den benannten Befehl、print_state() Hilfsfunktionen).Das alteTutorial zum „Verse Grip Stopper“ wurde entfernt– es wurde durch das neue Tutorial zum „Combined“ ersetzt.Die öffentlichen Dokumentewurden aktualisiert und umfassen nun SDK-Anleitungen, API-Referenzhandbücher und Hardware-Seiten.
