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 (provenant de type_hint) et leurs contraintes (provenant de metadata.constraint.range + 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 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 les clés de paramètres à leurs 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
}
Correspondance des types
Les indications de type renvoyées par l'API correspondent aux types JSON suivants :
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 d'écoute des 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émarrage | Adresse IP sur laquelle les serveurs HTTP et WebSocket sont à l'écoute. |
communication/bind_all_interfaces | bool | démarrage | Configurer les serveurs pour qu'ils écoutent sur 0.0.0.0 au lieu de « localhost ». |
communication/http/port | int | démarrage | Port de l'API REST HTTP (par défaut 10000). |
communication/websocket/port | int | démarrage | Port WebSocket principal de la version 3.1 (par défaut) 10001). |
communication/websocket/legacy_port | int | démarrage | Port WebSocket hérité de la version 3.0 (par défaut) 10000). |
communication/events/port | int | démarrage | Port WebSocket du flux d'événements (par défaut 10020). |
devices/…
devices/detection/…
Politique de balayage des ports série. Tous les niveaux sont avancés.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/detection/scan_period_ms | int | plage 100–10 000 ; démarrage | Intervalle entre deux balayages des ports série (ms). |
devices/detection/handshake_timeout_s | int | plage 1–15 | Délai d'expiration de la négociation par port(s). |
devices/detection/max_retries | int | plage 1–10 | Nombre maximal de tentatives de négociation 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 à chaque 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 de l'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 substitutions propres à chaque session ont la priorité.
| 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 de la porte 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 | — | Interroger le micrologiciel sur l'orientation de l'appareil lorsque celui-ci est inactif. |
devices/presets
| Clé | Type | Contraintes | Description |
|---|---|---|---|
devices/presets | json | — | Paramètres de configuration par défaut de l'appareil pour chaque type d'appareil (montage en transformation, de 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 se déclenche. |
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 se déclenche. |
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/…
Fonctionnement automatique du crochet de préhension : verrouille le curseur lorsque la poignée est tenue à la verticale.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Activer le verrouillage automatique du crochet de préhension 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 poignée. |
features/grip_hook/hall | int | plage 1 à 32 | Seuil de valeur du capteur à effet Hall déclenchant le verrouillage de la poignée. |
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 « bulle », transmises à la session lors de la première activation d'un comportement bubble.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | Position par défaut du centre de la bulle. |
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/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 d'inactivité diffusée sur les appareils Inverse3 lorsqu'aucune session n'est active.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/screensaver/enabled | bool | — | Activer l'animation de l'économiseur d'écran en cas d'inactivité 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é (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 connexion et de la déconnexion entre l'Inverse3 t l'appareil Verse Grip (avec ou sans fil). Alimente l'interface d'appairage du hub « Haply ».
| Clé | Type | Contraintes | Description |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | Activer l'appairage et le suivi de la mise en place et du retrait. |
features/verse_grip_pairing/hall_threshold_vg | int | plage 1 à 32 | Niveau du capteur à effet Hall à partir duquel l'appareil filaire VerseGrip est considéré comme fixé. |
features/verse_grip_pairing/hall_threshold_wvg | int | plage 1 à 32 | Niveau du capteur à effet Hall à partir duquel l'appareil sans fil VerseGrip est considéré comme fixé. |
features/verse_grip_pairing/detach_debounce_ms | int | plage 0–1 000 | Délai d'anti-rebond avant de confirmer 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 « fixé » à true, en contournant le capteur à effet Hall (solution de contournement en cas de panne matérielle). |
serialization/…
Mise en forme des résultats de transformation — concerne les charges utiles WebSocket et HTTP JSON.
| Clé | Type | Contraintes | Description |
|---|---|---|---|
serialization/explicit_fields | bool | — | Inclure les champs de transformation dont la valeur correspond à la valeur d'identité 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. Valeur par défaut : false. |
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 par ailleurs que rotation. Englobe serialization/explicit_fields. Valeur par défaut : false. |
session/…
Limites du planificateur de session et du pipeline de commandes.
| 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. |
session/commands/zoh_window_ms | int | — | Fenêtre de maintien d'ordre zéro — supprimer les sondes reçues pendant cette fenêtre (ms). |
session/commands/drop_warning_threshold | int | — | Nombre de commandes rejetées dans la fenêtre avant l'avertissement. |
session/commands/drop_warning_window_ms | int | — | Durée de la fenêtre glissante pour le comptage des commandes rejetées (ms). |
session/commands/tick_on_empty_batch | bool | — | Planifier un rendez-vous de main_loop même lorsqu'un lot WebSocket entier a été rejeté. |