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 configuration complète ainsi qu'une interface HTTP plus épurée. Elle inclut également les corrections de bogues et les améliorations de l'expérience utilisateur apportées au cours de l'année écoulée.
Points forts {#highlights}
Couche mathématique 3D unifiée — pipeline de transformations modulaires, fournissant un ensemble d'éléments de base de premier niveau pour le système de coordonnées de base de l'appareil (frame), les transformations de montage, les transformations de l'espace de travail et les transformations de navigation, et prenant en charge les conversions explicites entre les espaces local, de session, d'application et interne.Navigation « Bubble » — Permet de naviguer dans un vaste espace de travail virtuel à l'aide de zones de formation (éléments SDF) ; prend en charge le contrôle de la vitesse par mappage de vitesse, la détection des collisions avec prise en compte du temps de latence, ainsi qu'une dérive optionnelle vers le curseur. Entièrement configurable via HTTP et WebSocket, et prend en charge les allers-retours dans l'espace de l'application.Flux d'événements typés — Canaux d'événements WebSocket dédiés, destinés au cycle de vie des appareils, aux alertes de sécurité, à l'étalonnage, à l'état de la batterie, aux avertissements relatifs au débit de contrôle et aux notifications de fin de vie.API de configuration — Système complet de configuration clé-valeur prenant en charge les opérations CRUD via HTTP, les suggestions de types, les contraintes de plage de valeurs et les descriptions, qui remplace les anciens fichiers de configuration imbriqués.Configuration uniforme des équipements — Tous les appareils partagent un ensemble de règles de routage HTTP :base,monture,préréglage,transformer,filtres,latéralité,mise à l'échelle du couple,compensation de la gravité,Retour à l'accueil。Calibrage synchronisé de Minverse et du stylet — L'appareil et son stylet peuvent désormais être calibrés ensemble ; le calibrage reste verrouillé jusqu'à ce que le manche soit effectivement connecté.Améliorations de la facilité d'utilisation du protocole HTTP — Sélecteur d'appareils basé sur un index (sans identifiant, les appareils sont spécifiés par leur index), partageant avec WebSocket une structure de requête/réponse unifiée, dont l'activation est facultative {ok, erreur, données} Emballage (?format=json), ainsi que les sélecteurs de session avec caractères génériques.Nouvelles fonctionnalités {#new-features}
Équipements {#devices}
Minverse — Cette version prend officiellement en charge : la détection des appareils, le processus de mise en service, les notifications de sécurité et le flux de travail de synchronisation et d'étalonnage.Ruko et Kingfisher ont été reconnus comme des types de poignées officiels.Prise en charge des simulateurs de périphériques — Permet de détecter et de communiquer avec des périphériques simulés par un logiciel, parallèlement au matériel réel.Protection contre les boucles de connexion — Les ports présentant un comportement anormal sont automatiquement bloqués ; il est possible de POST /ports/{port}/reset Réinitialiser.Le stylet au rythme de votre cœur — une prise en main fiable qui détecte la connexion et la déconnexion, même en cas de tremblements.Sessions, commandes et WebSocket {#sessions-commands-websocket}
Filtrage et persistance des profils de session — Les sessions spécifient le nom du profil de configuration et la version requise du SDK ; le service mémorise ces informations après une reconnexion ; le client et les outils de surveillance peuvent filtrer et localiser les sessions à l'aide de ce profil.Mémoire tampon des commandes par session — Une session lente ne bloque plus les autres sessions.Mappage explicite `configure` pour les commandes ponctuelles — Pour chaque appareil, base,préréglage,monture,force_gate,amortissement, ainsi que pour chaque session profil et base, qui se trouvent désormais tous à configurer De ce fait, la correspondance avec la configuration de sortie est préservée, ce qui permet d'assurer la cohérence entre les données envoyées et celles lues, dans les deux sens.Méthodes d'installation personnalisables des appareils — Possibilité de choisir parmi les préréglages d'espace de travail intégrés (valeurs par défaut,avant du bras,bras_avant_centré,LED avant,led_avant_centré), il est également possible d'envoyer une transformation explicite ; lorsque l'on modifie manuellement le mode d'installation, le paramètre par défaut bascule automatiquement vers personnalisé。Champ de commande nommée — position,vecteur,angles,couples a remplacé le modèle générique valeurs Tableau.définir les couples angulaires a remplacé définir_couple_angulaire(La forme au singulier est obsolète).Extension de trame de session — Les trames de session des versions v3.0 et v3.1 contiennent désormais des éléments extensibles config,État et statut Objet ; 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 varié config.*, ainsi que état.sécurité(Masqué par défaut).Mise à jour partielle de la transformation — En ce qui concerne le mode d'installation, la transformation de l'espace de travail et la forme de navigation, il suffit d'envoyer les sous-champs à modifier (position,rotation,échelle).HTTP {#http}
GET / — Version du service.GET/POST/DELETE /paramètres et /paramètres/* — Une API complète de configuration par paires clé-valeur.GET /sessions/{session} et GET/POST/DELETE /sessions/{session}/profile。GET /devices?session=<selector> — Convertit les coordonnées de l'appareil dans l'espace de l'application de la session spécifiée.Sélecteur d'appareils basé sur un index — Il est possible de localiser n'importe quel appareil à l'aide de l'index sans avoir besoin de connaître son identifiant (/inverse3/0/... pointant vers le premier Inverse3;inverse... (valable pour tous les appareils de la gamme Inverse).Structure uniforme de requête/réponse — Le corps des requêtes POST/GET utilise le même format que celui des WebSockets données_de_commande Structure JSON ; le code écrit pour un mode de transmission peut également être utilisé pour un autre.Structures d'encapsulation optionnelles — À utiliser sur n'importe quel itinéraire ?format=json Peut être activé immédiatement ;/paramètres* et GET /retour_à_la_page_d'accueil Utilisation par défaut {ok, erreur, données}. Si vous souhaitez conserver la structure d'origine, veuillez utiliser ?format=simple。Caractères génériques du sélecteur de session — Dans le nom du fichier de configuration : *(séquence de caractères quelconque) et ?(un seul caractère).Sélecteurs de décodage des pourcentages — %2A,%3A etc. seront décodés avant le routage.Événements {#events}
à communication/événements/port Il fournit un flux d'événements WebSocket dédié.Il existe au total 24 catégories d'événements, notamment ceux liés au cycle de vie de l'appareil, les événements de sécurité (arrêt d'urgence, détection de corps étrangers, décrochage), les échecs d'étalonnage, les alertes de batterie, les avertissements de session, les vitesses de contrôle trop faibles ou extrêmement faibles, la validation des entrées et les notifications de mise hors service.Observabilité {#observability}
Lorsque l'analyse des performances est activée, les messages de journalisation sont transmises à Tracy après avoir été colorés en fonction de leur niveau.Chaque gestionnaire HTTP dispose d'une zone Tracy.Chronométrage des événements dans la boucle principale.Il est possible de configurer le répertoire des journaux et le nom d'hôte du serveur (pour faciliter l'utilisation de Docker).La version 3.6 sera bientôt disponible {#coming-in-36}
Effets tactiles SDF (SDF HFX) — Le travail de base a été achevé dans la version 3.5 (modules, cycle de vie, sérialisation des commandes et des états fournis par les modules) ; l'API publique sera publiée avec la version 3.6 et accompagnée d'une documentation complète.Améliorations {#improvements}
Filtrage des oscillations de force — Détection des oscillations par axe, récupération progressive en 8 étapes, mécanisme de vote d'entrée avec hystérésis et fenêtre de libération asymétrique.Filtre de porte de puissance à l'exécution — Utilisable via WebSocket ou HTTP configure.force_gate.gain Configuration avec des valeurs par défaut persistantes.La fréquence maximale du cycle principal a été portée à 32 kHz, ce qui permet de répondre aux besoinsdes applications de haute précision.Une charge WebSocket réduite — Par défaut, les sous-champs dont la valeur par défaut est une transformation identique sont omis dans la sortie (position = 0,rotation = identité,échelle = 1), ce qui permet de réduire la taille de la charge et de rétablir la compatibilité avec la limite de longueur de message de 4 Ko imposée par les anciennes versions du package Unity. Deux paramètres avancés (sérialisation/champs_explicites,sérialisation/forcer_la_transformation_complète) permet de réactiver tous les champs pour les utilisateurs qui en ont besoin.Réduction de la fluctuation de la boucle principale — Le traitement des messages WebSocket ne bloque plus les cycles de la boucle principale pendant l'analyse JSON et l'envoi sur le réseau ; la planification des cycles de session a été avancée avant la sérialisation des réponses.Par défaut, le serveur n'écoute que sur « localhost ». — Pour activer l'accès à Internet, veuillez activer communication/lier_toutes_les_interfaces Paramètres.Les caractères génériques du sélecteur d'équipement utilisent la syntaxe des préfixes(par exemple inverse (Compatible avec tous les appareils de la gamme Inverse).Commande d'amortissement A déjà été mis en relation avec force_gate S'installer ensemble configurer En cours de mappage.L'enregistreur de journaux à rotation de fichiers remplace l'enregistreur précédent et prend en charge les répertoires configurables.Commandes et états fournis par les modules — Les modules peuvent intégrer des commandes personnalisées, des champs de configuration et des sorties d'état dans les trames WebSocket, sans avoir à modifier le schéma de base.Corrections {#fixes}
Un an de correction des défauts ; les plus importants sont énumérés ci-dessous.
La vitesse de connexion est instable etce phénomène se produit dans certaines conditions particulières.GripHook (Verse Grip Stopper) ne se déverrouille pas correctement en l'absence de simulation.Inverse3 Le délaid'expirationétant trop court, les appareils dont le démarrage est lent se retrouvent pris dans une boucle de déconnexion.Le nettoyage n'a pas été effectué correctement lors de l'arrêt du service sur Windows — le serveur HTTP n'est pas toujours nettoyé lors de son arrêt.Une boucle de reconnexionse produit lorsque le service envoie des commandes non prises en charge à une ancienne version du micrologiciel.L'énumération des périphériques Bluetoothgénère un volume important de journaux sur les systèmes équipés d'un adaptateur Bluetooth.Le service plante lorsqu'on le redémarre plusieurs fois de suite.Le récepteur sans fil Verse Grip se bloqueaprès la mise en veille ou la sortie de veille d'un ordinateur portable sous Ubuntu.Le Verse Grip sans fil(Linux et macOS) effectue désormais correctement la procédure de repli en cas d'échec de la première tentative de détection.Emplacement des fichiers de configuration sous macOS — La configuration est désormais stockée dans ~/Bibliothèque/Application Support/ parmi celles-ci, et non pas une voie erronée.Gestion du signal SIGSEGV sous Linux et macOS — Lorsque la capture des plantages multithread est activée, le processus ne se retrouve plus dans une boucle à cause d'un signal fatal.Remplacement des commandes entre sessions — Une commande de configuration définie dans une session pouvait être remplacée en arrière-plan par une commande provenant d'une autre session ; ces commandes sont désormais correctement filtrées et fusionnées.Configuration de la couverture des commandes de détection — Surveillance des sessions (par exemple, via Haply Hub) envoyées position_de_la_sonde Dans ce cas, les modifications apportées à la base, au préréglage ou au profil en attente de traitement ne seront plus automatiquement remplacées.Problème d'affichage de la poignée prototype — Le matériel prototype s'affiche à tort comme une poignée standard, et non comme une poignée personnalisée.L'ancienne convention relative à la matrice `set_basis`est à nouveau en vigueur, à l'intention des clients qui n'ont pas encore effectué la migration.Inverse3 Le « force kick » ne génère plus de pic de force résiduelle lorsque la session est interrompue.Une condition de concurrence liée à la perte de connexion WebSocketse produit lors d'un cycle rapide de connexion/déconnexion.`session_id` WebSocket sérialisé dans une partie de la charge sortante sous la forme de 0。Sur Windows ,--niveau-journal et --dev Lorsqu'elles sont utilisées simultanément, elles sont désormais respectées (auparavant, elles étaient réinitialisées de manière silencieuse à débogage).Éléments obsolètes {#deprecations}
Il fonctionne toujours normalement, mais sera supprimé dans une prochaine version majeure. Le cas échéant, la réponse inclura avertissement_de_dépréciation Champ.
| 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 |
| Au niveau de la session WebSocket définir_la_base | configuration de base |
Remarques sur la compatibilité {#compatibility-notes}
Par rapport à la version 3.4.19, il n'y a pas de modifications majeures entraînant des incompatibilités. Deux remarques mineures concernant les intégrations existantes :
Les points de terminaison HTTP obsolètes incluent désormais dans leur réponse avertissement_de_dépréciation Champ — Les clients effectuant une validation stricte du schéma de réponse doivent autoriser ce champ supplémentaire.WebSocket données_de_commande dans valeurs Ce champ est obsolète, mais il sera tout de même analysé ; il est recommandé d'utiliser de préférence les champs nommés.Tutoriels et documentation {#tutorials-documentation}
Nouveaux tutoriels: 05 Contrôle de position, 06 Combiné (Inverse3 + Verse Grip), 07 Basis et Mount, 08 Configurateur à distance HTTP, 09 Contrôle à distance via WebSocket, 10 Écouteur de flux d'événements.Ajout d'une variante de Glaze: Ajout d'un nouveau contenu pour chaque tutoriel C++ cpp-glz/ Variante, coexistant avec la variante nlohmann/json existante.Tous les tutoriels ont été réécrits, afin de prendre en charge l'API v3.1 (port 10001,fichier de configuration prédéfini, champ de commande nommée,print_state() (fonctions auxiliaires).L'ancientutoriel sur le Verse Grip Stopper a été supprimé— il a été remplacé par le nouveau tutoriel « Combined ».La documentation publique a étémise à jour ; elle comprend désormais les guides du SDK, la documentation de référence des API et les pages consacrées au matériel.
