Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Unser bisher größtes Release seit der API-Neufassung vor einem Jahr. 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 – daneben ein Jahr voller Fehlerbehebungen und Komfortverbesserungen.
Highlights {#highlights}
Einheitliche 3D-Mathematikschicht — eine kombinierbare Transformationspipeline mit erstklassigen Primitiven für Geräte-Basis (Frame), Montagetransformation, Arbeitsbereichstransformation und Navigationstransformation 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 Gerätelebenszyklus, Sicherheitswarnungen, Kalibrierung, Batteriezustand, Warnungen zur Regelrate und Hinweise auf veraltete Funktionen.Settings API — ein vollständiges Key-Value-Einstellungssystem mit HTTP-CRUD, Typhinweisen, Bereichsbeschränkungen und Beschreibungen, das die bisherige verschachtelte Konfigurationsdatei ersetzt.Einheitliche Gerätekonfiguration — ein gemeinsamer Satz an HTTP-Routen für jedes Gerät: basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.Synchronisierte Minverse- und Stift-Kalibrierung — das Gerät und sein Stift werden nun gemeinsam kalibriert; die Kalibrierung bleibt gesperrt, bis ein Griff physisch angebracht ist.Komfortverbesserungen bei HTTP — indexbasierte Geräteselektoren (Gerät per Index ansprechen, keine ID erforderlich), ein einheitliches Anfrage- und Antwortformat, das mit WebSocket geteilt wird, eine optional aktivierbare {ok, error, data}-Envelope (?format=json) und Wildcard-Sitzungsselektoren.Neue Funktionen {#new-features}
Geräte {#devices}
Minverse — offizielle Unterstützung in diesem Release: Erkennung, Bereitschaftssequenz, Sicherheitsbenachrichtigungen und der synchronisierte Kalibrierungsablauf.Ruko und Kingfisher werden als offizielle Produkttypen für Griffe erkannt.Unterstützung für Geräte-Simulatoren — 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 Stiftanbringung — zuverlässige Erkennung des Anbringens und Entfernens des Griffs, mit Entprellung.Sitzungen, Befehle & WebSocket {#sessions-commands-websocket}
Filterung und Persistenz von Sitzungsprofilen — Sitzungen deklarieren einen Profilnamen und die erforderliche SDK-Version, die der Dienst über 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 Einmalbefehle — basis, preset, mount, force_gate, damping pro Gerät sowie profile und basis pro Sitzung werden nun alle in configure geführt – abgestimmt auf die Ausgabe-Konfigurationszuordnung, sodass das Gesendete mit dem Zurückgelesenen übereinstimmt.Anpassbare Geräte-Montage — wählen Sie ein integriertes Arbeitsbereichs-Preset (defaults, arm_front, arm_front_centered, led_front, led_front_centered) oder senden Sie eine explizite Transformation; manuelle Änderungen der Montage schalten das Preset automatisch auf custom um.Benannte Befehlsfelder — position, vector, angles, torques ersetzen das generische Array values.set_angular_torques ersetzt set_angular_torque (die Singularform ist veraltet).Erweiterungen der Sitzungsframes — Sitzungsframes der Versionen v3.0 und v3.1 enthalten nun erweiterbare Objekte config, state und status; neue Ausgabefelder umfassen current_cursor_force, current_cursor_position, current_angular_torques, current_angular_position, control_domain, control_mode, transform, transform_velocity, umfangreichere config.*-Felder sowie status.safety (standardmäßig ausgeblendet).Partielle Transformationsaktualisierungen — senden Sie nur die Unterfelder, die Sie ändern möchten (position, rotation, scale) bei Montage, Arbeitsbereichstransformation und Navigationsform.HTTP {#http}
GET / — Dienstversion.GET/POST/DELETE /settings und /settings/* — vollständige Key-Value-Settings-API.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äteselektoren — jedes Gerät per Index ansprechen, ohne seine ID zu kennen (/inverse3/0/... für das erste Inverse3-Gerät; /inverse__ITALIC_italic-1__/... für alle Geräte der Inverse-Familie).Einheitliches Anfrage- und Antwortformat — die Bodies von POST- und GET-Anfragen verwenden dieselben command_data-JSON-Strukturen wie WebSocket; Code, der für den einen Transportweg geschrieben wurde, funktioniert mit dem anderen.Optionale Envelope — aktivierbar über ?format=json auf jeder Route; /settings* und GET /home_return verwenden standardmäßig {ok, error, data}. Verwenden Sie ?format=plain für die Rohstruktur.Wildcards 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 communication/events/port.24 typisierte Ereigniskategorien, darunter Gerätelebenszyklus, Sicherheit (E-Brake, Erkennung von Fremdkörpern, Blockade), Kalibrierungsfehler, Batteriewarnungen, Sitzungswarnungen, niedrige und kritische Regelrate, Eingabevalidierung und Hinweise auf veraltete Funktionen.Observability {#observability}
Log-Nachrichten werden beim Profiling mit levelabhängigen Farben an Tracy weitergeleitet.Tracy-Zonen für jeden HTTP-Handler.Ereignisse mit Timing-Statistiken der Hauptschleife.Konfigurierbares Log-Verzeichnis und konfigurierbarer Server-Hostname (Docker-freundlich).Demnächst in 3.6 {#coming-in-36}
SDF Haptic Effects (SDF HFX) — die Grundlagen wurden in 3.5 bereits geschaffen (Modul, Lebenszyklus, Serialisierung von modulseitig bereitgestellten Befehls- und Zustandsdaten); die öffentliche API wird mit vollständiger Dokumentation in 3.6 ausgeliefert.Verbesserungen {#improvements}
Filterung von Kraftschwingungen — achsenweise 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 persistentem Standardwert.Maximalfrequenz der Hauptschleife auf 32 kHz erhöht für Präzisionsanwendungen.Kleinere WebSocket-Nutzlasten — Transformations-Unterfelder mit Identitäts-Standardwert (position = 0, rotation = identity, scale = 1) werden standardmäßig nicht ausgegeben. Dadurch sinkt die Nutzlastgröße, und die Kompatibilität mit dem 4-KB-Nachrichtenlimit älterer Unity-Pakete wird wiederhergestellt. Zwei erweiterte Einstellungen (serialization/explicit_fields, serialization/force_complete_transforms) 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.Server standardmäßig nur auf localhost — Netzwerkzugriff aktivieren Sie über die Einstellung communication/bind_all_interfaces.Wildcards für Geräteselektoren nutzen Präfixsyntax (z. B. inverse* trifft alle Geräte der Inverse-Familie).Dämpfungsbefehle wurden zusammen mit force_gate in die configure-Zuordnung verschoben.Rotierender 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 das WebSocket-Frame einfügen, ohne das Kernschema anzutasten.Fehlerbehebungen {#fixes}
Ein Jahr voller Fehlerbehebungen; die wirkungsvollsten sind nachfolgend aufgeführt.
Unregelmäßige Session-Geschwindigkeit unter bestimmten Bedingungen.GripHook (Verse Grip Stopper) wurde nicht sauber freigegeben, wenn keine Simulation lief.Inverse3-Timeouts waren zu aggressiv und verursachten auf langsam hochfahrenden Geräten Verbindungsabbruch-Schleifen.Unsauberes Beenden des Dienstes auf Windows — der HTTP-Server wurde beim Herunterfahren nicht immer bereinigt.Reconnect-Schleife, wenn der Dienst nicht unterstützte Befehle an ältere Firmware-Versionen sendete.Bluetooth-Geräteaufzählung überflutete das Log auf Systemen mit Bluetooth-Adaptern.Absturz beim mehrfachen Neustart des Dienstes hintereinander.Einfrieren des Wireless-Verse-Grip-Dongles auf Ubuntu-Laptops nach Standby und Wiederaufnahme.Wireless-Verse-Grip-Handshake auf Linux und macOS greift jetzt korrekt auf den Fallback zurück, wenn der erste Erkennungsversuch fehlschlägt.Speicherort der MacOS-Konfigurationsdatei — die Konfiguration wird jetzt in ~/Library/Application Support/ gespeichert statt am falschen Pfad.SIGSEGV-Signalbehandlung auf Linux und macOS — der Prozess gerät bei fatalen Signalen nicht mehr in eine Schleife, wenn die Absturzerfassung für mehrere Threads aktiviert ist.Befehlsüberschreibung sessionübergreifend — Konfigurationsbefehle aus einer Session konnten stillschweigend durch Befehle aus einer anderen Session ersetzt werden; sie werden jetzt korrekt gefiltert und zusammengeführt.Probe-Befehle überschreiben die Konfiguration — Monitoring-Sessions (z. B. Haply Hub), die probe_position senden, überschreiben ausstehende Änderungen an Basis / Preset / Profil nicht mehr stillschweigend.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-Kraftimpuls beim Trennen der Session erzeugt keine Restkraftspitze mehr.Race Condition beim Verbindungsverlust von WebSocket während schneller Verbindungs-/Trennungszyklen.WebSocket `session_id` wurde in einigen ausgehenden Payloads als 0 serialisiert.Auf Windows wird --log-level jetzt auch zusammen mit --dev berücksichtigt (zuvor stillschweigend auf debug zurückgesetzt).Veraltete Funktionen {#deprecations}
Weiterhin funktionsfähig, wird aber in einer künftigen Hauptversion entfernt. Antworten enthalten gegebenenfalls ein Feld deprecation_warning.
| Veraltet | 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 | Settings API |
| POST /experimental/features/screensaver_enable | Settings 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 set_basis auf Session-Ebene | configure.basis |
Kompatibilitätshinweise {#compatibility-notes}
Keine harten Breaking Changes gegenüber 3.4.19. Zwei unkritische Hinweise für bestehende Integrationen:
Veraltete HTTP-Endpunkte enthalten jetzt ein Feld deprecation_warning in der Antwort – Clients, die Antwortschemata strikt validieren, sollten das zusätzliche Feld zulassen.Das Feld values in WebSocket command_data ist veraltet, wird aber weiterhin geparst. Verwenden Sie bevorzugt die benannten Felder.Tutorials & Dokumentation {#tutorials-documentation}
Neue Tutorials: 05 Positionsregelung, 06 Kombiniert (Inverse3 + Verse Grip), 07 Basis und Mount, 08 HTTP-Remote-Konfigurator, 09 WebSocket-Fernsteuerung, 10 Event-Stream-Listener.Neue Glaze-Variante jedes C++-Tutorials (cpp-glz/) neben der bestehenden nlohmann/json-Variante.Alle Tutorials überarbeitet für die v3.1-API (Port 10001, configure.preset, benannte Befehlsfelder, print_state()-Hilfsfunktionen).Entfernt: das alte Tutorial zum Verse Grip Stopper – ersetzt durch das neue kombinierte Tutorial.Öffentliche Dokumentation aktualisiert in den SDK-Anleitungen, der API-Referenz und auf den Hardware-Seiten.
