v3.5.0

Il s'agit de notre version la plus complète à ce 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 d'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 entière consacrée à la correction de bogues et à l'amélioration de l'ergonomie.

Points forts

• Couche mathématique 3D unifiée: un pipeline de transformations combinables comprenant des primitives complètes pour la base de l'appareil (trame), la transformation de montage, la transformation de l'espace de travail et la transformation de navigation, ainsi que des conversions explicites entre l'espace local, l'espace de session, l'espace d'application et l'espace interne.
• Navigation par bulles – Navigation dans de grands espaces de travail virtuels via des zones délimitées (primitives SDF) avec un contrôle de la vitesse en fonction de la vitesse, une détection des collisions tenant compte de l'hystérésis et, en option, un déplacement vers le curseur. Entièrement configurable via HTTP et WebSocket avec aller-retour via l'espace d'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.
• Settings-API – un système complet de paramètres de type clé-valeur, doté de fonctionnalités HTTP CRUD, d'indicateurs de type, de restrictions de plage et de descriptions, qui remplace l'ancien fichier de configuration imbriqué.
• Configuration uniforme des appareils – un ensemble commun de routes HTTP pour chaque appareil : basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
• Minverse s synchronisées et étalonnage du stylet: l'appareil et le stylet sont désormais étalonnés ensemble ; l'étalonnage reste verrouillé jusqu'à ce qu'un stylet soit physiquement connecté.
• Améliorations du confort d'utilisation pour HTTP – des sélecteurs de périphériques basés sur un index (permettant d'accéder à un périphérique via son index, sans avoir besoin d'un identifiant), une structure uniforme de requête/réponse, partagée avec WebSocket, une fonctionnalité pouvant être activée en option {ok, error, data}-Enveloppe (?format=json) et les sélecteurs de session génériques.

Nouvelles fonctionnalités

Appareils

• Minverse – Fonctionnalités officiellement prises en charge dans cette version : détection, procédure de mise en état de préparation, notifications de sécurité et procédure d'étalonnage synchronisée.
• « Ruko » et « Kingfisher » sont désormais reconnus comme des types de produits « Griff » officiels.
• Prise en charge des simulateurs de périphériques: les périphériques simulés par logiciel peuvent être détectés et pilotés au même titre que le matériel physique.
• Protection contre les boucles de connexion – Les ports défectueux sont automatiquement bloqués ; pour les réinitialiser, il faut utiliser POST /ports/{port}/reset.
• Détection de la prise « Heartbeat » : détection fiable du moment où une poignée est saisie ou lâchée, avec suppression des faux déclenchements.

Sessions, commandes et WebSocket

• Filtrage et persistance des profils de session – Les sessions indiquent un nom de profil et la version requise du SDK ; le service mémorise ces deux informations d'une connexion à l'autre. Les clients et les outils de surveillance peuvent filtrer les sessions en fonction 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 les autres.
• Explizite configure-Tableau des commandes ponctuelles – basis, preset, mount, force_gate, damping par appareil ainsi que profile et basis Pour chaque session, tous les éléments figurant dans configure sont transmises et adaptées à la carte de configuration de sortie, de sorte que les données envoyées correspondent à celles reçues.
• Support d'appareil réglable – sélectionnez 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 ; les modifications manuelles du montage règlent 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 remplacé set_angular_torque (la forme au singulier est désuète).
• Extensions du cadre de session – Les cadres de session des versions v3.0 et v3.1 contiennent désormais des éléments extensibles config-, state- et status-Objets ; 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, plus détaillées config.*-Felder et status.safety (masqué par défaut).
• Transformations partielles - Mises à jour – n'envoyez que les sous-champs que vous souhaitez modifier (position, rotation, scale), pour Mount, la transformation de l'espace de travail et le formulaire de navigation.

HTTP

• GET / – Version de service.
• GET/POST/DELETE /settings et /settings/* – API de paramètres complète pour les 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 d'application de la session indiquée.
• Sélecteurs d'appareils basés sur un index – accédez à n'importe quel appareil via son index, sans connaître son identifiant (/inverse3/0/... pour commencer Inverse3; /inverse*/*/... (pour tous les appareils de la gamme Inverse).
• Structure uniforme des demandes et des réponses – Les requêtes POST et GET utilisent les mêmes command_data- Les structures JSON, comme WebSocket : le code écrit pour un protocole de transport fonctionne également avec l'autre.
• Enveloppe activable (en option) über ?format=json sur chaque itinéraire ; /settings* et GET /home_return utilisent par défaut {ok, error, data}. Utilisez ?format=plain pour la structure brute.
• Caractères génériques dans les sélecteurs de session – * (chaîne de caractères quelconque) et ? (un seul caractère) dans les noms de profil.
• Sélecteurs codés en pourcentage – %2A, %3A etc. sont décodés avant le routage.

Événements

• Flux d'événements WebSocket personnalisé sur communication/events/port.
• 24 catégories d'événements standardisées, notamment concernant le cycle de vie des appareils, la sécurité (frein électronique, détection de corps étrangers, blocage), les erreurs d'étalonnage, les alertes relatives à la batterie, les alertes de session, les fréquences de régulation faibles et critiques, la validation des entrées et les indications concernant les fonctions obsolètes.

Observabilité

• Lors du profilage, les messages de journal sont transmis à Tracy avec des couleurs correspondant à chaque niveau.
• 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).

