SDK Haply 3.5.0
Il s'agit de notre plus importante mise à 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 de Minverse, un flux d'événements typé, une API de paramètres complète et une interface HTTP plus épurée — sans compter une année de corrections de bogues et d'améliorations en matière d'ergonomie.
Points forts
Couche mathématique 3D unifiée — un pipeline de transformation modulable doté de primitives de premier ordre pour la 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 — naviguer dans de vastes espaces de travail virtuels à travers des zones de forme définie (primitives SDF), avec un contrôle du débit proportionnel à la vitesse, 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é — un canal d'événements WebSocket dédié au cycle de vie des appareils, aux alertes de sécurité, à l'étalonnage, à la batterie, aux avertissements relatifs à la fréquence de contrôle et aux avis 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 des appareils — un seul ensemble d'enregistrements HTTP pour chaque appareil : base, monture, préréglage, transformer, filtres, latéralité, mise à l'échelle du couple, compensation de la gravité, Retour à l'accueil.Étalonnage synchronisé de Minverse 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 de l'ergonomie pour HTTP — sélecteurs d'appareils par index (cibler un appareil par son index, sans avoir besoin d'un identifiant), structure unifiée de requête et de réponse partagée avec WebSocket, enveloppe {ok, erreur, données} à activer (?format=json) et des sélecteurs de session génériques.Nouvelles fonctionnalités
Appareils
Minverse — prise en charge officielle incluse dans cette version : détection, séquence de préparation, notifications de sécurité et flux d'étalonnage synchronisé.Ruko et Kingfisher sont désormais reconnus comme des modèles officiels de poignées.Prise en charge des simulateurs d'appareils — détection et communication avec des appareils simulés par logiciel, parallèlement au matériel réel.Protection contre les boucles de connexion — les ports défaillants sont automatiquement bloqués ; réinitialisation avec 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 la version du SDK requise, que le service conserve d'une reconnexion à l'autre ; les clients et les outils de surveillance 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 explicite de `configure` pour les commandes ponctuelles — base, préréglage, monture, force_gate, amortissement par appareil, ainsi que profil et base par session, désormais tous regroupés dans configurer — aligné sur le dictionnaire de configuration de sortie, de sorte que ce que vous envoyez corresponde à ce que vous relisez.Montage d'appareil personnalisable — choisissez un préréglage d'espace de travail intégré (valeurs par défaut, avant du bras, bras_avant_centré, LED avant, led_avant_centré) ou envoyez une transformation explicite ; toute modification manuelle du montage fait automatiquement basculer le préréglage sur personnalisé.Champs de commande nommés — position, vecteur, angles, couples remplacent le tableau générique valeurs.définir les couples angulaires remplacer définir_couple_angulaire (le singulier est déprécié).Extensions des trames de session — Les trames de session v3.0 et v3.1 contiennent désormais des objets extensibles config, État et statut; les nouveaux champs de sortie comprennent force_du_curseur, position_du_curseur, couples angulaires actuels, position_angulaire_actuelle, domaine_de_contrôle, mode_de_contrôle, transformer, vitesse_de_transformation, des config.* enrichis et état.sécurité (masqué par défaut).Mises à jour partielles des transformations — N'envoyez que les sous-champs que vous souhaitez modifier (position, rotation, échelle) pour le montage, l'aménagement de l'espace de travail et le mode de navigation.HTTP
GET / — version du service.GET/POST/DELETE /paramètres et /paramètres/* — 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 JSON données_de_commande comme WebSocket ; le code écrit pour un protocole de transport fonctionne avec l'autre.Enveloppe facultative via ?format=json sur n'importe quelle route ; /paramètres* et GET /retour_à_la_page_d'accueil utilisent {ok, erreur, données} par défaut. Utilisez ?format=simple pour obtenir la structure brute.Caractères génériques dans les sélecteurs de session — * (une suite de caractères) et ? (un seul caractère) dans les noms de profil.Sélecteurs décodés en pourcentage — %2A, %3A, etc. sont décodés avant le routage.Événements
Flux d'événements dédié WebSocket sur communication/événements/port.24 catégories d'événements types, notamment le cycle de vie des appareils, la sécurité (freinage d'urgence, détection de corps étrangers, calage), les échecs d'étalonnage, les alertes liées à la batterie, les avertissements de session, la fréquence de commande faible ou critique, la validation des entrées et les avis de dépréciation.Observabilité
Messages de journalisation transmis à Tracy, avec des couleurs correspondant à chaque 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 (adapté à Docker).À venir dans la version 3.6
Effets haptiques SDF (SDF HFX) — les bases ont été posées dans la version 3.5 (module, cycle de vie, sérialisation des commandes et de l'état fournie 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 « force-gate » à l'exécution — configurable à l'aide de 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 = identité, échelle = 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 imposée aux messages des anciens paquets Unity. Deux paramètres avancés (sérialisation/champs_explicites, sérialisation/forcer_la_transformation_complète) réintègrent 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 ; la planification des cycles de session a été déplacée avant la sérialisation des réponses.Par défaut, les serveurs sont limités à localhost — activez l'accès au réseau à l'aide du paramètre communication/lier_toutes_les_interfaces.Les caractères génériques des sélecteurs d'appareils utilisent la syntaxe du préfixe (par ex. inverse correspondent à tous les appareils de la gamme Inverse).Les commandes d'amortissement ont été déplacées dans l'objet configurer, à côté de force_gate.La journalisation à fichiers rotatifs remplace l'ancienne méthode, avec un répertoire configurable.Commandes et informations d'état fournies par les modules — les modules peuvent intégrer leurs propres commandes, champs de configuration et informations 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 répertoriées ci-dessous.
Vitesse de session irrégulière dans certaines conditions.GripHook (Verse Grip Stopper) ne se relâchait pas correctement lorsqu'aucune simulation n'était en cours.Les délais d'attente « Inverse3 » étaient trop courts et provoquaient des boucles de déconnexion sur les appareils à démarrage lent.Arrêt incorrect du service « Windows » — le serveur HTTP n'était pas toujours vidé 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 équipés d'adaptateurs Bluetooth.Blocage lors des redémarrages successifs du service.Problème de connexion de la souris sans fil Verse Grip sur les ordinateurs portables Ubuntu après la mise en veille et la reprise.La prise en charge du Verse Grip sans fil sous Linux et macOS bascule désormais correctement vers la solution 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 ~/Bibliothèque/Application Support/ au lieu de suivre la mauvaise voie.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.Commandes de sonde remplaçant la configuration — les sessions de surveillance (par exemple, Haply Hub) qui envoient position_de_la_sonde n'écrasent plus silencieusement les modifications apportées aux paramètres de base, aux préréglages ou aux profils en attente.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 `set_basis`, héritée, est à nouveau respectée pour les clients qui n'avaient pas encore effectué la migration.L'impulsion de force Inverse3 lors de la déconnexion d'une session ne génère plus de pic de force résiduel.Condition de concurrence WebSocket en cas de perte de connexion lors de cycles rapides de connexion et de déconnexion.`session_id` WebSocket était sérialisé sous la forme 0 dans certaines charges utiles sortantes.Sur Windows, --niveau-journal est désormais respecté lorsqu'il est associé à --dev (auparavant, il était réinitialisé en silence à débogage).Dépréciations
Ils sont toujours opérationnels, mais ils seront supprimés dans une prochaine version majeure. Les réponses comportent un champ avertissement_de_dépréciation le cas échéant.
| Obsolète | 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 |
| WebSocket définir_la_base au niveau de la session | configuration de base |
Notes de compatibilité
Aucune rupture de compatibilité majeure par rapport à la version 3.4.19. Deux remarques mineures concernant les intégrations existantes :
Les points de terminaison HTTP obsolètes incluent désormais un champ avertissement_de_dépréciation dans la réponse — les clients qui valident rigoureusement les schémas de réponse doivent accepter ce champ supplémentaire.Le champ valeurs de WebSocket données_de_commande 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 HTTP à distance, 09 Contrôle à distance via WebSocket, 10 Écouteur de flux d'événements.Nouvelle variante Glaze de chaque tutoriel C++ (cpp-glz/), en plus de la variante existante nlohmann/json.Tous les tutoriels réécrits pour l'API v3.1 (port 10001, fichier de configuration prédéfini, champs de commande nommés, fonctions utilitaires print_state()).Retrait 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.
