Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Il s'agit de notre plus importante mise à jour depuis la refonte 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 claire – sans oublier une année riche en corrections de bogues et en améliorations de l'ergonomie.
Points forts {#highlights}
Couche mathématique 3D unifiée — un pipeline de transformations combinables comprenant des primitives de premier ordre pour la base de l'appareil (trame), la transformation d'assemblage, la transformation de l'espace de travail et la transformation de navigation, ainsi que des conversions explicites entre les espaces locaux, de session, d'application et internes.Navigation par bulles — Navigation dans de grands espaces de travail virtuels via des zones profilées (primitives SDF) avec contrôle de la vitesse en fonction de la vitesse, détection des collisions tenant compte de l'hystérésis et dérive vers le curseur en option. Entièrement configurable via HTTP et WebSocket, avec aller-retour via l'espace de l'application.Flux d'événements standardisé — un canal d'événements WebSocket dédié au cycle de vie des appareils, aux alertes de sécurité, à l'étalonnage, à l'état de la batterie, aux alertes relatives à la fréquence de mise à jour et aux notifications concernant les fonctionnalités obsolètes.API de paramètres — un système complet de paramètres de type clé-valeur, avec des opérations HTTP CRUD, des validations de type, des restrictions de plage et des descriptions, qui remplace l'ancien fichier de configuration imbriqué.Configuration uniforme des appareils — un ensemble commun de routes HTTP pour chaque appareil : base, monture, préréglage, transformer, filtres, latéralité, mise à l'échelle du couple, compensation de la gravité, Retour à l'accueil.Calibrage synchronisé du Minverse et du stylet — l'appareil et son stylet sont désormais calibrés ensemble ; le calibrage reste verrouillé jusqu'à ce qu'un stylet soit physiquement connecté.Améliorations du confort d'utilisation de HTTP — des sélecteurs de périphériques basés sur un index (accès au périphérique via un index, aucun identifiant requis), un format uniforme de requête et de réponse, commun avec WebSocket, une fonctionnalité pouvant être activée en option {ok, erreur, données}-Enveloppe (?format=json) et les sélecteurs de session avec caractères génériques.Nouvelles fonctionnalités {#new-features}
Appareils {#devices}
Minverse — prise en charge officielle dans cette version : détection, séquence de mise en service, notifications de sécurité et procédure d'étalonnage synchronisée.« Ruko » et « Kingfisher » sont reconnus comme des types de produits officiels pour les poignées.Prise en charge des simulateurs de périphériques — détecter les périphériques simulés par un logiciel et communiquer avec eux, parallèlement au matériel physique.Protection contre les boucles de connexion — Les ports présentant un comportement anormal sont automatiquement bloqués ; réinitialisation à l'aide de POST /ports/{port}/reset.Détection des mouvements de la poignée — détection fiable de la mise en place et du retrait de la poignée, avec suppression des faux signaux.Sessions, commandes et WebSocket {#sessions-commands-websocket}
Filtrage et persistance des profils de session — Les sessions spécifient un nom de profil et la version requise du SDK, que le service conserve d'une reconnexion à l'autre ; les clients et les outils de surveillance peuvent filtrer les sessions à l'aide de ce profil et les cibler de manière spécifique.Mémoire tampon de commandes par session — une session lente ne peut plus ralentir une autre session.Mappage explicite de `configure` pour les commandes à exécuter une seule fois — base, préréglage, monture, force_gate, amortissement par appareil ainsi que profil et base Pour chaque séance, tous les éléments figurant dans configurer géré – en fonction de l'affectation de la configuration de sortie, de sorte que les données envoyées correspondent à celles reçues.Montage personnalisable des appareils — sélectionnez un préréglage d'espace de travail intégré (valeurs par défaut, avant du bras, bras_avant_centré, LED avant, led_avant_centré) ou envoyez une transformation explicite ; toute modification manuelle du montage active automatiquement le préréglage sur personnalisé euh.Champs de commande nommés — position, vecteur, angles, couples remplacent le tableau générique valeurs.définir les couples angulaires remplacé définir_couple_angulaire (la forme au singulier est désuète).Extensions des trames de session — Les cadres de session des versions v3.0 et v3.1 contiennent désormais des objets extensibles config, État et statut; les nouveaux champs de sortie comprennent force_du_curseur, position_du_curseur, couples angulaires actuels, position_angulaire_actuelle, domaine_de_contrôle, mode_de_contrôle, transformer, vitesse_de_transformation, plus complets config.*-Felder ainsi que état.sécurité (masqué par défaut).Mises à jour partielles des transformations — n'envoyez que les sous-champs que vous souhaitez modifier (position, rotation, échelle) lors du montage, de la transformation de l'espace de travail et de la forme de navigation.HTTP {#http}
GET / — Version de service.GET/POST/DELETE /paramètres et /paramètres/* — API complète de paramètres clé-valeur.GET /sessions/{session} et GET/POST/DELETE /sessions/{session}/profile.GET /devices?session=<selector> — Convertir les coordonnées de l'appareil dans l'espace d'application d'une session donnée.Sélecteurs d'appareils basés sur un index — accéder à chaque appareil par son index, sans connaître son identifiant (/inverse3/0/... pour le premier appareil « Inverse3 » ; inverse... (pour tous les appareils de la gamme Inverse).Format standardisé pour les demandes et les réponses — Les corps des requêtes POST et GET sont identiques données_de_commande- Les structures JSON telles que WebSocket ; le code écrit pour un mode de transport fonctionne également avec l'autre.Enveloppe facultative — activable via ?format=json sur chaque itinéraire ; /paramètres* et GET /retour_à_la_page_d'accueil utilisent par défaut {ok, erreur, données}. Utilisez ?format=simple pour la structure brute.Caractères génériques dans les sélecteurs de session — * (chaîne de caractères quelconque) et ? (caractère isolé) dans les noms de profil.Sélecteurs avec codage en pourcentage — %2A, %3A etc. sont décodés avant le routage.Événements {#events}
Flux d'événements WebSocket dédié sur communication/événements/port.24 catégories d'événements standardisées, parmi lesquelles le cycle de vie des appareils, la sécurité (frein électronique, détection de corps étrangers, blocage), les erreurs d'étalonnage, les alertes relatives aux batteries, les alertes de session, les fréquences de régulation faibles et critiques, la validation des entrées et les notifications concernant les fonctions obsolètes.Observabilité {#observability}
Lors du profilage, les messages de journal sont transmis à Tracy avec des couleurs correspondant au niveau de détail.Tracy-Zones pour chaque gestionnaire HTTP.Événements accompagnés de statistiques de temporisation de la boucle principale.Répertoire de journaux et nom d'hôte du serveur configurables (compatible avec Docker).Bientôt disponible dans la version 3.6 {#coming-in-36}
Effets haptiques SDF (SDF HFX) — les bases ont déjà été posées dans la version 3.5 (module, cycle de vie, sérialisation des données de commande et d'état fournies par le module) ; l'API publique sera fournie avec une documentation complète dans la version 3.6.Améliorations {#improvements}
Filtrage des vibrations mécaniques — détection des vibrations par axe, rétablissement progressif en huit étapes, réglage de l'entrée avec hystérésis et fenêtres de validation asymétriques.Filtre « Force-Gate » à l'exécution — configurable via configure.force_gate.gain, via WebSocket ou HTTP, avec une valeur par défaut persistante.La fréquence maximale de la boucle principale a été portée à 32 kHz pour les applications de précision.Charges utiles WebSocket plus petites — Sous-champs de transformation avec valeur d'identité par défaut (position = 0, rotation = identité, échelle = 1) ne sont pas affichés par défaut. Cela permet de réduire la taille de la charge utile et de rétablir la compatibilité avec la limite de 4 Ko par message des anciens paquets Unity. Deux paramètres avancés (sérialisation/champs_explicites, sérialisation/forcer_la_transformation_complète) reprennent tous les champs, pour les clients qui en ont besoin.Réduction de la gigue de la boucle principale — le traitement des messages WebSocket ne bloque plus le cadencement de la boucle principale pendant l'analyse JSON et l'envoi sur le réseau ; la planification du cadencement des sessions a été déplacée avant la sérialisation des réponses.Par défaut, le serveur fonctionne uniquement sur localhost — Pour activer l'accès au réseau, utilisez le paramètre communication/lier_toutes_les_interfaces.Utilisation des caractères génériques pour les sélecteurs d'appareils : syntaxe des préfixes (par exemple inverse (convient à tous les appareils de la gamme Inverse).Commandes d'atténuation ont été réalisés en collaboration avec force_gate dans la matrice configurer- Attribution reportée.L'enregistreur de fichiers rotatif remplace l'ancien et prend en charge un répertoire configurable.Commandes et états fournis par les modules — Les modules peuvent introduire leurs propres commandes, configurer des champs et insérer des informations d'état dans le cadre WebSocket, sans modifier le schéma de base.Corrections de bogues {#fixes}
Une année marquée par de nombreuses corrections de bogues ; les plus efficaces sont énumérées ci-dessous.
Vitesse de session irrégulière dans certaines conditions.GripHook (Verse Grip Stopper) ne se déverrouillait pas correctement lorsqu'aucune simulation n'était en cours.Inverse3- Les délais d'expiration étaient trop stricts et provoquaient des boucles de déconnexion sur les appareils dont le démarrage était lent.Arrêt incorrect du service sur Windows — le serveur HTTP n'était pas toujours nettoyé lors de son arrêt.Boucle de reconnexion lorsque le service envoyait des commandes non prises en charge à des versions antérieures du micrologiciel.La liste des périphériques Bluetooth a saturé le journal sur les systèmes équipés de cartes Bluetooth.Plantage lors de plusieurs redémarrages consécutifs du service.Blocage de la clé « Wireless Verse Grip » sur les ordinateurs portables sous Ubuntu après la mise en veille et la sortie de veille.Wireless-Verse-Grip-Handshake sous Linux et macOS utilise désormais correctement la solution de secours lorsque la première tentative de détection échoue.Emplacement du fichier de configuration macOS — la configuration est désormais enregistrée dans ~/Bibliothèque/Application Support/ enregistré au lieu d'être placé dans le mauvais chemin d'accès.SIGSEGV — Gestion des signaux sous Linux et macOS: le processus ne se retrouve plus en boucle en cas de signaux fatals lorsque la collecte des plantages est activée pour plusieurs threads.Remplacement des commandes entre sessions — Les commandes de configuration d'une session pouvaient être remplacées tacitement par celles d'une autre session ; elles sont désormais correctement filtrées et fusionnées.Les commandes de sondage écrasent la configuration — Sessions de surveillance (par exemple, le Hub « Haply »), qui position_de_la_sonde Les modifications en attente apportées à la base, au préréglage ou au profil ne sont désormais plus appliquées tacitement.Affichage des poignées prototypes — Le matériel prototype s'affichait par erreur comme une poignée standard au lieu d'une poignée personnalisée.L'ancienne convention relative à la matrice `set_basis` est à nouveau prise en compte pour les clients qui n'ont pas encore été migrés.Inverse3- L'impulsion de force générée lors de la fin de la session ne provoque plus de pic de force résiduelle.Condition de concurrence en cas de perte de connexion WebSocket lors de cycles rapides de connexion/déconnexion.`session_id` WebSocket a été détecté dans certaines charges utiles sortantes sous la forme de 0 sérialisé.Sur Windows , on trouve --niveau-journal désormais également en collaboration avec --dev pris en compte (auparavant tacitement considéré comme débogage réinitialisé).Fonctionnalités obsolètes {#deprecations}
Toujours opérationnel, mais sera supprimé dans une prochaine version majeure. Les réponses peuvent comporter un champ avertissement_de_dépréciation.
| Obsolète | Remplacement |
|---|---|
| POST /force_scale | POSTinverse |
| POST /compensation_gravitationnelle | 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 /paramètres/communication/série/activé |
| POST /experimental/features/grip_dropped_simulation_stopper | API des paramètres |
| POST /experimental/features/screensaver_enable | API des paramètres |
| WebSocket command_data.values | position, vecteur, angles, couples |
| WebSocket définir_couple_angulaire | définir les couples angulaires |
| WebSocket position_du_curseur_de_sonde | position_de_la_sonde |
| WebSocket définir_l'origine_des_coordonnées | fichier de configuration prédéfini |
| WebSocket définir_la_base au niveau de la session | configuration de base |
Remarques sur la compatibilité {#compatibility-notes}
Aucune modification majeure par rapport à la version 3.4.19. Deux remarques sans gravité concernant les intégrations existantes :
Les points de terminaison HTTP obsolètes contiennent désormais un champ avertissement_de_dépréciation dans la réponse – Les clients qui valident rigoureusement les schémas de réponse devraient autoriser ce champ supplémentaire.Le champ valeurs dans WebSocket données_de_commande Cette méthode est obsolète, mais elle continue d'être analysée. Privilégiez l'utilisation des champs nommés.Tutoriels et documentation {#tutorials-documentation}
Nouveaux tutoriels: 05 Contrôle de position, 06 Combiné (Inverse3 + Verse Grip), 07 Base et support, 08 Configurateur à distance HTTP, 09 Commande à distance via WebSocket, 10 Écouteur de flux d'événements.Nouvelle variante de glaçure chaque tutoriel C++ (cpp-glz/) en plus de la variante nlohmann/json existante.Tous les tutoriels ont été mis à jour pour l'API v3.1 (port 10001, fichier de configuration prédéfini, champs de commande nommés, print_state()-Fonctions auxiliaires).Supprimé: l'ancien tutoriel sur le « Verse Grip Stopper » – remplacé par le nouveau tutoriel combiné.La documentation publique a été mise à jour dans les guides SDK, la référence API et sur les pages consacrées au matériel.
