v3.5.0

Il s'agit de notre 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 unifiée, la prise en charge complète de Minverse, un flux d'événements typés, une API de paramètres complète et une interface HTTP plus épurée — le tout accompagné d'une année de corrections de bogues et d'améliorations en termes de confort d'utilisation.

Points forts

• Couche mathématique 3D unifiée — un pipeline de transformations modulaire doté de primitives natives pour le repère de base de l'appareil (frame), la transformation de montage, la transformation de l'espace de travail et la transformation de navigation, ainsi que des conversions explicites entre les espaces local, de session, d'application et interne.
• Navigation par bulles — explorez de vastes espaces de travail virtuels à travers des zones de forme définie (primitives SDF), avec un contrôle de la vitesse basé sur la vélocité, une détection des collisions tenant compte de l'hystérésis et une dérive optionnelle vers le curseur. Entièrement configurable via HTTP et WebSocket, avec aller-retour dans l'espace de l'application.
• Flux d'événements typés — un canal d'événements WebSocket dédié aux cycles de vie des appareils, aux alertes de sécurité, à l'étalonnage, à la batterie, aux avertissements concernant la fréquence des contrôles et aux indications de dépréciation.
• API de paramètres — un système complet de paramètres clé-valeur comprenant des opérations CRUD HTTP, des indications de type, des contraintes de plage et des descriptions, qui remplace l'ancien fichier de configuration imbriqué.
• Configuration cohérente de l'appareil — un seul ensemble d'enregistrements HTTP pour chaque appareil : basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
• Étalonnage synchronisé de l Minverse e et du stylet — l'appareil et son stylet s'étalonnent désormais ensemble ; l'étalonnage reste verrouillé tant qu'une poignée n'est pas physiquement fixée.
• Améliorations ergonomiques apportées au protocole HTTP — sélecteurs d'appareils par index (cibler un appareil par son index, sans identifiant), format unifié de requête et de réponse commun avec WebSocket, enveloppe {ok, error, data} activable (?format=json) et sélecteurs de session avec caractères génériques.

Nouvelles fonctionnalités

Appareils

• Minverse — prise en charge officielle incluse dans cette version : détection, séquence de démarrage, notifications de sécurité et flux d'étalonnage synchronisé.
• Les modèles « Ruko » et « Kingfisher » sont reconnus comme des types de poignées officiels.
• Prise en charge des simulateurs d'appareils — détection des appareils simulés par logiciel et communication avec ceux-ci, parallèlement au matériel réel.
• Protection contre les boucles de connexion — les ports présentant un comportement anormal sont automatiquement bloqués ; réinitialisez-les à l'aide de POST /ports/{port}/reset.
• Signal indiquant que le stylet est bien fixé — détection fiable de la mise en place et du retrait de la poignée, avec système anti-rebond.

Sessions, commandes et WebSocket

• Filtrage et persistance des profils de session — les sessions indiquent un nom de profil et une version requise du SDK, que le service conserve d'une reconnexion à l'autre ; les clients et les outils de supervision peuvent filtrer et cibler les sessions en fonction de ce profil.
• Mise en file d'attente des commandes par session — une session lente ne peut plus bloquer une autre.
• Dictionnaire configure spécifiquement pour les commandes ponctuelles — basis, preset, mount, force_gate, damping par appareil, ainsi que profile et basis par session, sont désormais tous regroupés dans configure. Ce dictionnaire est synchronisé avec celui de la sortie, de sorte que ce que vous envoyez apparaît à l'identique dans ce que vous relisez.
• Montage d'appareil personnalisable — choisissez 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 ; toute modification manuelle du montage fait automatiquement basculer le préréglage vers custom.
• Champs de commande nommés — position, vector, angles et torques remplacent le tableau générique values.
• set_angular_torques remplacer set_angular_torque (forme au singulier considérée comme désuète).
• Extensions des trames de session — Les trames de session v3.0 et v3.1 prennent désormais en charge les objets extensibles config, state et status; 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, des champs config.* enrichis et status.safety (masqué par défaut).
• Mises à jour partielles des transformations — n'envoyez que les sous-champs à modifier (position, rotation, scale) pour le montage, l'aménagement de l'espace de travail et le mode de navigation.