Perspectives pour la version 3.6

• Effets haptiques SDF (SDF HFX) – Les principes de base ont déjà été implémentés dans la version 3.5 (module, cycle de vie, sérialisation des commandes et des états fournis par le module), et l'API publique, accompagnée d'une documentation complète, sera disponible dans la version 3.6.

Améliorations

• Filtrage des oscillations de force – détection des oscillations par axe, restauration progressive en huit étapes, réglage de l'entrée avec hystérésis et fenêtres d'activation asymétriques.
• Filtre « Force-Gate » à l'exécution – configurable via configure.force_gate.gain via WebSocket ou HTTP, avec une valeur par défaut enregistrée de manière permanente.
• 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 des valeurs d'identité par défaut (position = 0, rotation = identity, scale = 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 (serialization/explicit_fields, serialization/force_complete_transforms) réintègrent tous les champs, pour les applications qui en ont besoin.
• Réduction de la gigue de la boucle principale – Le traitement des messages WebSocket ne bloque plus l'horloge de la boucle principale pendant l'analyse JSON et lors de l'envoi sur le réseau ; la planification de l'horloge des sessions a été déplacée avant la sérialisation des réponses.
• Par défaut, les serveurs ne sont accessibles que via « localhost ». – Pour permettre l'accès au réseau, activez le paramètre communication/bind_all_interfaces.
• Les caractères génériques dans les sélecteurs de périphériques utilisent la 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 configure- Carte déplacée.
• L'enregistreur de fichiers à rotation remplace l'ancien ; le répertoire est configurable.
• Commandes et états fournis par les modules – Les modules peuvent intégrer leurs propres commandes, champs de configuration et états dans le cadre WebSocket sans modifier le schéma de base.

Corrections de bogues

Une année marquée par de nombreuses corrections de bogues ; les plus importantes sont répertoriées ci-dessous.

• Vitesse irrégulière de la session 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 courts et provoquaient des boucles de connexion sur les appareils qui mettaient du temps à démarrer.
• Arrêt incorrect du service sous Windows — le serveur HTTP n'était pas toujours nettoyé lors de l'arrêt du système.
• Boucle de reconnexion lorsque le service envoyait des commandes non prises en charge à des versions antérieures du micrologiciel.
• La liste des appareils Bluetooth a saturé le journal sur les systèmes équipés de cartes Bluetooth.
• Plantage lors de plusieurs redémarrages successifs du service.
• Blocage du dongle sans fil Verse-Grip sur les ordinateurs portables sous Ubuntu après la mise en veille ou la sortie de veille.
• Le protocole de connexion du Verse Grip sans fil 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 ~/Library/Application Support/ au lieu d'être enregistré dans le mauvais dossier.
• Traitement du signal SIGSEGV sous Linux et macOS — le processus ne reste plus bloqué en boucle en cas de signaux fatals lorsque la journalisation des plantages est activée pour plusieurs threads.
• Remplacement des commandes d'une session à l'autre — 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 — Séances de suivi (par exemple, Haply Hub), qui probe_position Les modifications en attente apportées à la base, au préréglage ou au profil ne sont plus automatiquement enregistrées.
• 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.
• La convention de nommage « Matrix » obsolète de set_basis sera à nouveau pris en compte pour les clients qui n'ont pas encore été migrés.
• L'impulsion de force générée par Inverse3 lors de la coupure de la session ne produit plus de pic de force résiduelle.
• Condition de concurrence en cas de perte de connexion WebSocket lors d'une succession rapide d'opérations de connexion et de déconnexion.
• WebSocket session_id a été détecté dans certaines charges utiles sortantes sous la forme de 0 sérialisé.
• Sous Windows, on --log-level désormais également disponible en combinaison avec --dev pris en compte (auparavant, il était tacitement fixé à debug réinitialisé).

Éléments obsolètes

Toujours opérationnel, mais sera supprimé dans une prochaine version majeure. Les réponses peuvent comporter un champ deprecation_warning.

Obsolète	Ersatz
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	API des paramètres
POST /experimental/features/screensaver_enable	API des paramètres
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
Au niveau de la session WebSocket set_basis	configure.basis

Remarques concernant la compatibilité

Par rapport à la version 3.4.19, il n'y a pas de changements majeurs entraînant des incompatibilités. Deux remarques à prendre en compte pour les intégrations existantes :

1. Les points de terminaison HTTP obsolètes contiennent désormais un champ deprecation_warning dans la réponse — Les clients qui valident rigoureusement les schémas de réponse devraient autoriser ce champ supplémentaire.
2. Le champ values dans WebSocket command_data Cette syntaxe est obsolète, mais elle continue d'être analysée ; privilégiez l'utilisation des champs nommés.

Tutoriels et documentation

• Nouveaux tutoriels: 05 Régulation de position, 06 Combiné (Inverse3 + Verse Grip), 07 Notions de base et montage, 08 Configurateur à distance HTTP, 09 Commande à distance 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é réécrits pour l'API v3.1 (Port 10001, configure.preset, champs de commande nommés, print_state()-Fonctions auxiliaires).
• L'ancien tutoriel sur le Verse-Grip-Stopper a été supprimé — il a été remplacé par le nouveau tutoriel combiné.
• La documentation publique a été mise à jour dans l'ensemble des guides SDK, de la documentation de référence de l'API et des pages consacrées au matériel.