Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Il s'agit de la mise à jour la plus importante publiée depuis la refonte de l'API, il y a un an. La version 3.5.0 introduit une couche mathématique 3D intégrée, la prise en charge complète de Minverse, des flux d'événements typés, une API de configuration complète et une interface HTTP plus épurée. Elle inclut également les corrections de bogues et les améliorations d'ergonomie apportées au cours de cette dernière année.
Points forts {#highlights}
Couche mathématique 3D intégrée — Il s'agit d'un pipeline de transformations combinables qui fournit comme éléments fondamentaux de premier ordre la base de l'appareil (frame), la transformation de montage, la transformation de l'espace de travail et la transformation de navigation ; il prend également en charge les transformations explicites entre les espaces local, de session, d'application et interne.Bubble Navigation — Permet d'explorer un vaste espace de travail virtuel grâce à des zones de forme (primitives SDF) dotées d'un contrôle de vitesse basé sur la cartographie de vitesse, d'une détection des collisions tenant compte de l'hystérésis et d'une dérive directionnelle optionnelle du curseur. Entièrement configurable via HTTP et WebSocket, cette solution prend en charge les allers-retours dans l'espace de l'application.Flux d'événements de type spécifié — Il s'agit d'un canal d'événements WebSocket dédié aux cycles de vie des appareils, aux notifications de sécurité, à l'étalonnage, à la batterie, aux alertes de cycle de contrôle et aux indications de fin de prise en charge (dépréciation).API de configuration — Système complet de configuration clé-valeur prenant en charge les opérations CRUD HTTP, les indications de type, les contraintes de plage et les descriptions, qui remplace les fichiers de configuration imbriqués existants.Configuration cohérente des périphériques — Fournit un ensemble de routes HTTP commun à tous les appareils : 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 le stylet sont désormais calibrés ensemble, et l'état de calibrage reste verrouillé jusqu'à ce que le stylet soit physiquement connecté.Amélioration de l'ergonomie HTTP — Sélecteur de périphérique basé sur un index (spécification du périphérique par index sans identifiant), format de requête/réponse unifié partagé avec WebSocket, utilisation facultative de {ok, erreur, données} Enveloppe (?format=json), propose des sélecteurs de session avec caractères génériques.Nouvelles fonctionnalités {#new-features}
Périphériques {#devices}
Minverse — Cette version inclut désormais la prise en charge officielle des fonctionnalités suivantes : détection, séquence de préparation, alertes de sécurité et workflow de calibrage synchronisé.Les modèles « Ruko » et « Kingfisher» sont reconnus comme des types officiels de poignées.Prise en charge des simulateurs de périphériques — Permet de détecter et de communiquer avec des périphériques simulés par logiciel, en complément du matériel physique.Protection contre les boucles de connexion — Les ports défectueux sont automatiquement bloqués, et POST /ports/{port}/resetVous pouvez le réinitialiser.Connexion du stylo Heartbeat — Utilise la technologie Debounce pour détecter de manière fiable la connexion et la déconnexion du stylo.Sessions, commandes et WebSocket {#sessions-commands-websocket}
Filtrage et persistance des profils de session — Chaque session déclare un nom de profil et la version requise du SDK ; le service conserve ces informations même après une reconnexion. Les clients et les outils de surveillance peuvent filtrer et cibler les sessions en fonction de ce profil.Tampon de commandes par session — Une session lente ne ralentit plus les autres sessions.Carte `configure` explicite pour les commandes ponctuelles — par appareil base, préréglage, monture, force_gate, amortissementet par session profil et baseC'est maintenant tout le monde configurerIl est inclus. Il est aligné sur la carte de configuration de sortie, ce qui garantit que les données transmises seront restituées sous la même forme lors de leur lecture ultérieure.Montage d'un périphérique personnalisé — 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é) ou envoyer une transformation explicite. Si vous modifiez manuellement le montage, le préréglage sera automatiquement personnalisésera converti en.Champ de commande nommé — position, vecteur, angles, couplesest polyvalent valeurs Remplace le tableau.définir les couples angulairesa définir_couple_angulaireremplace (la forme au singulier n'est plus prise en charge).Extension de la trame de session — Extensible aux trames de session v3.0 et v3.1 config, État, statut L'objet est inclus. Le nouveau champ de sortie contient force_du_curseur, position_du_curseur, couples angulaires actuels, position_angulaire_actuelle, domaine_de_contrôle, mode_de_contrôle, transformer, vitesse_de_transformation, encore plus riche config.*, et état.sécurité(masqué par défaut) est inclus.Mise à jour partielle de la transformation — Mount, transformation de l'espace de travail, sous-champs à modifier dans la forme d'exploration (position, rotation, échelle) uniquement.HTTP {#http}
GET / — Il s'agit d'une version de service.GET/POST/DELETE /paramètres et /paramètres/* — Il s'agit de l'API complète de configuration des paires clé-valeur.GET /sessions/{session} et GET/POST/DELETE /sessions/{session}/profile.GET /devices?session=<selector> — Convertit les coordonnées du périphérique dans l'espace applicatif de la session spécifiée.Sélecteur de périphériques basé sur un index — Même si vous ne connaissez pas l'ID, vous pouvez spécifier un périphérique quelconque à l'aide d'un index (dans le cas du premier Inverse3, par exemple) /inverse3/0/..., Tous les appareils de la gamme Inverse sont inverse...).Format des requêtes et réponses intégrées — Le corps des requêtes POST/GET est identique à celui de WebSocket données_de_commande Comme le format JSON est utilisé, le code écrit pour un mode de transmission fonctionne également avec les autres modes de transmission.Enveloppe sélective — sur tous les itinéraires ?format=jsonVous pouvez l'activer. /paramètres* et GET /retour_à_la_page_d'accueilC'est, par défaut, {ok, erreur, données} Utilisez ce format. Pour utiliser le format brut, ?format=simpleVeuillez le spécifier.Caractères génériques dans les sélecteurs de session — Dans le nom du profil *(une chaîne de caractères quelconque) et ?Vous pouvez utiliser (un seul caractère).Sélecteurs décodés en pourcentage — %2A, %3A Ces éléments sont décodés avant le routage.Événements {#events}
communication/événements/portIl s'agit d'un flux d'événements WebSocket dédié, fourni par [...].Il propose 24 catégories d'événements prédéfinies, notamment : cycle de vie de l'appareil, sécurité (frein électronique, détection de corps étrangers, blocage), échec d'étalonnage, alerte batterie, alerte de session, cycles de contrôle faibles et critiques, validation des entrées, et avertissements de fin de prise en charge.Observabilité {#observability}
Lors du profilage, les messages de journal sont transmis à Tracy avec des couleurs correspondant à chaque niveau.Une zone Tracy est appliquée à tous les gestionnaires HTTP.Il s'agit d'un événement statistique relatif au timing de la boucle principale.Vous pouvez configurer le répertoire des journaux et le nom d'hôte du serveur (compatible avec Docker).Disponible dans la version 3.6 {#coming-in-36}
Les travaux relatifs aux effets haptiques SDF (SDF HFX) ont été intégrés dans la version 3.5 (module, cycle de vie, sérialisation des commandes et des états fournis par le module). L'API publique sera disponible dans la version 3.6, accompagnée d'une documentation complète.Améliorations {#improvements}
Filtrage des vibrations de force — comprend la détection des vibrations par axe, une récupération progressive en 8 étapes, un vote d'entrée avec hystérésis et une plage de désactivation asymétrique.Filtre « force-gate » à exécution dynamique — via WebSocket ou HTTP configure.force_gate.gainIl peut être configuré et prend en charge les valeurs par défaut permanentes.Pour les applications de haute précision, la fréquence maximale de la boucle principale a été portée à 32 kHz.Une charge utile WebSocket réduite — Sous-champ « transform » avec une valeur par défaut d'identité (position = 0, rotation = identité, échelle = 1) est par défaut omis dans la sortie, ce qui réduit la taille de la charge utile et rétablit la compatibilité avec la limite de 4 Ko par message des anciennes versions du package Unity. Deux paramètres avancés (sérialisation/champs_explicites, sérialisation/forcer_la_transformation_complète) permet de réintégrer tous les champs pour les utilisateurs qui en ont besoin.Réduction de la gigue dans la boucle principale — Le traitement des messages WebSocket ne bloque plus les ticks de la boucle principale, même pendant l'analyse JSON et la transmission réseau. La planification des ticks de session a été avancée par rapport à la sérialisation des réponses.La configuration par défaut du serveur est réservée à « localhost » — communication/lier_toutes_les_interfaces Vous pouvez autoriser explicitement l'accès au réseau dans les paramètres.Les caractères génériques du sélecteur de périphériques utilisent la syntaxe des préfixes(par exemple : inverse(est compatible avec tous les appareils de la gamme Inverse).Commande d'amortissementce force_gateavec configurer Vous avez été redirigé vers la carte.L'enregistreur de fichiers à rotationremplace l'enregistreur existant et permet de configurer des répertoires.Commandes et états fournis par le module — Le module peut injecter ses propres commandes, configurer des champs et ajouter des informations d'état aux trames WebSocket sans modifier le schéma de base.Corrections {#fixes}
Il s'agit des corrections de bogues cumulées au cours de l'année ; les éléments ayant eu le plus d'impact sont les suivants :
Problème lié à l'apparition d'irrégularités dans la vitesse de la session dans certaines conditions.Problème lié au fait que le déverrouillage du GripHook (Verse Grip Stopper) ne s'effectuait pas correctement lorsque la simulation n'était pas en cours d'exécution.Inverse3 Problème lié àun délai d'expirationtrop court, qui provoquait des déconnexions répétées sur les appareils dont le démarrage était lent.Windows Arrêt anormal du service — Le serveur HTTP n'a pas toujours été nettoyé lors de l'arrêt.Boucle de reconnexion qui se produisait lorsque le service envoyait des commandes non prises en charge par l'ancienne version du micrologiciel.Problème lié à l'énumération des périphériques Bluetoothqui saturait excessivement le journal sur les systèmes équipés d'un adaptateur Bluetooth.Un plantage qui se produisait lors du redémarrage successif et répété du service.Blocage de la clé « Wireless Verse Grip » sur un ordinateur portable sous Ubuntu lors de la reprise après la mise en veille.Sous Linux et macOS, la connexion du Wireless Verse Grips'effectue désormais correctement même si la première tentative de détection échoue.Emplacement des fichiers de configuration de macOS — La configuration utilise désormais le bon chemin d'accès au lieu de ~/Bibliothèque/Application Support/est enregistré dans.Gestion du signal SIGSEGV sous Linux et macOS — Lorsque la capture des conflits multithread est activée, le processus ne se retrouve plus pris dans une boucle en cas de signal fatal.Remplacement des commandes entre sessions — Auparavant, les commandes de configuration d'une session pouvaient être remplacées discrètement par celles d'une autre session ; désormais, elles sont correctement filtrées et fusionnées.Problème lié à la commande « Probe » qui écrase les paramètres — Lors d'une session de surveillance (par exemple, Hub « Haply ») position_de_la_sonde Même si vous envoyez une commande, les modifications en attente concernant la base, le préréglage ou le profil ne seront plus automatiquement écrasées.Indication relative à la poignée du prototype — Le matériel du prototype a été indiqué à tort comme étant équipé d'une poignée standard au lieu d'une poignée personnalisée.Une modification a été apportée afin que l'ancienne règle relative à la matrice `set_basis`s'applique à nouveau pour les clients qui n'ont pas encore effectué la migration.Lors de la déconnexion d'une session, le « force kick » deInverse3 ne provoque plus de pic de puissance résiduel.Condition de concurrence « WebSocket connection lost » survenant lors de cycles rapides d'établissement et de fermeture de connexion.Dans certaines charges utiles de transmission, `session_id` WebSocket la valeur 0Problème lié à la sérialisation.Sous Windows --dev Lorsqu'il est utilisé avec cette option, --niveau-journal Les options s'appliquent désormais correctement (auparavant, elles étaient ignorées sans message d'erreur) débogage (Il a été réinitialisé au niveau).Éléments obsolètes {#deprecations}
Cette fonctionnalité fonctionne toujours, mais elle sera supprimée dans une prochaine version majeure. Le cas échéant, veuillez indiquer dans votre réponse avertissement_de_dépréciation Il contient des champs.
| Éléments obsolètes | Éléments de 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}
Il n'y a pas de modification entraînant une rupture de compatibilité certaine pour la version 3.4.19. Il convient de noter deux points concernant l'intégration existante :
Les réponses des points de terminaison HTTP obsolètes contiennent désormais avertissement_de_dépréciation Ce champ est inclus. Les clients qui vérifient rigoureusement le schéma de réponse doivent accepter ce champ supplémentaire.WebSocket données_de_commandede valeurs Ce champ est obsolète, mais il est toujours analysé. Il est recommandé d'utiliser des champs nommés.Tutoriels et documentation {#tutorials-documentation}
Nouveaux tutoriels: 05 Contrôle de position, 06 Intégration (Inverse3 +Verse Grip), 07 Basis et Mount, 08 Configurateur à distance HTTP, 09 Contrôle à distance via WebSocket, 10 Écouteur de flux d'événements.Nouvelle version de Glaze: En plus de la version nlohmann/json existante, tous les tutoriels C++ incluent désormais la version Glaze (cpp-glz/) a été ajouté.Réécriture de tous les tutoriels: API v3.1 (port 10001, fichier de configuration prédéfini, champ de commande nommé, print_state() Ce texte a été réécrit pour s'adapter à « Helper ».Le tutoriel existant sur le Verse Grip Stopper a été supprimé— il a été remplacé par un nouveau tutoriel complet.Nous avons mis à jour l'ensemble de la documentation publique, qu'il s'agisse du guide du SDK, de la référence API ou des pages consacrées au matériel.
