v3.5.0

Notre plus importante version depuis la réécriture 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 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 — parcourez de vastes espaces de travail virtuels à travers des zones de forme définie (primitives SDF), avec un contrôle de vitesse calé sur la vélocité, une détection de collision tenant compte de l'hystérésis et une dérive facultative 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 de fréquence de contrôle et aux indications de dépréciation.
• API de paramètres — un système complet de paramètres clé-valeur avec opérations CRUD HTTP, indications de type, contraintes de plage et descriptions, remplaçant l'ancien fichier de configuration imbriqué.
• Configuration d'appareil cohérente — un seul ensemble de routes HTTP pour chaque appareil : basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
• Étalonnage synchronisé Minverse et 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 de HTTP — sélecteurs d'appareils par index (ciblez un appareil par son index, sans identifiant), forme unifiée de requête et de réponse commune avec WebSocket, enveloppe {ok, error, data} activable (?format=json) et sélecteurs de session à caractères génériques.

Nouvelles fonctionnalités

Appareils

• Minverse — prise en charge officielle incluse dans cette version : détection, séquence de mise en route, notifications de sécurité et flux d'étalonnage synchronisé.
• Ruko et Kingfisher sont reconnus comme 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, en parallèle du matériel réel.
• Protection contre les boucles de connexion — les ports au comportement anormal sont bloqués automatiquement; réinitialisez-les avec POST /ports/{port}/reset.
• Signal de présence de la fixation du stylet — détection fiable de la fixation et du retrait de la poignée, avec anti-rebond.

Sessions, commandes et WebSocket

• Filtrage et persistance des profils de session — les sessions déclarent un nom de profil et une version requise du SDK, que le service mémorise d'une reconnexion à l'autre; les clients et les outils de supervision peuvent filtrer et cibler les sessions selon ce profil.
• Tampons de commandes par session — une session lente ne peut plus bloquer une autre.
• Dictionnaire configure explicite 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 aligné sur celui de la sortie, de sorte que ce que vous envoyez se retrouve à 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 à custom.
• Champs de commande nommés — position, vector, angles et torques remplacent le tableau générique values.
• set_angular_torques remplace set_angular_torque (forme au singulier dépréciée).
• Extensions des trames de session — les trames de session v3.0 et v3.1 transportent désormais les objets extensibles config, state et status; les nouveaux champs de sortie incluent 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, la transformation de l'espace de travail et la forme 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 — ciblez n'importe quel appareil par son index, sans connaître son identifiant (/inverse3/0/... pour le premier Inverse3; /inverse*/*/... pour tous les appareils de la famille Inverse).
• Structure unifiée de requête et de réponse — les corps POST/GET utilisent les mêmes structures command_data JSON que WebSocket; le code écrit pour un 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.
• Décodage 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 typés, notamment le cycle de vie des appareils, la sécurité (frein électronique, détection d'objets étrangers, blocage), les échecs d'étalonnage, les alertes de batterie, les avertissements de session, la fréquence de contrôle basse ou critique, la validation des entrées et les indications de dépréciation.

Observabilité

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

À venir dans la version 3.6

• Effets haptiques SDF (SDF HFX) — les fondations 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 livrée 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 de force à l'exécution — configurable via configure.force_gate.gain sur 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.
• Charges utiles WebSocket réduites — les sous-champs de transformation à valeur identité par défaut (position = 0, rotation = identity, scale = 1) sont omis de la sortie par défaut, 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.
• Gigue réduite 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 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 réseau avec le paramètre communication/bind_all_interfaces.
• Les caractères génériques des sélecteurs d'appareils utilisent une syntaxe de préfixe (p. ex. inverse* correspond à tous les appareils de la famille 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 injecter 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 erratique dans certaines conditions.
• GripHook (Verse Grip Stopper) ne se libérait pas proprement lorsqu'aucune simulation n'était en cours d'exécution.
• Les délais d'attente de Inverse3 étaient trop agressifs et provoquaient des boucles de déconnexion sur les appareils à démarrage lent.
• Arrêt non propre du service sur 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.
• L'énumération des appareils Bluetooth saturait le journal sur les systèmes dotés d'adaptateurs Bluetooth.
• Plantage lorsque le service était redémarré plusieurs fois de suite.
• Gel du dongle sans fil Verse Grip sur les ordinateurs portables Ubuntu après une mise en veille et une reprise.
• La séquence de connexion sans fil du Verse Grip sur Linux et macOS bascule maintenant correctement sur une méthode de repli lorsque la première tentative de détection échoue.
• Emplacement du fichier de configuration sous macOS — la configuration est maintenant enregistrée dans ~/Library/Application Support/ au lieu de l'ancien chemin incorrect.
• Gestion du signal SIGSEGV sur Linux et macOS — le processus ne boucle 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 silencieusement remplacées par celles d'une autre ; elles sont maintenant filtrées et fusionnées correctement.
• Les commandes de sonde écrasent la configuration — les sessions de surveillance (p. ex. Haply Hub) qui envoient probe_position n'écrasent plus silencieusement les changements en attente de base, de préréglage ou de profil.
• Affichage des poignées prototypes — le matériel prototype apparaissait à tort comme une poignée standard au lieu d'une poignée personnalisée.
• La convention de matrice héritée set_basis est de nouveau prise en charge pour les clients qui n'avaient pas encore migré.
• À-coup de force de Inverse3 lors de la déconnexion d'une session ne produit plus de pic de force résiduel.
• Condition de course lors de la perte de connexion de WebSocket pendant des cycles rapides de connexion et de déconnexion.
• WebSocket session_id était sérialisé à 0 dans certaines charges utiles sortantes.
• Sur Windows, --log-level est maintenant respecté lorsqu'il est combiné avec --dev (auparavant, il était silencieusement réinitialisé à debug).

Obsolescences

Toujours fonctionnels, mais ils seront supprimés dans une future version majeure. Les réponses incluent un champ deprecation_warning lorsque c'est 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 incompatible majeur par rapport à 3.4.19. Deux remarques mineures pour les intégrations existantes :

1. Les points de terminaison HTTP obsolètes incluent maintenant un champ deprecation_warning dans la réponse — les clients qui valident strictement 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é.
• Documentation publique mise à jour dans les guides du SDK, la référence de l'API et les pages sur le matériel.