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 à 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 changements 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 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 référence de l'API). Toute clé non spécifiée utilise la valeur par défaut du service.

Par exemple, un remplacement de 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 → string
BOOL → bool
INT → int
FLOAT → float
ARR_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 sont modifiables qu'au démarrage.

Clé	Type	Contraintes	Description
`communication/serial/enabled`	`bool`	—	Activer ou désactiver la communication avec les appareils série.
`communication/bind_address`	`string`	démarrage	Adresse IP sur laquelle les serveurs HTTP et WebSocket écoutent.
`communication/bind_all_interfaces`	`bool`	démarrage	Faire écouter les serveurs 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 principal WebSocket de la version 3.1 (par défaut `10001`).
`communication/websocket/legacy_port`	`int`	démarrage	Port hérité WebSocket 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. Toutes les entrées sont de niveau avancé.

Clé	Type	Contraintes	Description
`devices/detection/scan_period_ms`	`int`	plage 100–10000 ; 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 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 à balayer 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 à 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 façon transparente à la clé canonique.

`devices/inverse*/…`

Valeurs par défaut globales appliquées à chaque appareil de la famille Inverse3. Les substitutions propres à chaque session ont préséance.

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 de la porte 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`	—	Interroger l'orientation du corps auprès du micrologiciel lorsque l'appareil est inactif.

`devices/presets`

Clé	Type	Contraintes	Description
`devices/presets`	`json`	—	Préréglages de configuration par défaut de l'appareil 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 se déclenche.
`devices/wireless_verse_grip/battery/critical_threshold`	`int`	—	Pourcentage de batterie sous lequel une alerte de batterie critique se déclenche.
`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 attaché pendant l'étalonnage.

`features/grip_hook/…`

Comportement automatique du crochet de préhension : verrouille le curseur lorsque la poignée est tenue verticalement.

Clé	Type	Contraintes	Description
`features/grip_hook/enabled`	`bool`	—	Activer le verrouillage automatique du crochet de préhension lorsque la poignée est tenue verticalement.
`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–1000	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 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/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 permise de l'effecteur terminal (m/s).

`features/screensaver/…`

Animation d'inactivité jouée sur les appareils Inverse3 lorsqu'aucune session ne les pilote.

Clé	Type	Contraintes	Description
`features/screensaver/enabled`	`bool`	—	Activer l'animation d'économiseur d'écran en inactivité 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é (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 l'appareil Verse Grip (filaire ou sans fil). Alimente l'interface d'appairage de Haply Hub.

Clé	Type	Contraintes	Description
`features/verse_grip_pairing/enabled`	`bool`	—	Activer l'appairage et le suivi de la fixation et du retrait.
`features/verse_grip_pairing/hall_threshold_vg`	`int`	plage 1–32	Niveau du capteur 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 Hall à partir duquel l'appareil sans fil VerseGrip est considéré comme fixé.
`features/verse_grip_pairing/detach_debounce_ms`	`int`	plage 0–1000	Fenêtre d'anti-rebond avant de confirmer 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 Hall (solution de contournement en cas de panne matérielle).

`serialization/…`

Mise en forme des sorties de transformation — touche les charges utiles WebSocket et HTTP JSON.

Clé	Type	Contraintes	Description
`serialization/explicit_fields`	`bool`	—	Inclure les champs de transformation dont la valeur équivaut à 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 é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 sinon 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 de simulation minimale acceptable 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 dans 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`	—	Taille de la fenêtre glissante pour le comptage des commandes rejetées (ms).
`session/commands/tick_on_empty_batch`	`bool`	—	Planifier un tick de `main_loop` même lorsqu'un lot WebSocket entier a été rejeté.

Configuration​

Correspondance des types​

communication/…​

devices/…​

devices/detection/…​

devices/inverse*/…​

devices/presets​

devices/wireless_verse_grip/…​

features/…​

features/calibration/…​

features/grip_hook/…​

features/navigation/bubble/…​

features/safe_trajectory/…​

features/screensaver/…​

features/sdf/…​

features/verse_grip_pairing/…​

serialization/…​

session/…​