HTTP

• GET / — version du service.
• GET/POST/DELETE /settings et /settings/* — API complète de paramètres clé-valeur.
• GET /sessions/{session} et GET/POST/DELETE /sessions/{session}/profile.
• GET /devices?session=<selector> — convertit les coordonnées des appareils dans l'espace d'application d'une session donnée.
• Sélecteurs d'appareils par index — citez n'importe quel appareil à l'aide de son index, sans connaître son identifiant (/inverse3/0/... pour le premier Inverse3; /inverse*/*/... (pour tous les appareils de la gamme Inverse).
• Structure unifiée de requête et de réponse — Les corps POST/GET utilisent les mêmes structures command_data JSON ou WebSocket : le code écrit pour un mode de transport fonctionne avec l'autre.
• Enveloppe activable via ?format=json sur n'importe quelle route ; /settings* et GET /home_return utilisent {ok, error, data} par défaut. Utilisez ?format=plain pour obtenir la structure brute.
• Caractères génériques des sélecteurs de session — * (toute séquence) et ? (un seul caractère) dans les noms de profil.
• Répartition en pourcentage des sélecteurs — %2A, %3A, etc. sont décodés avant le routage.

Événements

• Flux d'événements WebSocket dédié, sur communication/events/port.
• 24 catégories d'événements types, notamment le cycle de vie des appareils, la sécurité (frein électronique, détection de corps étrangers, blocage), les échecs d'étalonnage, les alertes liées à la batterie, les avertissements relatifs à la session, la fréquence de contrôle faible ou critique, la validation des entrées et les indications de dépréciation.

Observabilité

• Messages de journalisation transmis à Tracy, avec des couleurs correspondant au niveau lors du profilage.
• Zones Tracy sur chaque gestionnaire HTTP.
• Événements liés aux statistiques de temps de la boucle principale.
• Répertoire de journalisation et nom d'hôte du serveur configurables (compatible avec Docker).

À venir dans la version 3.6

• Effets haptiques SDF (SDF HFX) — les bases sont en place dans la version 3.5 (module, cycle de vie, sérialisation des commandes et des états fournis par les modules), et l'API publique sera fournie avec une documentation complète dans la version 3.6.

Améliorations

• Filtrage des oscillations de force — détection des oscillations par axe, récupération progressive en 8 étapes, vote d'entrée avec hystérésis et fenêtres de relâchement asymétriques.
• Filtre de porte forçant l'exécution — configurable via configure.force_gate.gain via WebSocket ou HTTP, avec une valeur par défaut persistante.
• Fréquence maximale de la boucle principale portée à 32 kHz pour les applications de précision.
• Frais d'utilisation WebSocket réduits — les sous-champs de transformation dont la valeur par défaut est l'identité (position = 0, rotation = identity, scale = 1) sont omis par défaut dans la sortie, ce qui réduit la taille des charges utiles et rétablit 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établissent tous les champs pour les consommateurs qui en ont besoin.
• Réduction du temps d'exécution de la boucle principale: le traitement des messages WebSocket ne bloque plus le cycle de la boucle principale pendant l'analyse JSON et l'envoi sur le réseau ; l'ordonnancement des cycles de session a été placé avant la sérialisation des réponses.
• Serveurs limités à « localhost » par défaut — activez l'accès au réseau à l'aide du paramètre communication/bind_all_interfaces.
• Les caractères génériques des sélecteurs d'appareils utilisent une syntaxe de préfixe (par ex. inverse* correspondent à tous les appareils de la gamme Inverse).
• Les commandes d'amortissement ont été déplacées dans le dictionnaire configure, à côté de force_gate.
• Un nouveau système de journalisation par fichiers à rotation remplace l'ancien, avec un répertoire configurable.
• Commandes et états fournis par les modules — les modules peuvent intégrer leurs propres commandes, champs de configuration et sorties d'état dans la trame WebSocket, sans modifier le schéma de base.

Corrections

