Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
Il s'agit de la mise à jour la plus importante 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, un flux d'événements typé, une API de configuration complète et une interface HTTP mieux organisée. Elle inclut également toutes les corrections de bogues et améliorations de l'ergonomie apportées au cours de l'année écoulée.
Points forts {#highlights}
Couche mathématique 3D intégrée — Il s'agit d'un pipeline de transformations combinables, doté de primitives de premier ordre pour la base de l'appareil (système de référence), les transformations de montage, les transformations de l'espace de travail et les transformations de navigation. De plus, il permet d'effectuer des transformations explicites entre les espaces local, de session, d'application et interne.Navigation par bulles — Vous pouvez vous déplacer au sein d'un espace de travail virtuel à grande échelle grâce à des zones dotées d'une forme (primitives SDF). Ce système prend en charge le contrôle de la vitesse par mappage de vitesse, la détection des collisions tenant compte de l'hystérésis, ainsi que la dérive vers la direction du curseur si nécessaire. Il est entièrement configurable via HTTP et WebSocket et prend également en charge les allers-retours au sein de l'espace de l'application.Flux d'événements typés — Il s'agit de canaux d'événements WebSocket dédiés au cycle de vie des appareils, aux alertes de sécurité, à l'étalonnage, à la batterie, aux avertissements relatifs au taux de contrôle et aux conseils concernant les pratiques déconseillées.API de configuration — Système complet de configuration clé-valeur, prenant en charge les opérations CRUD via HTTP, les indications de type, les contraintes de plage et les descriptions. Elle remplace les fichiers de configuration imbriqués traditionnels.Harmonisation des paramètres des appareils — Nous avons défini un ensemble unique de routes HTTP communes à 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 son stylet sont désormais calibrés simultanément. Le calibrage reste verrouillé jusqu'à ce que la poignée soit physiquement fixée.Amélioration de la facilité d'utilisation du protocole HTTP — Sélecteur de périphériques basé sur un index (ne nécessitant pas d’ID et permettant de spécifier un périphérique à l’aide d’un index), format de requête/réponse commun à WebSocket, option d’adhésion {ok, erreur, données} Enveloppe (?format=json), ainsi qu'un sélecteur de session utilisant des caractères génériques.Nouvelles fonctionnalités {#new-features}
Périphériques {#devices}
Minverse — Cette version offre une prise en charge officielle. Elle inclut des workflows de détection, de séquences de préparation, d'alertes de sécurité et d'étalonnage synchronisé.Les modèles « Ruko » et « Kingfisher » sont désormais reconnus comme des types de produits de poignées officiels.Prise en charge des simulateurs de périphériques — Vous pouvez détecter et communiquer avec des périphériques simulés par logiciel, parallèlement aux périphériques physiques.Protection des boucles de connexion — Les ports présentant un comportement anormal sont automatiquement bloqués.POST /ports/{port}/reset Vous pouvez le réinitialiser.Le « battement de cœur » de la fixation du stylo — Grâce au traitement anti-rebond, la détection de la fixation et du retrait de la poignée est garantie.Sessions, commandes, WebSocket {#sessions-commands-websocket}
Filtrage et persistance des profils de session — Une session peut déclarer un nom de profil et la version requise du SDK ; le service mémorise ces informations d'une reconnexion à l'autre. Les clients et les outils de surveillance peuvent filtrer les sessions à l'aide de ce profil et spécifier les sessions ciblées.Tampon de commandes par session — Les sessions lentes ne bloquent plus les autres sessions.Mappe `configure` explicite pour les commandes ponctuelles — Par appareil base,préréglage,monture,force_gate,amortissement, ainsi que pour chaque session profil et base Mais tout configurer Il en fait désormais partie. Comme il est aligné sur la carte de configuration de sortie, le contenu envoyé correspond à celui lu lors du cycle aller-retour.Support d'appareil personnalisable — 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 conversion explicite. Si vous modifiez manuellement le montage, les préréglages sont automatiquement personnalisé passe à.Champ de commande nommé — à usage général valeurs Au lieu d'un tableau,position,vecteur,angles,couples On utilise.définir les couples angulaires mais définir_couple_angulaire remplace (l'emploi du singulier est déconseillé).Extension du cadre de session — Dans les trames de session des versions v3.0 et v3.1, une fonctionnalité extensible config,État,statut Des objets ont été ajoutés. Les nouveaux champs de sortie sont les suivants :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 détaillées config.*, et état.sécurité(masqué par défaut) est disponible.Mise à jour partielle de la conversion — Dans les montages, les transformations d'espace de travail et les formes de navigation, le sous-champ que vous souhaitez modifier (position,rotation,échelle) uniquement.HTTP {#http}
GET / — Version du service.GET/POST/DELETE /paramètres et /paramètres/* — Il s'agit d'une API complète de configuration 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 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 n'importe quel périphérique à l'aide de l'index (dans la partie « Inverse3 », il faut indiquer /inverse3/0/...、Tous les appareils de la gamme Inverse sont équipés de inverse...).Harmonisation des formats de requête et de réponse — Le corps des requêtes POST/GET est identique à celui des WebSockets données_de_commande Le format JSON est utilisé. Le code écrit pour l'un des protocoles de transport fonctionne également avec l'autre.Enveloppe « opt-in » — vers n'importe quel itinéraire ?format=json pour l'activer./paramètres* et GET /retour_à_la_page_d'accueil est, par défaut, {ok, erreur, données} . Si vous utilisez le format brut, ?format=simple Spécifiez .Caractères génériques du sélecteur de session — Dans le nom du profil,*(chaîne de caractères quelconque) et ?(Un caractère quelconque) peut être utilisé.Sélecteur décodé en pourcentage — %2A,%3A Ces éléments, entre autres, sont décodés avant le routage.Événements {#events}
communication/événements/port Le flux d'événements WebSocket dédié ci-dessus.24 catégories d'événements typés, comprenant notamment le cycle de vie des appareils, les fonctions de sécurité (freinage d'urgence, détection de corps étrangers, calage), les échecs d'étalonnage, les alertes de batterie, les avertissements de session, les baisses et baisses importantes du taux de contrôle, la validation des entrées et les conseils non recommandés.Observabilité {#observability}
Lors du profilage, les messages de journal sont transmis à Tracy dans une couleur correspondant à leur niveau.Nous avons configuré une zone Tracy pour tous les gestionnaires HTTP.Événements statistiques relatifs au timing de la boucle principale.Possibilité de configurer le répertoire des journaux et le nom d'hôte du serveur (compatible avec Docker).Fonctionnalités prévues pour la version 3.6 {#coming-in-36}
Effets haptiques SDF (SDF HFX) — Les fonctionnalités de base sont incluses dans la version 3.5 (modules, cycle de vie, sérialisation des commandes et des états fournis par les modules). L'API publique devrait être disponible dans la version 3.6, accompagnée d'une documentation complète.Points à améliorer {#improvements}
Filtre de vibrations de puissance — Il intègre 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 fenêtre de désactivation asymétrique.Filtre « Force Gate » en temps d'exécution — via WebSocket ou HTTP configure.force_gate.gain Vous pouvez effectuer la configuration à l'aide de cette option. Il est également possible de définir des valeurs par défaut permanentes.La fréquence maximale de la boucle principale a été portée à 32 kHz — pour les applications nécessitant une grande précision.Réduction de la taille de la charge utile WebSocket — Sous-champ de conversion dont la valeur par défaut est l'identité (position = 0,rotation = identité,échelle = 1) sont désormais omis par défaut dans la sortie. Cela permet de réduire la taille de la charge utile et de rétablir la compatibilité avec la limite de 4 Ko imposée aux messages par les anciens paquets Unity. Pour les consommateurs souhaitant inclure tous les champs dans la sortie, deux paramètres avancés (sérialisation/champs_explicites,sérialisation/forcer_la_transformation_complète) sont disponibles.Réduction du jitter dans la boucle principale — Le traitement des messages WebSocket ne bloque désormais plus le tick de la boucle principale, que ce soit lors de l'analyse du JSON ou lors de la transmission sur le réseau. La planification des ticks de session a été déplacée avant la sérialisation des réponses.Par défaut, le serveur n'accepte que « localhost » — L'accès au réseau est,communication/lier_toutes_les_interfaces Vous pouvez l'activer explicitement dans les paramètres.Les caractères génériques du sélecteur de périphériques utilisent la syntaxe de correspondance en début de chaîne.(Exemple : inverse (Compatible avec tous les appareils de la gamme Inverse).Commande de déchargement ,force_gate à côté de configurer Vous êtes désormais sur la carte.Il remplace désormais l'enregistreur de fichiers à rotation et permet de configurer un répertoire.Commandes et états fournis par le module — Le module permet d'ajouter des commandes personnalisées, de configurer des champs et d'intégrer des informations d'état dans les trames WebSocket, sans modifier le schéma de base.Corrections {#fixes}
Parmi les corrections de bogues effectuées au cours de l'année, voici celles qui ont eu un impact particulièrement important.
Instabilité de la vitesse de session(dans certaines conditions).GripHook (Verse Grip Stopper) ne se déverrouillait pas correctement lorsque la simulation n'était pas en cours d'exécution.Inverse3 Le délai d'expirationétant trop court, une boucle de déconnexion se produisait sur les appareils à démarrage lent.Windows Arrêt incomplet du service — Le serveur HTTP n'était pas toujours correctement nettoyé lors de l'arrêt.Boucle de reconnexion(lorsque le service envoie une commande non prise en charge par une ancienne version du micrologiciel).L'énumération des périphériques Bluetoothgénérait un volume important de journaux sur les systèmes équipés d'un adaptateur Bluetooth.Plantage survenant lors du redémarrage successif du service.Blocage du dongle Wireless Verse Grip(sur un ordinateur portable sous Ubuntu, lors de la mise en veille ou au réveil).La procédure d'établissement de la connexion du Wireless Verse Grip sous Linux et macOSeffectue désormais correctement une procédure de secours en cas d'échec de la première tentative de détection.Emplacement des fichiers de configuration de macOS — La configuration n'indique pas un chemin d'accès erroné, mais ~/Bibliothèque/Application Support/ est désormais enregistré dans.Gestion des signaux SIGSEGV sous Linux et macOS — Lorsque la capture des plantages multithread est activée, le processus ne se met plus en boucle en cas de signal fatal.Remplacement des commandes entre sessions — Il arrivait parfois que les commandes de configuration d'une session soient remplacées en arrière-plan par celles d'une autre session ; désormais, elles sont correctement filtrées et fusionnées.Remplacement des paramètres via les commandes de sondage — position_de_la_sonde Les sessions de surveillance envoyées (par exemple : Hub « Haply ») ne remplaçent plus automatiquement les modifications en attente apportées aux paramètres « basis », « preset » et « profile ».Affichage de la poignée du prototype — Le matériel du prototype s'affichait par erreur comme une poignée standard au lieu d'une poignée personnalisée.La convention de matrice `set_basis` traditionnelles'applique à nouveau aux clients qui n'ont pas encore effectué la migration.Inverse3 Le « kick » forcéne provoque plus de pic de puissance résiduel lors de la déconnexion de la session.Perte de connexion WebSocket(lors d'un cycle rapide de connexion et de déconnexion).Le `session_id` de WebSocket Cependant, dans certaines charges utiles de transmission, 0 Il avait été sérialisé sous cette forme.Windows Bon, alors,--dev même lorsqu'on l'associe à --niveau-journal est désormais respecté (alors qu'auparavant débogage (… avait été réinitialisé sans que personne ne s'en aperçoive).Obsolète {#deprecations}
Les fonctionnalités suivantes continueront de fonctionner, mais elles devraient être supprimées dans une prochaine version majeure. Le cas échéant, la réponse contiendra avertissement_de_dépréciation Il contient des champs.
| Déconseillé | À remplacer par |
|---|---|
| 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 concernant la compatibilité {#compatibility-notes}
Il n'y a pas eu de changements rompant la compatibilité depuis la version 3.4.19. Il convient de noter deux points concernant les intégrations existantes :
Les réponses des points de terminaison HTTP non recommandés contiennent :avertissement_de_dépréciation Un champ a été ajouté. Pour les clients qui effectuent une validation stricte du schéma de réponse, veuillez les configurer de manière à accepter ce champ supplémentaire.WebSocket données_de_commande situé à valeurs Ce champ est obsolète, mais il continue d'être analysé. Il est recommandé d'utiliser des champs nommés.Tutoriels et documentation {#tutorials-documentation}
Nouveaux tutoriels: 05 Contrôle de position, 06 Combinaisons (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: Elle a été ajoutée à tous les tutoriels C++, parallèlement à la version existante nlohmann/json (cpp-glz/).Réécrire tous les tutoriels, nous avons assuré la compatibilité avec l'API v3.1 (port 10001,fichier de configuration prédéfini, champ de commande nommé,print_state() (aide).Suppression — L'ancien tutoriel sur le Verse Grip Stopper a été supprimé et remplacé par un nouveau tutoriel sur les combinaisons.Nous avons mis à jour les documents publics(guide du SDK, référence API, pages consacrées au matériel).
