Guide de configuration
Ce document présente /settings/ Tous les paramètres renvoyés par le nœud, ainsi que, pour chaque paramètre, Touche,Type(Source : type_hint) et Contrainte(Source : metadata.constraint.range, et, le cas échéant, en tenant compte de locked).
locked Configurer à l'exécution comme suit : Lecture seule。Cela peut se faire via le fichier de configuration ou Hub Haply Effectuez les modifications dans la page de configuration, mais pour que celles-ci prennent effet, il faut Redémarrer complètement le service. Dans le tableau ci-dessous, ces paramètres sont indiqués par démarrer。
Configuration
Le fichier de configuration permettant de remplacer les paramètres lors du démarrage du service se trouve à l'emplacement suivant :
| 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 |
Un fichier de configuration est un Objet JSON « plat », permet d'attribuer une touche à une valeur de remplacement. La touche doit être /settings/ Clés de configuration valides renvoyées par le routage HTTP (voir Documentation de l'API). Toute clé non spécifiée utilisera la valeur par défaut du service.
Par exemple, la configuration réseau est la suivante :
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
Visibilité et filtrage
/settings Point de terminaison de liste (GET /settings,GET /settings/) Ne renvoie par défaut que Notions de base Paramètres. Entrée ?advanced=true Peut inclure des paramètres marqués comme « advanced », transmis via ?deprecated=true Peut inclure des alias obsolètes. Les paramètres masqués sont réservés à un usage interne ; ils ne sont accessibles que via POST /settings/misc/hidden_settings Paramètres misc/hidden_settings ne s'affichera qu'ensuite (en l'absence de paramètre de recherche correspondant). Les critères de filtrage sont liés par une relation logique « ET » (AND) ; en d'autres termes, ils doivent tous être cochés simultanément. advanced et hidden La clé doit être débloquée par les deux restrictions simultanément. Les opérations POST et DELETE effectuées sur une clé connue ne sont pas soumises aux restrictions susmentionnées.
Lecture à l'aide d'une seule clé de spécification précise (GET /settings/<key>), cela permet de contourner les restrictions liées aux fonctionnalités « avancées » ou « obsolètes », ce qui convient aux utilisateurs disposant déjà des connaissances nécessaires. Les clés masquées restent toutefois soumises à des restrictions.
Trois paramètres d'exécution permettent d'initialiser ces limites ; leurs valeurs restent valides pendant tout le cycle de vie du service :
| Touche | Type | Contrainte | Description |
|---|---|---|---|
misc/advanced_settings | bool | — | à GET /settings La liste contient les éléments marqués comme advanced Paramètres (par défaut) false). Ce qui revient à transmettre à chaque requête ?advanced=true。 |
misc/deprecated_settings | bool | — | à GET /settings La liste contient les éléments marqués comme deprecated Paramètres (par défaut) false). Ce qui revient à transmettre à chaque requête ?deprecated=true。 |
Mappage de types
Les indications de type renvoyées par l'API correspondent à la structure JSON suivante :
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3(y compris{x, y, z}(l'objet)GENERIC→json(valeur structurée au choix)
communication/…
Ports réseau et adresses de liaison des serveurs HTTP, WebSocket et de flux d'événements. La plupart des entrées ne s'appliquent qu'au démarrage(un redémarrage du service est nécessaire pour que les modifications prennent effet).
| Touche | Type | Contrainte | Description |
|---|---|---|---|
communication/serial/enabled | bool | — | Activer ou désactiver la communication avec les périphériques série. |
communication/bind_address | string | démarrer | Adresses IP auxquelles sont liés les serveurs HTTP et WebSocket. |
communication/bind_all_interfaces | bool | démarrer | Lier le serveur à 0.0.0.0 et non « localhost ». |
communication/http/port | int | démarrer | Port de l'API REST HTTP (par défaut) 10000). |
communication/websocket/port | int | démarrer | v3.1 Port WebSocket principal (par défaut) 10001). |
communication/websocket/legacy_port | int | démarrer | v3.0 Ancien port WebSocket (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/…
Stratégie de balayage des ports série. Toutes les entrées relèvent des paramètres avancés (advanced).
| Touche | Type | Contrainte | Description |
|---|---|---|---|
devices/detection/scan_period_ms | int | Plage : 100–10 000 ; prend effet au démarrage | Intervalle entre deux balayages du port série (en millisecondes). |
devices/detection/handshake_timeout_s | int | Plage : 1–15 | Délai d'expiration de la négociation pour chaque port (en secondes). |
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 (en secondes) avant la réenregistrement du journal des échecs de détection. |
devices/detection/block_looping_ports | bool | — | Empêcher la mise en état de l'appareil lorsqu'un port en boucle est détecté. |
devices/detection/excluded_ports | json | — | Chemin d'accès au port série à ignorer pendant la phase de test. |
devices/detection/additional_ports | string[] | — | Chemin d'accès supplémentaire au port série pour la numérisation sans condition. |
devices/detection/allowed_vendor_id_filter | string[] | — | ID de fabricant USB autorisés pendant l'énumération des ports. |
devices/detection/port_name_substring_filter | string[] | — | Sous-chaîne du nom de port, spécifique à la plateforme, à utiliser pour la correspondance. |
devices/detection/wireless_verse_grip_description_filter | string[] | — | Chaîne de caractères décrivant le port utilisé pour la détection sans fil de VerseGrip. |
devices/detection/inverse3x_description_filter | string[] | — | Chaîne de caractères décrivant le descripteur de port utilisé pour la détection Inverse3x. |
devices/detection/extra_ports (obsolète) | string[] | — | Veuillez utiliser à la place devices/detection/additional_ports。Les opérations de lecture et d'écriture sont transmises de manière transparente à la clé de spécification. |
devices/*inverse/…
Valeurs par défaut globales applicables à tous les appareils de la gamme Inverse3 . Les paramètres définis pour chaque session prévalent.
Dans la version 3.5.0, le mode des caractères génériques est le suivant : devices/inverse*/…; actuellement en tête * Situé à inverse Auparavant, les fichiers de configuration utilisant d'anciens littéraux ne pouvaient pas être liés correctement sous la version 3.5.1 ; veuillez les mettre à jour. Les clés elles-mêmes n'ont subi aucune autre modification.
| Touche | Type | Contrainte | Description |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | Plage : 0,0–2,0 | Facteur de multiplication de la force de sortie global applicable à tous les appareils. |
devices/*inverse/filters/force_gate/gain | float | Intervalle : 0,0–1,0 | Gain de commande par tension par défaut pour la nouvelle session. |
devices/*inverse/control_timeout_ms | int | Plage : 50–10 000 | Délai d'expiration (en millisecondes) avant la libération du verrou de contrôle du périphérique. |
devices/*inverse/query_orientation_on_idle | bool | — | Lorsque l'appareil est inactif, il interroge le micrologiciel pour connaître son orientation. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | à GET /devices/{id} L'instantané contient les indicateurs de sécurité de chaque appareil. |
devices/presets
| Touche | Type | Contrainte | Description |
|---|---|---|---|
devices/presets | json | — | Les préréglages de configuration par défaut pour chaque type d'appareil (y compris les transformations d'installation, « basis », etc.) s'appliquent à inverse_arm_front_*,inverse_led_front_*,minverse_*,verse_grip_default,wireless_verse_grip_default,custom_verse_grip_default). |
devices/wireless_verse_grip/…
| Touche | Type | Contrainte | Description |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | L'avertissement de batterie faible se déclenche lorsque le niveau de charge de la batterie est inférieur à ce pourcentage. |
devices/wireless_verse_grip/battery/critical_threshold | int | — | Une alerte de niveau de charge très faible se déclenche lorsque le niveau de charge de la batterie est inférieur à ce pourcentage. |
devices/wireless_verse_grip/battery/reset_margin | int | — | Supprimer la marge de rémanence avant l'avertissement de batterie faible. |
devices/wireless_verse_grip/filters/orientation_filter | json | Entrée en vigueur au démarrage | Configuration « One Euro Filter » avec poignée VerseGrip sans fil. |
features/…
features/calibration/…
| Touche | Type | Contrainte | Description |
|---|---|---|---|
features/calibration/hall_threshold | int | Plage : 1 à 32 | Pendant la procédure d'étalonnage, lorsque le niveau du capteur à effet Hall atteint cette valeur, le stylo est considéré comme étant en place. |
features/grip_hook/…
Comportement « grip-hook » automatique : le curseur se verrouille lorsque la poignée est en position verticale.
| Touche | Type | Contrainte | Description |
|---|---|---|---|
features/grip_hook/enabled | bool | — | Le verrouillage automatique « grip-hook » s'active lorsque la poignée est en position verticale. |
features/grip_hook/use_hall | bool | — | La détection de la prise en main s'effectue à l'aide du seuil du capteur à effet Hall (et non de l'orientation). |
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 pendant laquelle le verrouillage est maintenu après le déclenchement (en millisecondes). |
features/navigation/bubble/…
Valeurs par défaut du module de navigation « Bubble » lors de sa première activation bubble Transmis lors de l'exécution de l'action. Pour connaître la sémantique d'exécution de chaque champ, veuillez consulterModule de navigationPage.
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | Position par défaut du centre de la bulle. |
features/navigation/bubble/center_enabled | bool | — | Lors de la première activation du comportement « bulle », l'application a déjà été configurée pour center。 |
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 le zoom de l'espace de travail à la vitesse de navigation. |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | auto_follow Vitesse de dérive en mode central (m/s). |
features/navigation/bubble/max_velocity | float | — | Vitesse maximale de navigation (en m/s) dans la zone de vitesse. |
features/navigation/bubble/velocity_zone_width | float | — | Largeur (en mètres) de la zone de vitesse située à l'extérieur de la surface de la bulle. |
features/navigation/bubble/reset_velocity_on_entry | bool | — | Lorsque le curseur entre dans la bulle, la vitesse est remise à zéro. |
features/navigation/bubble/spring_inner | float | — | Le coefficient élastique (N/m) au centre de la bulle. |
features/navigation/bubble/spring_surface | float | — | Le coefficient de ressort à la surface de la bulle (N/m). |
features/navigation/bubble/spring_outer | float | — | Coefficient de ressort (N/m) au niveau de la limite extérieure. |
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 des bulles (Ns/m). |
features/navigation/bubble/damping_outer | float | — | Coefficient d'amortissement (Ns/m) au niveau de la limite extérieure. |
features/navigation/bubble/wall_stiffness | float | — | Rigidité (N/m) de la paroi rigide au niveau de la limite extérieure. |
features/navigation/bubble/bump_width | float | — | Largeur (en m) des reliefs tactiles à la surface des bulles. |
features/navigation/bubble/bump_stiffness | float | — | Rigidité (N/m) des protubérances tactiles à la surface des bulles. |
features/navigation/bubble/stop_at_collision | bool | — | Lorsqu'une collision se produit, empêcher le centre de la bulle de dériver dans la direction de la collision. |
features/navigation/bubble/collision_threshold | float | > 0 | Seuil de l'intensité de la force externe (en N) détectée lors d'une collision. |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | Appliqué pendant la phase d'activation par collision velocity_zone_width multiple de. |
features/navigation/bubble/collision_exit_ratio | float | Intervalle (0, 1] | Taux de rémanence : lorsque |ext_force| baisser jusqu'à collision_threshold × this Dans les cas suivants, le système se désactive.1.0 Indique que la rémanence est désactivée. |
features/navigation/bubble/avatar_boundary_enabled | bool | — | Limiter les coordonnées mondiales de l'avatar aux coordonnées configurées avatar_boundary À l'intérieur de la forme SDF. |
features/safe_trajectory/…
Limiteur de vitesse pour le mouvement des actionneurs finaux.
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | Activer le limiteur de vitesse de sécurité. |
features/safe_trajectory/max_vel | float | Plage : 0,01–2,0 | Vitesse maximale autorisée de l'actionneur terminal (m/s). |
features/screensaver/…
Animation de veille diffusée sur l'appareil « Inverse3 » en l'absence de session active.
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
features/screensaver/enabled | bool | — | Activer l'animation de l'écran de veille sur les appareils Inverse3 . |
features/screensaver/speed | float | Plage : 0,001 – 0,2 | Vitesse de l'animation de l'écran de veille. |
features/screensaver/distracted_speed | float | Plage : 0,001 – 0,2 | Vitesse de l'animation lorsque l'utilisateur est à proximité mais n'interagit pas. |
features/sdf/…
Module d'effets tactiles à champ de distance signé (SDF HFX).
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
features/sdf/enabled | bool | — | Activer ou désactiver le module d'effets tactiles SDF. |
features/sdf/state_output | bool | — | Par défaut, l'état SDF est inclus dans les données de sortie de l'appareil. |
features/sdf/max_count | int | Plage : 0 à 128 | Nombre maximal d'effets SDF actifs simultanément (0 (sans restriction). |
features/sdf/events/created | bool | — | Événement déclenché lors de la création d'un nouvel effet SDF. |
features/sdf/events/deleted | bool | — | Événement déclenché lors de la suppression d'un effet SDF. |
features/sdf/events/updated | bool | — | Événement déclenché lors de la mise à jour des effets SDF. |
features/sdf/probe_on_zero_force/enabled | bool | — | Lorsque la force appliquée est proche de zéro, le champ SDF est détecté automatiquement. |
features/sdf/probe_on_zero_force/delay | float | Plage : 0,001–60,0 | Délai (en secondes) entre la chute de la force à zéro et le début de la détection automatique. |
features/verse_grip_pairing/…
Suivi de l'état de connexion/déconnexion entre l'Inverse3 et le Verse Grip (filaire ou sans fil). Prise en charge de l'interface d'appairage du hub « Haply ».
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | Activer le suivi des appariements et des connexions/déconnexions. |
features/verse_grip_pairing/hall_threshold_vg | int | Plage : 1 à 32 | Niveau de signal Hall indiquant que le VerseGrip filaire est détecté comme étant connecté. |
features/verse_grip_pairing/hall_threshold_wvg | int | Plage : 1 à 32 | Niveau de signal Hall indiquant que le VerseGrip sans fil est détecté comme étant connecté. |
features/verse_grip_pairing/detach_debounce_ms | int | Plage : 0–1 000 | Confirmer la fenêtre temporelle de stabilisation avant la séparation (ms). |
features/verse_grip_pairing/heartbeat_ms | int | Plage : 100–10 000 | Intervalle (en ms) entre les notifications forcées. |
features/verse_grip_pairing/force_attached | bool | — | Définir de manière permanente l'état de connexion sur true, en contournant le capteur à effet Hall (solution de contournement en cas de défaillance matérielle). |
session/serialization/…
Format de sortie « Transform » — affecte les charges JSON WebSocket et HTTP. Ces clés ont été déplacées de la section 3.5.1 vers serialization/* Migration vers session/serialization/*, afin de refléter son champ d'application par session. L'ancien chemin d'accès continuera d'être résolu via l'alias obsolète.
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | Inclure dans la sortie sérialisée les champs « transform » dont la valeur est égale à la valeur par défaut (par exemple position: {0,0,0},rotation: {w:1,…}). Cela s'avère très utile lorsque le client exige que chaque champ soit explicitement présent. Valeur par défaut :false。 |
session/serialization/force_complete_transforms | bool | — | Chaque sortie de transformation doit toujours contenir position,rotation et scale, y compris les appareils ne fournissant que des données de posture (Verse Grip, Wireless Verse Grip), qui, à l'origine, ne transmettaient que rotation。Ce paramètre est déjà pris en compte session/serialization/explicit_fields Fonctionnalité. Valeur par défaut :false。 |
serialization/explicit_fields (obsolète) | bool | — | Veuillez utiliser à la place session/serialization/explicit_fields. Les opérations de lecture et d'écriture sont transmises de manière transparente à la clé de spécification. |
serialization/force_complete_transforms (obsolète) | bool | — | Veuillez utiliser à la place session/serialization/force_complete_transforms. Les opérations de lecture et d'écriture sont transmises de manière transparente à la clé de spécification. |
session/…
Planificateur de sessions.
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
session/min_simulation_rate_hz | int | Plage de valeurs : 20–500 | Fréquence d'échantillonnage minimale acceptable de l'appareil (Hz) avant le déclenchement d'une alerte. |
rate/…
Contrôle du débit de service. Introduit à partir de la version 3.5.1 — les quatre éléments suivants rate/websocket/* La touche se trouvait auparavant à l'emplacement session/commands/* En outre, l'ancien chemin d'accès continuera d'être résolu via l'alias obsolète.
| Touche | Type | Contrainte | Explication |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | Fenêtre de conservation d'ordre zéro (ZOH) : supprime les messages de détection reçus dans cette fenêtre (en ms). |
rate/websocket/drop_warning_threshold | int | — | Nombre de commandes ignorées dans la fenêtre avant le déclenchement de l'alerte. |
rate/websocket/drop_warning_window_ms | int | — | Taille de la fenêtre glissante (en ms) utilisée pour compter le nombre de commandes ignorées. |
rate/websocket/tick_on_empty_batch | bool | Avancé | Même si l'ensemble du lot WebSocket est rejeté, la tâche est tout de même planifiée une fois. main_loop coche。 |
session/commands/zoh_window_ms (obsolète) | int | — | Veuillez utiliser à la place rate/websocket/zoh_window_ms. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
session/commands/drop_warning_threshold (obsolète) | int | — | Veuillez utiliser à la place rate/websocket/drop_warning_threshold. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
session/commands/drop_warning_window_ms (obsolète) | int | — | Veuillez utiliser à la place rate/websocket/drop_warning_window_ms. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
session/commands/tick_on_empty_batch (obsolète) | bool | — | Veuillez utiliser à la place rate/websocket/tick_on_empty_batch. Les opérations de lecture et d'écriture sont transmises de manière transparente. |
Paramètres réservés à un usage interne
3.5.1 comporte plusieurs familles de paramètres, dont hidden Publication d'état, à usage interne uniquement ——rate/dispatch/*(limite maximale du débit de distribution de l'AIMD et seuil de contre-pression),session/freeform/*(reconnaissance des empreintes comportementales), ainsi que session/serialization/preview/*(Expériences de sérialisation pré-publiées, telles que la sortie des quaternions d'Euler et le routage Wireless VerseGrip). Ces paramètres sont accessibles via misc/hidden_settings Ces fonctionnalités sont accessibles à des fins de débogage, mais sachez qu'elles pourraient être converties en paramètres officiels, renommées ou supprimées dans les prochaines versions mineures. Veillez donc à ne pas baser le comportement de votre client sur celles-ci.