Référence des paramètres
Ce document répertorie tous les paramètres renvoyés par le /settings/ point de terminaison avec leur clé, type (tiré de type_hint), et contraintes (tiré de metadata.constraint.range + locked le cas échéant).
A locked le réglage est en lecture seule lors de l'exécution. Il peut être modifié via le fichier de configuration ou via le Hub Haply page des paramètres, mais un redémarrage complet du système est nécessaire pour que les modifications prennent effet. Celles-ci sont indiquées démarrer 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 | Lieu |
|---|---|
| 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 mappage des clés de paramètres pour remplacer les valeurs. Les clés doivent être des clés de paramètres valides renvoyées par le /settings/ Route HTTP (voir Référence 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 /settings liste des points de terminaison (GET /settings, GET /settings/) renvoie uniquement de base paramètres par défaut. Passer ?advanced=true pour inclure les paramètres marqués comme « avancés », ?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 via POST /settings/misc/hidden_settings (pas d'équivalent pour le paramètre de requête). Filtrer les indicateurs ET ensemble — une clé marquée à la fois advanced et hidden Les deux portes doivent être ouvertes. Les commandes POST et DELETE sur une clé connue ne sont pas soumises à ces conditions.
Lectures à clé unique (GET /settings/<key>) contourner le filtre « avancé/obsolète » lorsque vous utilisez la clé canonique exacte — ce qui est utile pour les clients disposant d'informations préalables. Les clés masquées restent soumises au filtre.
Trois commutateurs d'exécution initialisent les portes ; leurs valeurs sont conservées pendant toute la durée de vie du service :
| Clé | Type | Contraintes | Description |
|---|---|---|---|
misc/advanced_settings | bool | — | Inclure advancedles paramètres marqués d'un drapeau dans GET /settings annonces (par défaut) false). Équivalent à « passer » ?advanced=true à chaque demande. |
misc/deprecated_settings | bool | — | Inclure deprecatedles paramètres marqués d'un drapeau dans GET /settings annonces (par défaut) false). Équivalent à « passer » ?deprecated=true à chaque demande. |
Mappage de 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 event-stream. La plupart des entrées ne sont actives 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 | Lier les serveurs à 0.0.0.0 au lieu de localhost. |
communication/http/port | int | démarrer | Port de l'API REST HTTP (par défaut 10000). |
communication/websocket/port | int | démarrer | Port WebSocket principal v3.1 (par défaut) 10001). |
communication/websocket/legacy_port | int | démarrer | Port WebSocket Legacy v3.0 (par défaut) 10000). |
communication/events/port | int | démarrer | Port WebSocket pour le flux d'événements (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 du port série (ms). |
devices/detection/handshake_timeout_s | int | intervalle 1–15 | Délai d'expiration de la poignée de main par port (en secondes). |
devices/detection/max_retries | int | intervalle de 1 à 10 | Nombre maximal de tentatives de reconnexion par port. |
devices/detection/failure_log_delay_s | int | intervalle 1–60 | Délai avant la nouvelle enregistrement d'un échec de détection (en secondes). |
devices/detection/block_looping_ports | bool | — | Suspendre la disponibilité du périphérique bloc lorsqu'un port en boucle est détecté. |
devices/detection/excluded_ports | json | — | Chemins d'accès aux ports série à ignorer lors de la détection. |
devices/detection/additional_ports | string[] | — | Chemins d'accès supplémentaires vers les ports série à analyser sans condition. |
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 des ports pour la détection sans fil du VerseGrip. |
devices/detection/inverse3x_description_filter | string[] | — | Sous-chaînes de description des ports pour la détection Inverse3x. |
devices/detection/extra_ports (obsolète) | string[] | — | Utilisation devices/detection/additional_ports à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente à la clé canonique. |
devices/*inverse/…
Paramètres par défaut globaux appliqués à tous les appareils Inverse3. Les modifications par session ont la priorité.
La boule était devices/inverse*/… dans la version 3.5.0 ; le caractère de début * se trouve désormais devant inverse. Les fichiers de configuration utilisant l'ancienne valeur littérale ne pourront pas être chargés sous la version 3.5.1 — veuillez les mettre à jour. Les clés elles-mêmes restent inchangées.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | intervalle 0,0–2,0 | Multiplicateur de force global appliqué à tous les appareils. |
devices/*inverse/filters/force_gate/gain | float | intervalle 0,0–1,0 | Gain par défaut de la fonction « force-gate » pour les nouvelles sessions. |
devices/*inverse/control_timeout_ms | int | plage de 50 à 10 000 | Délai d'expiration avant la levée du verrouillage de contrôle de l'appareil (en ms). |
devices/*inverse/query_orientation_on_idle | bool | — | Demander l'orientation du corps de l'appareil au micrologiciel lorsque celui-ci est en veille. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | Inclure des indicateurs de sécurité par appareil dans GET /devices/{id} instantanés. |
devices/presets
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/presets | json | — | Préréglages de configuration par défaut par 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 en dessous duquel un avertissement de batterie faible se déclenche. |
devices/wireless_verse_grip/battery/critical_threshold | int | — | Pourcentage de charge de la batterie en dessous duquel une alerte de batterie faible se déclenche. |
devices/wireless_verse_grip/battery/reset_margin | int | — | Marge d'hystérésis avant la désactivation d'un avertissement concernant la batterie. |
devices/wireless_verse_grip/filters/orientation_filter | json | démarrer | Une configuration de filtre « One Euro » pour l'orientation sans fil du VerseGrip. |
features/…
features/calibration/…
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/calibration/hall_threshold | int | plage de 1 à 32 | Niveau du capteur à effet Hall à partir duquel le stylet est considéré comme connecté pendant l'étalonnage. |
features/grip_hook/…
Comportement automatique du crochet de sélection — verrouille le curseur tant que le crochet est maintenu à la verticale.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Activer le verrouillage automatique du crochet de la poignée lorsque celle-ci est maintenue en position verticale. |
features/grip_hook/use_hall | bool | — | Utilisez le seuil du capteur à effet Hall plutôt que l'orientation pour détecter l'adhérence. |
features/grip_hook/hall | int | plage de 1 à 32 | Seuil de la valeur du capteur à effet Hall pour déclencher le verrouillage de la poignée. |
features/grip_hook/hold_duration | int | plage de 10 à 1 000 | Durée de maintien du verrouillage après le déclenchement (ms). |
features/navigation/bubble/…
Paramètres par défaut du module de navigation par bulles — transmis à la session lorsqu'un bubble le comportement est d'abord activé. Voir le Module de navigation page consacrée à 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 | — | Appliquez la configuration center lorsqu'un comportement de bulle est activé pour la première fois. |
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 auto_follow mode centré. |
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 ressort au centre de la bulle (N/m). |
features/navigation/bubble/spring_surface | float | — | Coefficient de ressort à la surface de la bulle (N/m). |
features/navigation/bubble/spring_outer | float | — | Coefficient de ressort à 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 au niveau de la limite extérieure (N/m). |
features/navigation/bubble/bump_width | float | — | Largeur de la protubérance tactile à la surface de la bulle (m). |
features/navigation/bubble/bump_stiffness | float | — | Rigidité de la protubérance 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) à 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 — sortir de la collision lorsque |ext_force| passe en dessous de collision_threshold × this. 1.0 désactive l'hystérésis. |
features/navigation/bubble/avatar_boundary_enabled | bool | — | Fixer la position de l'avatar dans le monde à la valeur configurée avatar_boundary Forme SDF. |
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écurisée. |
features/safe_trajectory/max_vel | float | intervalle 0,01–2,0 | Vitesse maximale autorisée de l'effecteur terminal (m/s). |
features/screensaver/…
Animation d'inactivité diffusée sur Inverse3 lorsqu'aucune session ne les pilote.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/screensaver/enabled | bool | — | Activer l'animation de l'économiseur d'écran en mode veille sur Inverse3 . |
features/screensaver/speed | float | intervalle 0,001–0,2 | Vitesse d'animation de l'économiseur d'écran. |
features/screensaver/distracted_speed | float | intervalle 0,001–0,2 | Vitesse de l'animation lorsque l'utilisateur est à proximité mais n'interagit pas. |
features/sdf/…
Module d'effets haptiques pour champs de distance signés (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 par défaut l'état SDF dans les données de sortie des périphériques. |
features/sdf/max_count | int | plage de 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 | — | Analyser automatiquement les champs SDF lorsque la force appliquée est proche de zéro. |
features/sdf/probe_on_zero_force/delay | float | plage de 0,001 à 60,0 | Délai avant le démarrage de la détection automatique après que la force est tombée à zéro (s). |
features/verse_grip_pairing/…
Activer/désactiver le suivi entre un Inverse3 un Verse Grip (avec ou sans fil). Permet d'utiliser l'interface utilisateur de couplage du Haply .
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | Activer le suivi des appariements / des connexions et déconnexions. |
features/verse_grip_pairing/hall_threshold_vg | int | plage de 1 à 32 | Niveau de hall à partir duquel un VerseGrip filaire est considéré comme connecté. |
features/verse_grip_pairing/hall_threshold_wvg | int | plage de 1 à 32 | Niveau de signal à partir duquel un VerseGrip sans fil est considéré comme connecté. |
features/verse_grip_pairing/detach_debounce_ms | int | plage de 0 à 1 000 | Délai d'attente avant de valider une déconnexion (en ms). |
features/verse_grip_pairing/heartbeat_ms | int | plage de 100 à 10 000 | Intervalle entre les renotifications forcées (ms). |
features/verse_grip_pairing/force_attached | bool | — | Forcer définitivement l'état associé à true, en contournant le capteur à effet Hall (solution de contournement en cas de défaillance matérielle). |
session/serialization/…
Mise en forme de la sortie de transformation — concerne les charges utiles JSON WebSocket et HTTP. Ces clés ont été déplacées depuis serialization/* à session/serialization/* dans la version 3.5.1 afin de refléter leur portée par session. Les anciens chemins d'accès sont toujours accessibles via des alias obsolètes.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | Inclure les champs de transformation dont la valeur est égale à leur valeur par défaut dans la sortie sérialisée (par exemple : 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 les appareils dédiés à l'orientation (Verse Grip, Wireless Verse Grip) qui, autrement, n'émettent que rotation. Englobe session/serialization/explicit_fields. Par défaut : false. |
serialization/explicit_fields (obsolète) | bool | — | Utilisation session/serialization/explicit_fields à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente à la clé canonique. |
serialization/force_complete_transforms (obsolète) | bool | — | Utilisation session/serialization/force_complete_transforms à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente à la clé canonique. |
session/…
Planificateur de sessions.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
session/min_simulation_rate_hz | int | plage de 20 à 500 | Fréquence minimale acceptable de simulation de l'appareil (Hz) avant le déclenchement d'un avertissement. |
rate/…
Rythme de service. Introduit dans la version 3.5.1 — les quatre rate/websocket/* Les touches ci-dessous se trouvaient auparavant sous session/commands/*; les anciens chemins d'accès sont toujours résolus via des alias obsolètes.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | Fenêtre de retenue d'ordre zéro — supprime les sondes reçues pendant cette fenêtre (en ms). |
rate/websocket/drop_warning_threshold | int | — | Nombre de commandes ignorées dans la fenêtre avant l'affichage d'un avertissement. |
rate/websocket/drop_warning_window_ms | int | — | Durée de la fenêtre glissante pour le comptage des commandes perdues (ms). |
rate/websocket/tick_on_empty_batch | bool | avancé | Prendre rendez-vous main_loop s'affiche même lorsqu'un lot entier de WebSockets a été perdu. |
session/commands/zoh_window_ms (obsolète) | int | — | Utilisation rate/websocket/zoh_window_ms à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
session/commands/drop_warning_threshold (obsolète) | int | — | Utilisation rate/websocket/drop_warning_threshold à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
session/commands/drop_warning_window_ms (obsolète) | int | — | Utilisation rate/websocket/drop_warning_window_ms à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
session/commands/tick_on_empty_batch (obsolète) | bool | — | Utilisation rate/websocket/tick_on_empty_batch à la place. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
Paramètres réservés à l'usage interne
Plusieurs familles de paramètres sont fournies hidden dans la section 3.5.1 et sont réservées à un usage interne — rate/dispatch/* (Limite de fréquence d'émission et seuils de contre-pression de l'AIMD), session/freeform/* (empreinte comportementale), et session/serialization/preview/* (expériences de pré-lancement telles que la sortie de 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 version mineure ultérieure — ne basez pas le comportement du client sur elles.