Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Unser bislang größtes Release seit der Überarbeitung der API vor einem Jahr. Version 3.5.0 führt eine einheitliche 3D-Mathematikschicht, vollständige Unterstützung für Minverse, einen typisierten Ereignisstrom, eine vollständige Settings-API und eine übersichtlichere HTTP-Schnittstelle ein – dazu kommt ein Jahr voller Fehlerbehebungen und Komfortverbesserungen.
Highlights {#highlights}
Einheitliche 3D-Mathematikschicht – eine kombinierbare Transformationspipeline mit erstklassigen Primitiven für Gerätebasis (Frame), Montage-, Arbeitsbereichs- und Navigationtransformationen sowie explizite Umrechnungen zwischen lokalen, Sitzungs-, Anwendungs- und internen Räumen.Bubble Navigation – Navigation durch große virtuelle Arbeitsbereiche ü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 Gerätelebenszyklus, Sicherheitswarnungen, Kalibrierung, Batteriestatus, Warnungen zur Abfragefrequenz und Hinweise auf veraltete Funktionen.Einstellungs-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: Grundlage, Halterung, Voreinstellung, umwandeln, Filter, Handhabung, Drehmomentskalierung, Schwerkraftkompensation, Startseite_Zurück.Synchronisierte Minverse- und Stiftkalibrierung – Das Gerät und sein Stift werden nun gemeinsam kalibriert; die Kalibrierung bleibt gesperrt, bis ein Griff physisch angebracht ist.Verbesserungen der Benutzerfreundlichkeit bei HTTP — indexbasierte Geräteselektoren (Ansprechen eines Geräts über einen Index, keine ID erforderlich), ein einheitliches Anfrage- und Antwortformat, das mit WebSocket gemeinsam genutzt wird, eine optional aktivierbare {ok, Fehler, Daten}-Umschlag (?format=json) und Wildcard-Sitzungsselektoren.Neue Funktionen {#new-features}
Geräte {#devices}
Minverse – offizielle Unterstützung in dieser Version: Erkennung, Startsequenz, Sicherheitsbenachrichtigungen und der synchronisierte Kalibrierungsablauf.Ruko und Kingfisher werden als offizielle Produkttypen für Griffe erkannt.Unterstützung für Gerätesimulatoren – softwaresimulierte Geräte erkennen und mit ihnen kommunizieren, neben echter Hardware.Schutz vor Verbindungsschleifen — Ports mit fehlerhaftem Verhalten werden automatisch gesperrt; Zurücksetzen mit POST /ports/{port}/reset.Heartbeat für die Stiftbefestigung – zuverlässige Erkennung des Anbringens und Entfernens des Griffs, mit Entprellung.Sitzungen, Befehle & WebSocket {#sessions-commands-websocket}
Filterung und Persistenz von Sitzungsprofilen — Sitzungen geben einen Profilnamen und die erforderliche SDK-Version an, die der Dienst über mehrere Wiederverbindungen hinweg 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 ausbremsen.Explizite `configure`-Zuordnung für einmalige Befehle — Grundlage, Voreinstellung, Halterung, Krafttor, Dämpfung pro Gerät sowie Profil und Grundlage Pro Sitzung werden nun alle in konfigurieren durchgeführt – abgestimmt auf die Zuordnung der Ausgabekonfiguration, sodass das Gesendete mit dem Zurückgelesenen übereinstimmt.Flexible Gerätemontage — Wählen Sie eine integrierte Arbeitsbereichsvoreinstellung (Standardwerte, Vorderarm, arm_front_centered, LED-Frontleuchte, led_front_centered) oder senden Sie eine explizite Transformation; bei manuellen Änderungen an der Montage wird das Preset automatisch auf benutzerdefiniert Ähm.Benannte Befehlsfelder — Position, Vektor, Winkel, Drehmomente ersetzen das generische Array Werte.Winkelmomente festlegen ersetzt Winkelmoment festlegen (Die Singularform ist veraltet).Erweiterungen der Sitzungsframes — Sitzungsframes der Versionen v3.0 und v3.1 enthalten nun erweiterbare Objekte Konfiguration, Zustand und Status; neue Ausgabefelder umfassen current_cursor_force, aktuelle_Cursorposition, aktuelle Drehmomente, aktuelle Winkelposition, Kontrolldomäne, Steuerungsmodus, umwandeln, transform_velocity, umfangreichere config.*-Felder sowie status.sicherheit (standardmäßig ausgeblendet).Teilweise Aktualisierungen der Transformationen — Senden Sie nur die Unterfelder, die Sie ändern möchten (Position, Rotation, Skala) bei der Montage, der Arbeitsbereichstransformation und der Navigationsform.HTTP {#http}
GET / — Dienstversion.GET/POST/DELETE /settings und /Einstellungen/* — vollständige Key-Value-Settings-API.GET /sessions/{session} und GET/POST/DELETE /sessions/{session}/profile.GET /devices?session=<selector> — Gerätekoordinaten in den Anwendungsbereich einer bestimmten Sitzung umrechnen.Indexbasierte Geräteselektoren — jedes Gerät über einen Index ansprechen, ohne dessen ID zu kennen (/inverse3/0/... für das erste „ Inverse3 “-Gerät; inverse... (für alle Geräte der Inverse-Familie).Einheitliches Format für Anfragen und Antworten — Die Body-Teile von POST- und GET-Anfragen sind identisch Befehlsdaten-JSON-Strukturen wie WebSocket; Code, der für den einen Übertragungsweg geschrieben wurde, funktioniert auch mit dem anderen.Optionaler Umschlag — aktivierbar über ?format=json auf jeder Strecke; /Einstellungen* und GET /home_return verwenden standardmäßig {ok, Fehler, Daten}. Verwenden Sie ?format=plain für die Rohstruktur.Platzhalter in Sitzungsselektoren — * (beliebige Zeichenfolge) und ? (einzelnes Zeichen) in Profilnamen.Selektoren mit Prozentkodierung — %2A, %3A usw. werden vor dem Routing dekodiert.Ereignisse {#events}
Dedizierter WebSocket-Ereignisstrom auf Kommunikation/Veranstaltungen/Hafen.24 standardisierte Ereigniskategorien, darunter Gerätelebenszyklus, Sicherheit (E-Brake, Erkennung von Fremdkörpern, Blockade), Kalibrierungsfehler, Akkuwarnungen, Sitzungswarnungen, niedrige und kritische Regelrate, Eingabevalidierung sowie Hinweise auf veraltete Funktionen.Beobachtbarkeit {#observability}
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).Demnächst in 3.6 {#coming-in-36}
SDF Haptic Effects (SDF HFX) – die Grundlagen wurden bereits in Version 3.5 geschaffen (Modul, Lebenszyklus, Serialisierung der vom Modul bereitgestellten Befehls- und Zustandsdaten); die öffentliche API wird in Version 3.6 mit vollständiger Dokumentation ausgeliefert.Verbesserungen {#improvements}
Filterung von Kraftschwingungen – achsweise Schwingungserkennung, achtstufige, abgestufte Wiederherstellung, Eintrittsabstimmung mit Hysterese und asymmetrische Freigabefenster.Force-Gate-Filter zur Laufzeit — konfigurierbar über configure.force_gate.gain, über WebSocket oder HTTP, mit persistenter Standardwert.Die maximale Frequenz der Hauptschleife wurde für Präzisionsanwendungen auf 32 kHz erhöht.Kleinere WebSocket-Nutzdaten — Transformations-Unterfelder mit Standardwert für die Identität (position = 0, Rotation = Identitätsmatrix, Maßstab = 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 (Serialisierung/explizite Felder, Serialisierung/Transformationen zwangsweise abschließen) nehmen alle Felder wieder auf, für Clients, die diese benötigen.Geringerer Jitter der Hauptschleife – die WebSocket-Nachrichtenverarbeitung blockiert den Takt der Hauptschleife während des JSON-Parsings und des Netzwerkversands nicht mehr; die Taktplanung der Sitzungen wurde vor die Serialisierung der Antworten verlegt.Der Server läuft standardmäßig nur auf „localhost“ — Den Netzwerkzugriff aktivieren Sie über die Einstellung Kommunikation/Alle Schnittstellen binden.Bei der Verwendung von Platzhaltern für Geräteselektoren wird die Präfixsyntax verwendet (z. B. inverse (gilt für alle Geräte der Inverse-Familie).Dämpfungsbefehle wurden zusammen mit Krafttor in die konfigurieren-Zuordnung verschoben.Der rotierende Datei-Logger ersetzt den bisherigen und unterstützt ein konfigurierbares Verzeichnis.Von Modulen bereitgestellte Befehle und Zustände — Module können eigene Befehle einbringen, Felder konfigurieren und Zustandsausgaben in den WebSocket-Frame einfügen, ohne das Kernschema zu verändern.Fehlerbehebungen {#fixes}
Ein Jahr voller Fehlerbehebungen; die wirkungsvollsten sind im Folgenden aufgeführt.
Unregelmäßige Sitzungsgeschwindigkeit unter bestimmten Bedingungen.GripHook (Verse Grip Stopper) wurde nicht ordnungsgemäß freigegeben, wenn keine Simulation lief.Inverse3-Die Timeouts waren zu aggressiv und führten auf Geräten, die nur langsam hochfuhren, zu Endlosschleifen bei Verbindungsabbrüchen.Unkorrektes Beenden des Dienstes unter Windows – der HTTP-Server wurde beim Herunterfahren nicht immer ordnungsgemäß bereinigt.Reconnect-Schleife, wenn der Dienst Befehle an ältere Firmware-Versionen gesendet hat, die nicht unterstützt wurden.Die Auflistung der Bluetooth-Geräte überflutete das Protokoll auf Systemen mit Bluetooth-Adaptern.Absturz beim wiederholten Neustart des Dienstes hintereinander.Einfrieren des Wireless-Verse-Grip-Dongles auf Ubuntu-Laptops nach dem Standby-Modus und der Wiederaufnahme.„Wireless-Verse-Grip-Handshake“ 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 ~/Bibliothek/Application Support/ gespeichert statt unter dem falschen Pfad.SIGSEGV-Signalbehandlung unter Linux und macOS – Der Prozess gerät bei fatalen Signalen nicht mehr in eine Schleife, wenn die Absturzprotokollierung für mehrere Threads aktiviert ist.Überschreiben von Befehlen über Sitzungen hinweg — Konfigurationsbefehle aus einer Sitzung konnten 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 Sondenposition 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 ältere `set_basis`-Matrixkonvention wird für Clients, die noch nicht migriert wurden, wieder berücksichtigt.Inverse3- Der Kraftimpuls beim Beenden der Sitzung erzeugt keine Restkraftspitze mehr.Race Condition bei Verbindungsverlust des WebSockets während schneller Verbindungs-/Trennungszyklen.WebSocket-`session_id` wurde in einigen ausgehenden Payloads als 0 serialisiert.Auf Windows wird --Protokollstufe jetzt auch zusammen mit --dev berücksichtigt (zuvor stillschweigend auf Debug zurückgesetzt).Veraltete Funktionen {#deprecations}
Weiterhin funktionsfähig, wird jedoch in einer zukünftigen Hauptversion entfernt. Antworten enthalten gegebenenfalls ein Feld Warnung vor veralteten Funktionen.
| 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 Basis festlegen auf Session-Ebene | configure.basis |
Kompatibilitätshinweise {#compatibility-notes}
Keine gravierenden Kompatibilitätsänderungen gegenüber 3.4.19. Zwei unkritische Hinweise für bestehende Integrationen:
Veraltete HTTP-Endpunkte enthalten nun ein Feld Warnung vor veralteten Funktionen in der Antwort – Clients, die Antwortschemata streng validieren, sollten das zusätzliche Feld zulassen.Das Feld Werte in WebSocket Befehlsdaten ist veraltet, wird aber weiterhin ausgewertet. Verwenden Sie vorzugsweise die benannten Felder.Anleitungen & Dokumentation {#tutorials-documentation}
Neue Tutorials: 05 Positionsregelung, 06 Kombiniert (Inverse3 + Verse Grip), 07 Basis und Halterung, 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 überarbeitet für die v3.1-API (Port 10001, Konfigurationsvoreinstellung, benannte Befehlsfelder, print_state()-Hilfsfunktionen).Entfernt: das alte Tutorial zum Verse Grip Stopper – ersetzt durch das neue kombinierte Tutorial.Die öffentliche Dokumentation wurde in den SDK-Anleitungen, der API-Referenz und auf den Hardware-Seiten aktualisiert.
