Référence des paramètres
Ce document énumère tous les paramètres renvoyés par le point de terminaison /settings/, avec leur clé, leur type (tiré de type_hint) et leurs contraintes (tirées de metadata.constraint.range et de locked, le cas échéant).
Un paramètre locked est en lecture seule à l'exécution. Il peut être modifié au moyen du fichier de configuration ou depuis la page des paramètres de Haply Hub, mais un redémarrage complet du service est requis pour que les modifications prennent effet. Ces paramètres sont marqués boot dans les tableaux ci-dessous.
Configuration
Le fichier de configuration permettant de remplacer les paramètres lors du 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 référence de l'API). Toute clé non précisée utilise la valeur par défaut du service.
Par exemple, un remplacement 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 terminaison de listage /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 au moyen de POST /settings/misc/hidden_settings (il n'existe aucun équivalent sous forme de paramètre de requête). Les indicateurs de filtre se combinent par un ET logique : une clé à la fois signalée advanced et hidden exige que les deux filtres soient levés. Les requêtes POST et DELETE 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à la clé. Les clés masquées demeurent soumises au filtre.
Trois bascules d'exécution alimentent les filtres; leurs valeurs persistent pendant toute la durée de vie du service :
| Clé | Type | Contraintes | Description |
|---|---|---|---|
misc/advanced_settings | bool | — | Inclut les paramètres signalés advanced dans les listages GET /settings (valeur par défaut : false). Équivalent à transmettre ?advanced=true à chaque requête. |
misc/deprecated_settings | bool | — | Inclut les paramètres signalés deprecated dans les listages GET /settings (valeur par défaut : false). Équivalent à 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 sont modifiables qu'au boot.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
communication/serial/enabled | bool | — | Activer ou désactiver la communication avec les appareils série. |
communication/bind_address | string | boot | Adresse IP à laquelle les serveurs HTTP et WebSocket se lient. |
communication/bind_all_interfaces | bool | boot | Lier les serveurs à 0.0.0.0 plutôt qu'à localhost. |
communication/http/port | int | boot | Port HTTP de l'API REST (valeur par défaut : 10000). |
communication/websocket/port | int | boot | Port WebSocket principal de la v3.1 (valeur par défaut : 10001). |
communication/websocket/legacy_port | int | boot | Port WebSocket hérité de la v3.0 (valeur par défaut : 10000). |
communication/events/port | int | boot | 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–10000 ; 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 de consigner à 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 | — | Chemins des ports série à ignorer pendant la détection. |
devices/detection/additional_ports | string[] | — | Chemins de 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 propres à 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 famille Inverse3. Les remplacements propres à la session ont priorité.
Le glob était devices/inverse*/… dans la 3.5.0 ; le * initial se place désormais devant inverse. Les fichiers de configuration utilisant l'ancienne syntaxe littérale ne seront pas pris en compte sur la 3.5.1 — mettez-les à jour. Les clés elles-mêmes demeurent par ailleurs inchangées.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | plage 0.0–2.0 | Multiplicateur global de la force 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–10000 | Délai d'expiration avant la libération du verrou de contrôle de l'appareil (ms). |
devices/*inverse/query_orientation_on_idle | bool | — | Demander au micrologiciel l'orientation du corps lorsque l'appareil est inactif. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | Inclure 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 batterie sous lequel un avertissement de batterie faible est déclenché. |
devices/wireless_verse_grip/battery/critical_threshold | int | — | Pourcentage de batterie sous lequel une alerte de batterie critique est déclenchée. |
devices/wireless_verse_grip/battery/reset_margin | int | — | Marge d'hystérésis avant l'effacement 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 de 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 l'accroche de préhension — verrouille le curseur tant que la poignée est tenue à la verticale.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Activer le verrouillage automatique de l'accroche 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 de seuil du capteur à effet Hall déclenchant le verrouillage de l'accroche. |
features/grip_hook/hold_duration | int | plage 10–1000 | 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 de centre auto_follow. |
features/navigation/bubble/max_velocity | float | — | Vitesse de navigation maximale 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 raideur au centre de la bulle (N/m). |
features/navigation/bubble/spring_surface | float | — | Coefficient de raideur à la surface de la bulle (N/m). |
features/navigation/bubble/spring_outer | float | — | Coefficient de raideur à 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 dériver dans la direction de la collision lorsqu'une collision est active. |
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 pendant qu'une collision est active. |
features/navigation/bubble/collision_exit_ratio | float | plage (0,1] | Rapport d'hystérésis : la collision prend fin lorsque |ext_force| descend 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 jouée sur les appareils Inverse3 lorsqu'aucune session ne les pilote.
| 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 de l'animation de l'économiseur d'écran. |
features/screensaver/distracted_speed | float | plage 0.001–0.2 | Vitesse de l'animation lorsque l'utilisateur est à 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 charges utiles 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 | — | Émettre un événement lorsqu'un nouvel effet SDF est créé. |
features/sdf/events/deleted | bool | — | Émettre un événement lorsqu'un effet SDF est supprimé. |
features/sdf/events/updated | bool | — | Émettre un événement lorsqu'un effet SDF est mis à jour. |
features/sdf/probe_on_zero_force/enabled | bool | — | Sonder 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 après que la force est tombée à zéro (s). |
features/verse_grip_pairing/…
Suivi de la fixation et du retrait entre Inverse3 et un Verse Grip (filaire ou sans fil). Alimente l'interface de jumelage de Haply Hub.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | Activer le jumelage et le suivi de fixation et de retrait. |
features/verse_grip_pairing/hall_threshold_vg | int | plage 1–32 | Niveau à 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–1000 | Fenêtre d'anti-rebond avant de valider un retrait (ms). |
features/verse_grip_pairing/heartbeat_ms | int | plage 100–10000 | Intervalle entre les renotifications forcées (ms). |
features/verse_grip_pairing/force_attached | bool | — | Forcer en permanence l'état fixé à 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 — affecte les charges utiles WebSocket et HTTP JSON. Ces clés ont été déplacées de serialization/* vers session/serialization/* dans la version 3.5.1 afin de refléter leur portée par session. Les anciens chemins fonctionnent toujours grâce à des alias dépréciés.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | Inclure dans la sortie sérialisée les champs de transformation égaux à leur valeur d'identité par défaut (p. 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 émettre position, rotation et scale dans chaque sortie de transformation, y compris pour les appareils à orientation seule (Verse Grip, Wireless Verse Grip), qui n'émettent autrement que rotation. Inclut session/serialization/explicit_fields. Par défaut : false. |
serialization/explicit_fields (déprécié) | bool | — | Utilisez plutôt session/serialization/explicit_fields. Les lectures et les écritures sont redirigées de façon transparente vers la clé canonique. |
serialization/force_complete_transforms (déprécié) | bool | — | Utilisez plutôt session/serialization/force_complete_transforms. Les lectures et les écritures sont redirigées de façon transparente vers la clé canonique. |
session/…
Ordonnanceur 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/…
Cadencement du service. Introduit dans la version 3.5.1 — les quatre clés rate/websocket/* ci-dessous se trouvaient auparavant sous session/commands/*; les anciens chemins fonctionnent toujours grâce à des alias dépréciés.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | Fenêtre de maintien d'ordre zéro — supprime les sondes reçues dans cette fenêtre (ms). |
rate/websocket/drop_warning_threshold | int | — | Nombre de commandes perdues dans la fenêtre avant l'émission d'un avertissement. |
rate/websocket/drop_warning_window_ms | int | — | Taille de la fenêtre glissante utilisée pour compter les commandes perdues (ms). |
rate/websocket/tick_on_empty_batch | bool | avancé | Planifier un tick de main_loop même lorsqu'un lot WebSocket entier a été perdu. |
session/commands/zoh_window_ms (déprécié) | int | — | Utilisez plutôt rate/websocket/zoh_window_ms. Les lectures et les écritures sont redirigées de façon transparente. |
session/commands/drop_warning_threshold (déprécié) | int | — | Utilisez plutôt rate/websocket/drop_warning_threshold. Les lectures et les écritures sont redirigées de façon transparente. |
session/commands/drop_warning_window_ms (déprécié) | int | — | Utilisez plutôt rate/websocket/drop_warning_window_ms. Les lectures et les écritures sont redirigées de façon transparente. |
session/commands/tick_on_empty_batch (déprécié) | bool | — | Utilisez plutôt rate/websocket/tick_on_empty_batch. Les lectures et les écritures sont redirigées de façon transparente. |
Paramètres réservés à un usage interne
Plusieurs familles de paramètres sont marquées 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, comme la sortie en quaternions d'Euler et le routage Wireless VerseGrip). Elles sont accessibles via misc/hidden_settings à des fins de débogage, mais attendez-vous à ce qu'elles soient promues, renommées ou supprimées dans une future version mineure — ne liez pas le comportement de votre client à ces paramètres.