Une année de corrections de bogues ; les plus importantes sont présentées ci-dessous.

• Vitesse de session irrégulière dans certaines conditions.
• GripHook (Verse Grip Stopper) ne se libérait pas correctement lorsqu'aucune simulation n'était en cours d'exécution.
• Les délais d'attente de Inverse3 étaient trop courts et provoquaient des boucles de déconnexion sur les appareils à démarrage lent.
• Arrêt incorrect du service sous Windows — le serveur HTTP n'était pas toujours nettoyé lors de l'arrêt.
• Boucle de reconnexion lorsque le service envoyait des commandes non prises en charge aux anciennes versions du micrologiciel.
• La liste des appareils Bluetooth encombrait le journal sur les systèmes équipés d'adaptateurs Bluetooth.
• Plantage lorsque le service a été redémarré plusieurs fois d'affilée.
• Problème de connexion de la clé sans fil Verse Grip sur les ordinateurs portables sous Ubuntu après une mise en veille et une reprise.
• La procédure de connexion sans fil du Verse Grip sous Linux et macOS bascule désormais correctement vers une méthode de secours lorsque la première tentative de détection échoue.
• Emplacement du fichier de configuration sous macOS — la configuration est désormais enregistrée dans ~/Library/Application Support/ au lieu de l'ancien chemin erroné.
• Gestion du signal SIGSEGV sous Linux et macOS — le processus ne se bloque plus sur les signaux fatals lorsque la capture des plantages multithread est activée.
• Écrasement des commandes entre sessions — les commandes de configuration d'une session pouvaient être remplacées sans avertissement par celles d'une autre ; elles sont désormais filtrées et fusionnées correctement.
• Les commandes de sonde écrasent la configuration — les sessions de surveillance (par exemple, Haply Hub) qui envoient probe_position n'écrasent plus silencieusement les modifications en attente concernant les paramètres de base, les préréglages ou les profils.
• Affichage des poignées prototypes — le matériel prototype s'affichait à tort comme une poignée standard au lieu d'une poignée personnalisée.
• La convention de matrice héritée set_basis est à nouveau prise en charge pour les clients qui n'avaient pas encore effectué la migration.
• La force exercée par l'Inverse3, lors de la déconnexion d'une session, ne génère plus de pic de force résiduelle.
• Condition de fonctionnement en cas de perte de connexion WebSocket lors de cycles rapides de connexion et de déconnexion.
• WebSocket session_id était publié en feuilleton dans 0 dans certaines charges utiles sortantes.
• Sous Windows, --log-level est désormais respecté lorsqu'il est associé à --dev (auparavant, il était réinitialisé en silence à debug).

Obsolescences

Ils sont toujours opérationnels, mais ils seront supprimés dans une prochaine version majeure. Les réponses comportent un champ deprecation_warning lorsque cela s'avère pertinent.

Obsolète	Remplacement
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
WebSocket set_basis au niveau de la session	configure.basis

Notes de compatibilité

Aucun changement majeur incompatible par rapport à la version 3.4.19. Deux remarques mineures concernant les intégrations existantes :

1. Les points de terminaison HTTP obsolètes comportent désormais un champ deprecation_warning dans la réponse — les clients qui valident rigoureusement les schémas de réponse doivent accepter ce champ supplémentaire.
2. Le champ values dans WebSocket command_data est obsolète, mais il est toujours analysé ; privilégiez les champs nommés.

Tutoriels et documentation

• Nouveaux tutoriels: 05 Contrôle de position, 06 Combiné (Inverse3 + Verse Grip), 07 Base et montage, 08 Configurateur à distance HTTP, 09 Commande à distance WebSocket, 10 Écouteur de flux d'événements.
• Nouvelle variante Glaze de chaque tutoriel C++ (cpp-glz/), en complément 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, fonctions d'aide print_state()).
• Suppression de l'ancien tutoriel « Verse Grip Stopper » — remplacé par le nouveau tutoriel « Combiné ».
• Mise à jour de la documentation publique dans les guides du SDK, la documentation de référence de l'API et les pages consacrées au matériel.