Référence des paramètres
Ce document répertorie tous les paramètres renvoyés par le point de terminaison /settings/, avec leur clé, leur type (extrait de type_hint) et leurs contraintes (extraits de metadata.constraint.range et de locked, le cas échéant).
Un paramètre locked est en lecture seule lors de l'exécution. Il peut être modifié via le fichier de configuration ou depuis la page des paramètres de Hub Haply, mais un redémarrage complet du service est nécessaire pour que les modifications soient prises en compte. Ces paramètres sont signalés par démarrer dans les tableaux ci-dessous.
Configuration
Le fichier de configuration permettant de modifier les paramètres au démarrage du service se trouve ici :
| Plateforme | Emplacement |
|---|---|
| Windows | C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json |
| macOS | /Library/Application Support/Haply/Inverse/haply-inverse-service-config.json |
| Linux | /etc/haply-inverse-service/haply-inverse-service-config.json |
Le fichier de configuration est un objet JSON plat qui associe des clés de paramètres à des valeurs de remplacement. Les clés doivent être des clés de paramètres valides renvoyées par la route /settings/ HTTP (voir la documentation de l'API). Toute clé non spécifiée utilise la valeur par défaut du service.
Par exemple, une modification de la configuration réseau :
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
Visibilité et filtrage
Les points de fin de liste /settings (GET /settings, GET /settings/) ne renvoient que les paramètres de base par défaut. Transmettez ?advanced=true pour inclure les paramètres signalés comme avancés, et ?deprecated=true pour inclure les alias obsolètes. Les paramètres masqués sont réservés à un usage interne ; ils n'apparaissent que lorsque misc/hidden_settings est défini à l'aide de POST /settings/misc/hidden_settings (il n'existe aucun équivalent sous forme de paramètre de requête). Les critères de filtrage sont combinés par un « ET » logique : une clé à la fois indiquée advanced et hidden exige que les deux filtres soient désactivés. Les requêtes POST et DELETE portant sur une clé connue ne sont pas soumises à ces filtres.
Les lectures d'une clé unique (GET /settings/<key>) contournent le filtre « advanced/deprecated » lorsque vous utilisez la clé canonique exacte, ce qui est pratique pour les clients qui connaissent déjà cette clé. Les clés masquées restent soumises au filtre.
Trois registres d'exécution alimentent les filtres ; leurs valeurs sont conservées pendant toute la durée de vie du service :
| Clé | Type | Contraintes | Description |
|---|---|---|---|
misc/advanced_settings | bool | — | Comprend les paramètres indiqués advanced dans les listes GET /settings (valeur par défaut : false). À transmettre ?advanced=true à chaque requête. |
misc/deprecated_settings | bool | — | Comprend les paramètres indiqués deprecated dans les listes GET /settings (valeur par défaut : false). À transmettre ?deprecated=true à chaque requête. |
Correspondance des types
Les indications de type renvoyées par l'API correspondent aux structures JSON suivantes :
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3(objet avec{x, y, z})GENERIC→json(valeur structurée arbitraire)
communication/…
Ports réseau et adresses de liaison pour les serveurs HTTP, WebSocket et de flux d'événements. La plupart des entrées ne peuvent être modifiées qu'au démarrage.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
communication/serial/enabled | bool | — | Activer ou désactiver la communication avec les périphériques série. |
communication/bind_address | string | démarrer | Adresse IP à laquelle les serveurs HTTP et WebSocket se connectent. |
communication/bind_all_interfaces | bool | démarrer | Connecter les serveurs à 0.0.0.0 plutôt qu'à localhost. |
communication/http/port | int | démarrer | Port HTTP de l'API REST (valeur par défaut : 10000). |
communication/websocket/port | int | démarrer | Port WebSocket principal de la version 3.1 (valeur par défaut : 10001). |
communication/websocket/legacy_port | int | démarrer | Port WebSocket hérité de la version 3.0 (valeur par défaut : 10000). |
communication/events/port | int | démarrer | Port WebSocket du flux d'événements (valeur par défaut : 10020). |
devices/…
devices/detection/…
Politique de balayage des ports série. Toutes les entrées sont avancées.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/detection/scan_period_ms | int | plage 100–10 000 ; démarrage | Intervalle entre les analyses des ports série (ms). |
devices/detection/handshake_timeout_s | int | plage 1–15 | Délai d'expiration de la poignée de main par port (s). |
devices/detection/max_retries | int | plage 1–10 | Nombre maximal de tentatives de poignée de main par port. |
devices/detection/failure_log_delay_s | int | plage 1–60 | Délai avant d'enregistrer à nouveau un échec de détection (s). |
devices/detection/block_looping_ports | bool | — | Bloquer la disponibilité de l'appareil lorsqu'un port en boucle est détecté. |
devices/detection/excluded_ports | json | — | Série « Chemins des ports » à ignorer lors de la détection. |
devices/detection/additional_ports | string[] | — | Chemins d'accès aux ports série supplémentaires à analyser systématiquement. |
devices/detection/allowed_vendor_id_filter | string[] | — | Identifiants de fournisseur USB autorisés lors de l'énumération des ports. |
devices/detection/port_name_substring_filter | string[] | — | Sous-chaînes de nom de port spécifiques à la plateforme à rechercher. |
devices/detection/wireless_verse_grip_description_filter | string[] | — | Sous-chaînes de description de port pour la détection sans fil de VerseGrip. |
devices/detection/inverse3x_description_filter | string[] | — | Sous-chaînes de description de port pour la détection d'Inverse3x. |
devices/detection/extra_ports (obsolète) | string[] | — | Utilisez plutôt devices/detection/additional_ports. Les lectures et les écritures sont transmises de manière transparente à la clé canonique. |
devices/*inverse/…
Valeurs par défaut globales appliquées à chaque appareil de la gamme « Inverse3 ». Les modifications spécifiques à la session ont la priorité.
Le globe était devices/inverse*/… dans la version 3.5.0 ; le * La lettre « se » s'écrit désormais au début inverse. Les fichiers de configuration utilisant l'ancienne syntaxe littérale ne seront pas pris en compte dans la version 3.5.1 — veuillez les mettre à jour. Les clés elles-mêmes restent par ailleurs inchangées.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | plage 0,0–2,0 | Multiplicateur global de la puissance de sortie appliqué à tous les appareils. |
devices/*inverse/filters/force_gate/gain | float | plage 0,0–1,0 | Gain par défaut du filtre de seuil de force pour les nouvelles sessions. |
devices/*inverse/control_timeout_ms | int | plage 50–10 000 | Délai d'expiration avant le déverrouillage du contrôle de l'appareil (ms). |
devices/*inverse/query_orientation_on_idle | bool | — | Demander au micrologiciel l'orientation de l'appareil lorsqu'il est inactif. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | Intégrer les indicateurs de sécurité propres à chaque appareil dans les instantanés GET /devices/{id}. |
devices/presets
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/presets | json | — | Préréglages de configuration par défaut pour chaque type d'appareil (transformation de montage, base, etc. pour inverse_arm_front_*, inverse_led_front_*, minverse_*, verse_grip_default, wireless_verse_grip_default, custom_verse_grip_default). |
devices/wireless_verse_grip/…
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | Pourcentage de charge de la batterie en dessous duquel un avertissement de batterie faible est déclenché. |
devices/wireless_verse_grip/battery/critical_threshold | int | — | Pourcentage de charge de la batterie en dessous duquel une alerte de niveau critique de la batterie est déclenchée. |
devices/wireless_verse_grip/battery/reset_margin | int | — | Marge d'hystérésis avant la suppression d'un avertissement de batterie. |
devices/wireless_verse_grip/filters/orientation_filter | json | démarrage | Configuration du filtre « One Euro » pour l'orientation sans fil du VerseGrip. |
features/…
features/calibration/…
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/calibration/hall_threshold | int | plage 1 à 32 | Niveau du capteur à effet Hall à partir duquel le stylet est considéré comme fixé pendant l'étalonnage. |
features/grip_hook/…
Comportement automatique de la poignée de préhension — verrouille le curseur tant que la poignée est maintenue à la verticale.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Activer le verrouillage automatique de l'attache lorsque la poignée est tenue à la verticale. |
features/grip_hook/use_hall | bool | — | Utiliser le seuil du capteur à effet Hall plutôt que l'orientation pour détecter la préhension. |
features/grip_hook/hall | int | plage 1 à 32 | Valeur seuil du capteur à effet Hall déclenchant le verrouillage du dispositif d'accrochage. |
features/grip_hook/hold_duration | int | plage 10–1 000 | Durée de maintien du verrouillage après le déclenchement (ms). |
features/navigation/bubble/…
Valeurs par défaut du module de navigation Bubble — transmises à la session lorsque le comportement bubble est activé pour la première fois. Consultez la page Module de navigation pour la sémantique d'exécution de chaque champ.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | Position par défaut du centre de la bulle. |
features/navigation/bubble/center_enabled | bool | — | Appliquer le center configuré lors de la première activation d'un comportement de bulle. |
features/navigation/bubble/rotation_enabled | bool | — | Appliquer la rotation de l'espace de travail à la direction de navigation. |
features/navigation/bubble/scale_enabled | bool | — | Appliquer l'échelle de l'espace de travail à la vitesse de navigation. |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | Vitesse de dérive (m/s) en mode central auto_follow. |
features/navigation/bubble/max_velocity | float | — | Vitesse maximale de navigation dans la zone de vitesse (m/s). |
features/navigation/bubble/velocity_zone_width | float | — | Largeur de la zone de vitesse à l'extérieur de la surface de la bulle (m). |
features/navigation/bubble/reset_velocity_on_entry | bool | — | Réinitialiser la vitesse à zéro lorsque le curseur entre dans la bulle. |
features/navigation/bubble/spring_inner | float | — | Coefficient de rigidité au centre de la bulle (N/m). |
features/navigation/bubble/spring_surface | float | — | Coefficient de rigidité à la surface de la bulle (N/m). |
features/navigation/bubble/spring_outer | float | — | Coefficient de rigidité à la limite extérieure (N/m). |
features/navigation/bubble/damping_inner | float | — | Coefficient d'amortissement au centre de la bulle (Ns/m). |
features/navigation/bubble/damping_surface | float | — | Coefficient d'amortissement à la surface de la bulle (Ns/m). |
features/navigation/bubble/damping_outer | float | — | Coefficient d'amortissement à la limite extérieure (Ns/m). |
features/navigation/bubble/wall_stiffness | float | — | Rigidité de la paroi rigide à la limite extérieure (N/m). |
features/navigation/bubble/bump_width | float | — | Largeur de la bosse tactile à la surface de la bulle (m). |
features/navigation/bubble/bump_stiffness | float | — | Rigidité de la bosse tactile à la surface de la bulle (N/m). |
features/navigation/bubble/stop_at_collision | bool | — | Empêcher le centre de la bulle de se déplacer dans la direction de la collision lorsqu'une collision est en cours. |
features/navigation/bubble/collision_threshold | float | > 0 | Intensité de la force externe (N) à partir de laquelle une collision est détectée. |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | Multiplicateur appliqué à velocity_zone_width tant qu'une collision est active. |
features/navigation/bubble/collision_exit_ratio | float | intervalle (0,1] | Rapport d'hystérésis : la collision prend fin lorsque |ext_force| descendre sous collision_threshold × this. 1.0 désactive l'hystérésis. |
features/navigation/bubble/avatar_boundary_enabled | bool | — | Limiter la position mondiale de l'avatar à la forme SDF avatar_boundary configurée. |
features/safe_trajectory/…
Limiteur de vitesse pour le mouvement de l'effecteur terminal.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | Activer le limiteur de vitesse de trajectoire sécuritaire. |
features/safe_trajectory/max_vel | float | plage 0,01–2,0 | Vitesse maximale autorisée de l'effecteur terminal (m/s). |
features/screensaver/…
Animation de veille de l'économiseur d'écran diffusée sur les appareils Inverse3 lorsqu'aucune session n'est active.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/screensaver/enabled | bool | — | Activer l'animation de veille de l'économiseur d'écran sur les appareils Inverse3. |
features/screensaver/speed | float | plage 0,001–0,2 | Vitesse d'animation de l'économiseur d'écran. |
features/screensaver/distracted_speed | float | plage 0,001–0,2 | Vitesse de l'animation lorsque l'utilisateur se trouve à proximité sans interagir. |
features/sdf/…
Module d'effets haptiques à champ de distance signée (SDF HFX).
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/sdf/enabled | bool | — | Activer ou désactiver le module d'effets haptiques SDF. |
features/sdf/state_output | bool | — | Inclure l'état SDF dans les données de sortie de l'appareil par défaut. |
features/sdf/max_count | int | plage 0–128 | Nombre maximal d'effets SDF actifs (0 = illimité). |
features/sdf/events/created | bool | — | Déclencher un événement lorsqu'un nouvel effet SDF est créé. |
features/sdf/events/deleted | bool | — | Déclencher un événement lorsqu'un effet SDF est supprimé. |
features/sdf/events/updated | bool | — | Déclencher un événement lorsqu'un effet SDF est mis à jour. |
features/sdf/probe_on_zero_force/enabled | bool | — | Détecter automatiquement les champs SDF lorsque la force appliquée est proche de zéro. |
features/sdf/probe_on_zero_force/delay | float | plage 0,001–60,0 | Délai avant le sondage automatique une fois que la force est tombée à zéro (s). |
features/verse_grip_pairing/…
Suivi de la fixation et du retrait entre l'Inverse3 t un Verse Grip (avec ou sans fil). Alimente l'interface de couplage du hub « Haply ».
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | Activer le jumelage ainsi que le suivi de la pose et du retrait. |
features/verse_grip_pairing/hall_threshold_vg | int | plage 1 à 32 | Niveau d'effet Hall à partir duquel un VerseGrip filaire est considéré comme fixé. |
features/verse_grip_pairing/hall_threshold_wvg | int | plage 1 à 32 | Niveau à effet Hall à partir duquel un VerseGrip sans fil est considéré comme fixé. |
features/verse_grip_pairing/detach_debounce_ms | int | plage 0–1 000 | Délai d'anti-rebond avant de valider un retrait (ms). |
features/verse_grip_pairing/heartbeat_ms | int | plage 100–10 000 | Intervalle entre les renotifications forcées (ms). |
features/verse_grip_pairing/force_attached | bool | — | Forcer en permanence l'état défini à true, en contournant le capteur à effet Hall (solution de contournement en cas de panne matérielle). |
session/serialization/…
Mise en forme de la sortie de transformation — s'applique aux charges utiles WebSocket et HTTP JSON. Ces clés ont été déplacées depuis serialization/* vers session/serialization/* dans la version 3.5.1 afin de refléter leur portée par session. Les anciens chemins d'accès fonctionnent toujours grâce à des alias obsolètes.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | Inclure dans la sortie sérialisée les champs de transformation dont la valeur par défaut est égale à leur valeur d'identité (par ex. position: {0,0,0}, rotation: {w:1,…}). Utile lorsque votre client exige que chaque champ soit explicitement présent. Par défaut : false. |
session/serialization/force_complete_transforms | bool | — | Toujours diffuser position, rotation et scale sur chaque sortie de transformation, y compris pour les appareils à orientation unique (Verse Grip, Wireless Verse Grip), qui n'émettent autrement que rotation. Comprend session/serialization/explicit_fields. Par défaut : false. |
serialization/explicit_fields (désuet) | bool | — | Utilisez plutôt session/serialization/explicit_fields. Les opérations de lecture et d'écriture sont redirigées de manière transparente vers la clé canonique. |
serialization/force_complete_transforms (désuet) | bool | — | Utilisez plutôt session/serialization/force_complete_transforms. Les opérations de lecture et d'écriture sont redirigées de manière transparente vers la clé canonique. |
session/…
Planificateur de session.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
session/min_simulation_rate_hz | int | plage 20–500 | Fréquence minimale acceptable de simulation de l'appareil (Hz) avant le déclenchement d'un avertissement. |
rate/…
Rythme du service. Introduit dans la version 3.5.1 — les quatre clés rate/websocket/* Les éléments ci-dessous se trouvaient auparavant sous session/commands/*; les anciens chemins d'accès fonctionnent toujours grâce à des alias obsolètes.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | Fenêtre de maintien d'ordre nulle — supprime les sondes reçues pendant cette fenêtre (ms). |
rate/websocket/drop_warning_threshold | int | — | Nombre de commandes perdues pendant la fenêtre avant l'émission d'un avertissement. |
rate/websocket/drop_warning_window_ms | int | — | Durée de la fenêtre glissante utilisée pour compter les commandes perdues (ms). |
rate/websocket/tick_on_empty_batch | bool | avancé | Planifier un rendez-vous de main_loop même lorsqu'un lot WebSocket entier a été perdu. |
session/commands/zoh_window_ms (désuet) | int | — | Utilisez plutôt rate/websocket/zoh_window_ms. Les lectures et les écritures sont redirigées de manière transparente. |
session/commands/drop_warning_threshold (désuet) | int | — | Utilisez plutôt rate/websocket/drop_warning_threshold. Les lectures et les écritures sont redirigées de manière transparente. |
session/commands/drop_warning_window_ms (désuet) | int | — | Utilisez plutôt rate/websocket/drop_warning_window_ms. Les lectures et les écritures sont redirigées de manière transparente. |
session/commands/tick_on_empty_batch (désuet) | bool | — | Utilisez plutôt rate/websocket/tick_on_empty_batch. Les lectures et les écritures sont redirigées de manière transparente. |
Paramètres réservés à un usage interne
Plusieurs familles de paramètres sont mises en évidence hidden dans la version 3.5.1 et sont réservées à un usage interne — rate/dispatch/* (plafond de débit d'envoi AIMD et seuils de contre-pression), session/freeform/* (empreinte comportementale) et session/serialization/preview/* (expérimentations de sérialisation en préversion, telles que la sortie en quaternions d'Euler et le routage Wireless VerseGrip). Elles sont accessibles via misc/hidden_settings à des fins de débogage, mais sachez qu'elles sont susceptibles d'être promues, renommées ou supprimées dans une future version mineure — ne basez pas le comportement de votre client sur ces paramètres.