HTTP
Par défaut, le service HTTP est exécuté sous http://localhost:10001 lancé.
Le port peut être modifié dans la configuration du service.
Aperçu
Cette section répertorie les routes HTTP fournies par le service.
Tous les itinéraires suivants partent de l'URL de base par défaut : http://localhost:10001.
Structure standard de la réponse
Tous les points de terminaison renvoient l'une des deux structures de réponse suivantes :
Réponse sans données (utilisée par les terminaux qui se contentent d'effectuer des modifications) :
{ "ok": true }
{ "ok": false, "error": "reason string" }
Réponse contenant des données (utilisée par les requêtes GET ainsi que POST/DELETE pour les points de terminaison de configuration qui renvoient la valeur reçue) :
{ "ok": true, "data": { "..." : "..." } }
{ "ok": false, "error": "reason string" }
Syntaxe du sélecteur de périphérique
Les routes au niveau des appareils suivent le modèle /{device_type}/{id_or_index}/.... Les segments de chemin {device_type} et {id_or_index} identifient les appareils cibles.
| Exemple de segment de chemin | Signification |
|---|---|
inverse3/0 | Premier élément de la liste « Inverse3 » selon l'index (à partir de 0) |
inverse3/A14 | Inverse3 avec l'identifiant de l'appareil A14 |
inverse3/* | Tous les appareils « Inverse3 » (espace réservé) |
verse_grip/0 | Premier vers, recherche par index |
wireless_verse_grip/* | Toutes les poignées Wireless Verse |
*inverse/* | Tous les appareils de la gamme Inverse (Inverse3, Inverse3x, Minverse) |
*verse_grip/* | Tous les appareils de la gamme Verse Grip (Verse Grip, Wireless VG) |
Règles relatives aux caractères de remplacement :
GETrefuse les sélecteurs ambigus ou contenant des caractères génériques (renvoie400).POSTetDELETEAccepter les caractères génériques : l'opération s'applique à tous les appareils correspondants.
Sélecteur de session
Les paramètres liés à la session (basis, mount, preset, transform, filters) nécessitent le paramètre de requête ?session=<expr>, afin d'identifier la session.
| Impression | Signification |
|---|---|
| (omission) | Toutes les sessions (DELETE uniquement) |
#123 ou 123 | Séance portant le numéro d'identification 123 |
:-1 | Dernière séance selon l'indice |
:0 | Première séance selon l'indice |
Exemple : GET /inverse3/0/config/basis?session=:0
Version
Méthode : GET
URL : http://localhost:10001/version
Exemple de réponse :
{
"build_time": "2024-08-07T16:01:53Z",
"git_branch": "main",
"git_describe": "3.5.0-2-gce34c39e",
"git_hash": "ce34c39e",
"git_tag": "3.5.0",
"project_name": "haply-inverse-service",
"project_version": "3.5.0"
}
Statut d'expert
Méthode : GET
URL : http://localhost:10001/expert/status
Renvoie des informations détaillées sur l'état, notamment concernant la détection, les appareils, les sessions et les paramètres globaux.
Appareils
Méthode : GET
URL : http://localhost:10001/devices
Renvoie la liste actuelle des périphériques, y compris config, state et status.
Vous pouvez, si vous le souhaitez, ?session=<expr> transmis afin de filtrer l'instantané selon la perspective d'une session donnée (la base, le montage et les transformations de cette session sont alors appliqués aux valeurs renvoyées).
Exemple de réponse :
{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}
Séances
| Méthode | Chemin d'accès | Description |
|---|---|---|
| OBTENIR | /sessions | Répertorie toutes les sessions v3.1 actives |
| OBTENIR | /sessions/{session_id} | Affiche une seule session |
| OBTENIR | /sessions/{session_id}/profile | Récupère le nom du profil de session |
| PUBLICATION | /sessions/{session_id}/profile | Définit le profil de session |
| SUPPRIMER | /sessions/{session_id}/profile | Activer le profil "default" retour |
Corps de POST /sessions/{session_id}/profile:
{
"name": "my_profile"
}
Ports
Méthode : POST
URL : http://localhost:10001/ports/{port}/reset
Libère un port série bloqué. Donne { "ok": true } Retour.
Configuration de l'appareil
Tous les points de terminaison de configuration suivent le modèle /{device_type}/{id_or_index}/config/{setting}.
Les points de terminaison liés à une session (basis, mount, preset) nécessitent en outre le paramètre de requête ?session=<expr>.
Latéralité (uniquement Inverse3)
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/handedness | -- | "left" ou "right" |
| PUBLICATION | /{device_type}/{id}/config/handedness | "left" ou "right" | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/handedness | -- | "right" (Standard) |
Mise à l'échelle du couple ( Inverse3 uniquement)
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/torque_scaling | -- | { "enabled": bool } |
| PUBLICATION | /{device_type}/{id}/config/torque_scaling | { "enabled": bool } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/torque_scaling | -- | { "enabled": false } |
Compensation gravitationnelle (uniquement Inverse3)
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/gravity_compensation | -- | { "enabled": bool, "scaling_factor": float } |
| PUBLICATION | /{device_type}/{id}/config/gravity_compensation | { "enabled": bool, "scaling_factor": float } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/gravity_compensation | -- | { "enabled": true, "scaling_factor": 1.0 } |
Base (tous les appareils, par séance)
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/basis?session= | -- | { "permutation": "XYZ" } |
| PUBLICATION | /{device_type}/{id}/config/basis?session= | { "permutation": "ZXY" } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/basis?session= | -- | { "permutation": "XYZ" } |
Mont (tous les appareils, par session)
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/mount?session= | -- | { "transform": {...} } |
| PUBLICATION | /{device_type}/{id}/config/mount?session= | { "transform": {...} } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/mount?session= | -- | Transformation identitaire |
Structure de la transformation (utilisée par les fonctions `mount` et `state/transform`) :
{
"transform": {
"position": { "x": 0, "y": 0, "z": 0 },
"rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
"scale": { "x": 1, "y": 1, "z": 1 }
}
}
Paramètre par défaut (tous les appareils, par session)
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/preset?session= | -- | { "preset": "arm_front_centered" } |
| PUBLICATION | /{device_type}/{id}/config/preset?session= | { "preset": "arm_front_centered" } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/preset?session= | -- | { "preset": "device_defaults" } |
Valeurs disponibles : device_defaults, arm_front, arm_front_centered, led_front, led_front_centered, custom.
Filtre par appareil ( Inverse3 uniquement, par session)
Utilisation des points de fin de filtrage /{device_type}/{id}/config/filters/{filter}?session=<expr>.
Amortissement
Contrôle à la fois l'amortissement uniforme et l'amortissement directionnel. Le corps POST doit comporter au moins un champ.
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/filters/damping?session= | -- | { "scalar": float, "vector": { "x": f, "y": f, "z": f } } |
| PUBLICATION | /{device_type}/{id}/config/filters/damping?session= | { "scalar": float } ou { "vector": {...} } ou les deux | valeurs renvoyées |
| SUPPRIMER | /{device_type}/{id}/config/filters/damping?session= | -- | les deux ont été remis à zéro |
Force Gate
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/config/filters/force_gate?session= | -- | { "gain": float } |
| PUBLICATION | /{device_type}/{id}/config/filters/force_gate?session= | { "gain": float } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/config/filters/force_gate?session= | -- | Gain issu des réglages par défaut |
État de l'appareil
Transformer (tous les appareils, par session)
Transformation de l'espace de travail (du domaine des appareils au domaine des applications).
| Méthode | Chemin d'accès | Corps | Réponse |
|---|---|---|---|
| OBTENIR | /{device_type}/{id}/state/transform?session= | -- | { "transform": {...} } |
| PUBLICATION | /{device_type}/{id}/state/transform?session= | { "transform": {...} } | valeur renvoyée |
| SUPPRIMER | /{device_type}/{id}/state/transform?session= | -- | Transformation identitaire |
Enregistrer la configuration
Ne fonctionne qu'avec les appareils Inverse3. Avertissement : évitez d'enregistrer la configuration trop souvent, car le nombre d'opérations d'enregistrement est limité par appareil (environ 10 000 écritures EEPROM).
Méthode : POST
URL : http://localhost:10001/save_configuration
Exemple de corps de texte :
{
"device_id": "049D"
}
Exemple de réponse :
{
"ok": true
}
Paramètres
Les points de terminaison pour les paramètres sont générés automatiquement pour :
- Liste de tous les paramètres (y compris les métadonnées)
- Lecture d'une valeur de paramétrage unique
- Application des paramètres (un par un ou par lots)
- Réinitialisation d'une clé à sa valeur par défaut
Vous trouverez ici toutes les références aux codes de paramétrage
Itinéraires
| Méthode | Itinéraire | Description |
|---|---|---|
| OBTENIR | /settings/ | Récupère toutes les clés de configuration, les valeurs et les métadonnées. |
| PUBLICATION | /settings/ | Applique plusieurs paramètres à la fois en mode batch. |
| OBTENIR | /settings/{key} | Récupère la valeur actuelle d'une clé de paramétrage donnée. |
| PUBLICATION | /settings/{key} | Applique une nouvelle valeur à une clé donnée. |
| SUPPRIMER | /settings/{key} | Rétablit la valeur par défaut d'une clé. |
Structure de la réponse
OBTENIR /settings/ (tous les paramètres)
Renvoie un objet indexé selon la clé de paramètre. Chaque entrée contient :
value: la valeur actuellemetadata: Type + Restrictions + Statut de blocage
Exemples d'entrées :
{
"devices/detection/timeout": {
"metadata": {
"constraint": {
"range": {
"max": 15,
"min": 1,
"step": 0
}
},
"locked": false,
"type_hint": "INT"
},
"value": 5
}
}
OBTENIR /settings/{key} (réglage individuel)
Renvoie uniquement la valeur (sans métadonnées) correspondant à la clé demandée.
Appliquer les paramètres
PUBLICATION /settings/ (Traitement par lots)
Applique plusieurs clés à la fois en mode batch.
Format de corps recommandé : un objet JSON associant des clés à des valeurs.
{
"devices/detection/timeout": 5,
"devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}
PUBLICATION /settings/{key} (utilisation ponctuelle)
Applique une nouvelle valeur à une clé unique.
Format de corps recommandé : soit une valeur JSON brute, soit une valeur encapsulée dans un objet (cette dernière option étant préférable pour des raisons de clarté).
{
"value": 5
}
Réinitialisation des paramètres
SUPPRIMER /settings/{key}
Rétablit la valeur par défaut de la clé.
Cela correspond à « rétablir les valeurs par défaut ».
Remarques concernant les types
Le service gère type_hint automatiquement. GENERIC est utilisé comme solution de repli pour les types complexes.
Remarques prises en charge :
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
Terminaux hérités obsolètes
Quelques-uns POST- Les points de terminaison sont encore acceptés, mais déclenchent un avertissement de dépréciation
et seront remplacés par 4.0 supprimé. Voir le Guide de migration vers la version 3.5
pour consulter le tableau complet de correspondance entre les itinéraires obsolètes et les itinéraires de remplacement.