Haply Inverse SDK 3.5.0
Notre plus grande version depuis la réécriture de l'API, il y a un an. La version 3.5.0 introduit une couche mathématique 3D unifiée, une prise en charge complète de Minverse, un flux d'événements typé, une API de paramètres complète et une interface HTTP plus épurée — en plus d'une année de corrections de bogues et d'améliorations de convivialité.
Faits saillants
Couche mathématique 3D unifiée — un pipeline de transformation composable doté de primitives de premier ordre pour la base de l'appareil (frame), la transformation de montage, la transformation de l'espace de travail et la transformation de navigation, ainsi que des conversions explicites entre les espaces local, de session, d'application et interne.Navigation par bulles — naviguer dans de grands espaces de travail virtuels à travers des zones de forme définie (primitives SDF), avec un contrôle du débit proportionnel à la vitesse, une détection de collision tenant compte de l'hystérésis et une dérive facultative vers le curseur. Entièrement configurable via HTTP et WebSocket, avec aller-retour dans l'espace de l'application.Flux d'événements typé — un canal d'événements WebSocket dédié au cycle de vie des appareils, aux alertes de sécurité, à l'étalonnage, à la batterie, aux avertissements de cadence de contrôle et aux avis de dépréciation.API de paramètres — un système complet de paramètres clé-valeur avec opérations CRUD HTTP, indications de type, contraintes de plage et descriptions, qui remplace l'ancien fichier de configuration imbriqué.Configuration cohérente des appareils — un seul ensemble de routes HTTP pour chaque appareil : basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.Étalonnage synchronisé de Minverse et du stylet — l'appareil et son stylet s'étalonnent maintenant ensemble; l'étalonnage reste verrouillé tant qu'une poignée n'est pas physiquement fixée.Améliorations de convivialité pour HTTP — sélecteurs d'appareils par index (cibler un appareil par son index, sans ID requis), structure de requête et de réponse unifiée partagée avec WebSocket, enveloppe {ok, error, data} à activer (?format=json) et sélecteurs de session à caractère générique.Nouvelles fonctionnalités
Appareils
Minverse — prise en charge officielle incluse dans cette version : détection, séquence de préparation, notifications de sécurité et flux d'étalonnage synchronisé.Ruko et Kingfisher reconnus comme types de produits de poignée officiels.Prise en charge des simulateurs d'appareils — détection et communication avec des appareils simulés par logiciel, en parallèle du matériel réel.Protection contre les boucles de connexion — les ports défaillants sont bloqués automatiquement; réinitialisation avec POST /ports/{port}/reset.Signal de présence de la fixation du stylet — détection fiable de la fixation et du retrait de la poignée, avec anti-rebond.Sessions, commandes et WebSocket
Filtrage et persistance des profils de session — les sessions déclarent un nom de profil et la version du SDK requise, que le service mémorise d'une reconnexion à l'autre; les clients et les outils de surveillance peuvent filtrer et cibler les sessions selon ce profil.Tampons de commandes par session — une session lente ne peut plus bloquer une autre.Dictionnaire `configure` explicite pour les commandes ponctuelles — basis, preset, mount, force_gate, damping par appareil, ainsi que profile et basis par session, désormais tous regroupés dans configure — aligné sur le dictionnaire de configuration de sortie, de sorte que ce que vous envoyez corresponde à ce que vous relisez.Montage d'appareil personnalisable — choisissez un préréglage d'espace de travail intégré (defaults, arm_front, arm_front_centered, led_front, led_front_centered) ou envoyez une transformation explicite; toute modification manuelle du montage bascule automatiquement le préréglage sur custom.Champs de commande nommés — position, vector, angles, torques remplacent le tableau générique values.set_angular_torques remplace set_angular_torque (le singulier est déprécié).Extensions des trames de session — les trames de session v3.0 et v3.1 portent désormais des objets extensibles config, state et status; les nouveaux champs de sortie comprennent current_cursor_force, current_cursor_position, current_angular_torques, current_angular_position, control_domain, control_mode, transform, transform_velocity, des config.* enrichis et status.safety (masqué par défaut).Mises à jour partielles des transformations — n'envoyez que les sous-champs que vous voulez modifier (position, rotation, scale) pour le montage, la transformation de l'espace de travail et la forme de navigation.HTTP
GET / — version du service.GET/POST/DELETE /settings et /settings/* — API complète de paramètres clé-valeur.GET /sessions/{session} et GET/POST/DELETE /sessions/{session}/profile.GET /devices?session=<selector> — convertit les coordonnées des appareils dans l'espace d'application d'une session donnée.Sélecteurs d'appareils par index — ciblez n'importe quel appareil par son index, sans connaître son identifiant (/inverse3/0/... pour le premier Inverse3; /inverse__ITALIC_italic-1__/... pour tous les appareils de la famille Inverse).Structure de requête et de réponse unifiée — les corps POST/GET utilisent les mêmes structures JSON command_data que WebSocket; le code écrit pour un transport fonctionne avec l'autre.Enveloppe facultative via ?format=json sur toute route; /settings* et GET /home_return utilisent {ok, error, data} par défaut. Utilisez ?format=plain pour obtenir la structure brute.Caractères génériques dans les sélecteurs de session — * (toute suite de caractères) et ? (un seul caractère) dans les noms de profil.Sélecteurs décodés en pourcentage — %2A, %3A, etc. sont décodés avant le routage.Événements
Flux d'événements dédié WebSocket sur communication/events/port.24 catégories d'événements typées, incluant le cycle de vie des appareils, la sécurité (frein d'urgence, détection d'objets étrangers, calage), les échecs d'étalonnage, les alertes de batterie, les avertissements de session, la fréquence de commande faible ou critique, la validation des entrées et les avis de dépréciation.Observabilité
Messages de journalisation transmis à Tracy, avec couleurs selon le niveau, lors du profilage.Zones Tracy sur chaque gestionnaire HTTP.Événements de statistiques de temps de la boucle principale.Répertoire de journalisation et nom d'hôte du serveur configurables (adapté à Docker).À venir dans la version 3.6
Effets haptiques SDF (SDF HFX) — les fondations ont été posées dans la version 3.5 (module, cycle de vie, sérialisation des commandes et de l'état fournie par les modules), et l'API publique sera livrée avec une documentation complète dans la version 3.6.Améliorations
Filtrage des oscillations de force — détection des oscillations par axe, récupération progressive en 8 étapes, vote d'entrée avec hystérésis et fenêtres de relâchement asymétriques.Filtre force-gate à l'exécution — configurable au moyen de configure.force_gate.gain via WebSocket ou HTTP, avec une valeur par défaut persistante.Fréquence maximale de la boucle principale portée à 32 kHz pour les applications de précision.Charges utiles WebSocket réduites — les sous-champs de transformation dont la valeur par défaut est l'identité (position = 0, rotation = identity, scale = 1) sont omis de la sortie par défaut, ce qui réduit la taille des charges utiles et rétablit la compatibilité avec la limite de 4 Ko des messages des anciens paquets Unity. Deux paramètres avancés (serialization/explicit_fields, serialization/force_complete_transforms) réintègrent tous les champs pour les consommateurs qui en ont besoin.Gigue réduite de la boucle principale — le traitement des messages WebSocket ne bloque plus le cycle de la boucle principale pendant l'analyse JSON et l'envoi réseau; la planification des cycles de session a été placée avant la sérialisation des réponses.Les serveurs sont par défaut limités à localhost — activez l'accès réseau avec le paramètre communication/bind_all_interfaces.Les caractères génériques des sélecteurs d'appareils utilisent la syntaxe de préfixe (p. ex. inverse* correspond à tous les appareils de la famille Inverse).Les commandes d'amortissement ont été déplacées dans l'objet configure, à côté de force_gate.Journalisation à fichiers rotatifs remplace la précédente, avec un répertoire configurable.Commandes et état apportés par les modules — les modules peuvent injecter leurs propres commandes, des champs de configuration et une sortie d'état dans la trame WebSocket sans modifier le schéma de base.Corrections
Une année de corrections de bogues; les plus importantes figurent ci-dessous.
Vitesse de session irrégulière dans certaines conditions.GripHook (Verse Grip Stopper) ne se relâchait pas proprement lorsqu'aucune simulation n'était en cours.Délais d'attente Inverse3 étaient trop agressifs et causaient des boucles de déconnexion sur les appareils à démarrage lent.Arrêt incorrect du service Windows — le serveur HTTP n'était pas toujours nettoyé à l'arrêt.Boucle de reconnexion lorsque le service envoyait des commandes non prises en charge aux anciennes versions du micrologiciel.Énumération des appareils Bluetooth saturait le journal sur les systèmes dotés d'adaptateurs Bluetooth.Plantage lors de redémarrages successifs du service.Gel du dongle Verse Grip sans fil sur les portables Ubuntu après la mise en veille et la reprise.Poignée de main du Verse Grip sans fil sur Linux et macOS bascule maintenant correctement sur la solution de rechange lorsque la première tentative de détection échoue.Emplacement du fichier de configuration sous MacOS — la configuration est maintenant enregistrée dans ~/Library/Application Support/ au lieu du mauvais chemin.Gestion du signal SIGSEGV sur Linux et macOS — le processus ne boucle plus sur les signaux fatals lorsque la capture des plantages multithread est activée.Écrasement de commandes entre sessions — les commandes de configuration d'une session pouvaient être remplacées silencieusement par celles d'une autre ; elles sont maintenant filtrées et fusionnées correctement.Commandes de sonde écrasant la configuration — les sessions de surveillance (p. ex. Haply Hub) qui envoient probe_position n'écrasent plus silencieusement les modifications de base, de préréglage ou de profil en attente.Affichage des poignées prototypes — le matériel prototype apparaissait à tort comme une poignée standard au lieu d'une poignée personnalisée.Convention de matrice `set_basis` héritée à nouveau respectée pour les clients qui n'avaient pas encore migré.Impulsion de force Inverse3 lors de la déconnexion d'une session ne produit plus de pic de force résiduel.Condition de concurrence WebSocket lors de la perte de connexion pendant des cycles rapides de connexion et de déconnexion.WebSocket `session_id` était sérialisé comme 0 dans certaines charges utiles sortantes.Sur Windows, --log-level est maintenant respecté lorsqu'il est combiné à --dev (il était auparavant silencieusement réinitialisé à debug).Dépréciations
Toujours fonctionnels, mais ils seront retirés dans une future version majeure. Les réponses incluent un champ deprecation_warning le cas échéant.
| Déprécié | Remplacement |
|---|---|
| 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 au niveau de la session | configure.basis |
Notes de compatibilité
Aucune rupture de compatibilité majeure par rapport à 3.4.19. Deux remarques mineures pour les intégrations existantes :
Les points de terminaison HTTP dépréciés incluent désormais un champ deprecation_warning dans la réponse — les clients qui valident strictement les schémas de réponse doivent accepter ce champ supplémentaire.Le champ values de WebSocket command_data est déprécié, mais il est encore analysé ; privilégiez les champs nommés.Tutoriels et documentation
Nouveaux tutoriels : 05 Contrôle de position, 06 Combiné (Inverse3 + Verse Grip), 07 Base et montage, 08 Configurateur HTTP à distance, 09 Contrôle à distance de WebSocket, 10 Écouteur de flux d'événements.Nouvelle variante Glaze de chaque tutoriel C++ (cpp-glz/), aux côtés de la variante existante nlohmann/json.Tous les tutoriels réécrits pour l'API v3.1 (port 10001, configure.preset, champs de commande nommés, fonctions utilitaires print_state()).Retrait de l'ancien tutoriel Verse Grip Stopper, remplacé par le nouveau tutoriel Combiné.Documentation publique mise à jour dans les guides du SDK, la référence de l'API et les pages sur le matériel.
