Aller au contenu principal

HTTP

Par défaut, le service HTTP démarre sur : http://localhost:10001.

Le port peut être modifié dans la configuration du service.

Vue d'ensemble​

Cette section présente les routes HTTP mises à disposition par le service.

Toutes les routes ci-dessous utilisent l'URL de base par défaut : http://localhost:10001.

Enveloppe de réponse standard​

Tous les points de terminaison renvoient l'une des deux enveloppes suivantes :

Réponse sans données (utilisée uniquement par les points de terminaison de modification) :

{ "ok": true }
{ "ok": false, "error": "reason string" }

Réponse de données (utilisée par GET, ainsi que par POST/DELETE sur les points de terminaison de configuration qui renvoient la valeur appliquée) :

{ "ok": true, "data": { "..." : "..." } }
{ "ok": false, "error": "reason string" }

Syntaxe du sélecteur d'appareil​

Les routes au niveau de l'appareil utilisent le motif /{device_type}/{id_or_index}/.... Les segments de chemin {device_type} et {id_or_index} identifient le ou les appareils visés.

Exemple de segment de cheminSignification
inverse3/0Inverse3 s principales selon l'index (base 0)
inverse3/A14Inverse3 dont l'identifiant de l'appareil est A14
inverse3/*Tous les appareils Inverse3 (caractère générique)
verse_grip/0Premier Verse Grip selon l'index
wireless_verse_grip/*Tous les Wireless Verse Grip
*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 génériques :

  • GET rejette les sélecteurs ambigus ou contenant des caractères génériques (renvoie 400).
  • POST et DELETE acceptent les caractères génériques : l'opération s'applique à tous les appareils concernés.

Sélecteur de session​

Les points de terminaison de session (basis, mount, preset, transform, filters) nécessitent un paramètre de requête ?session=<expr> pour identifier la session.

ExpressionSignification
(omis)Toutes les sessions (DELETE uniquement)
#123 ou 123Session dont l'identifiant numérique est 123
:-1Dernière session selon l'index
:0Première session selon l'index

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 la détection, les appareils, les sessions et les paramètres généraux.


Appareils​

Méthode : GET
URL : http://localhost:10001/devices

Renvoie la liste actuelle des appareils, comprenant notamment config, state et status.

Vous pouvez également transmettre ?session=<expr> pour filtrer l'instantané en fonction de la perspective d'une session donnée (applique la base, le montage et les transformations de cette session aux valeurs renvoyées).

Exemple de réponse :

{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}

Séances​

MéthodeCheminDescription
OBTENIR/sessionsAfficher toutes les sessions v3.1 actives
OBTENIR/sessions/{session_id}Obtenir une session
OBTENIR/sessions/{session_id}/profileRécupérer le nom du profil de session
PUBLICATION/sessions/{session_id}/profileDéfinir le profil de session
SUPPRIMER/sessions/{session_id}/profileRéinitialiser le profil à "default"

Corps de la requête POST /sessions/{session_id}/profile :

{
"name": "my_profile"
}

Ports​

Méthode : POST
URL : http://localhost:10001/ports/{port}/reset

Réinitialise un port série bloqué. Retourne { "ok": true }.


Configuration de l'appareil​

Tous les points de terminaison de configuration utilisent le motif /{device_type}/{id_or_index}/config/{setting}.

Les points de terminaison accessibles au niveau de la session (basis, mount, preset) nécessitent en outre un paramètre de requête ?session=<expr>.

Latéralité (Inverse3 ement)​

MéthodeCheminCorpsRé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" (par défaut)

Mise à l'échelle du couple (Inverse3 s uniquement)​

MéthodeCheminCorpsRé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 de la gravité (Inverse3 s uniquement)​

MéthodeCheminCorpsRé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, à portée de session)​

MéthodeCheminCorpsRé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" }

Monter (tous les appareils, à portée de session)​

MéthodeCheminCorpsRé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 `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 }
}
}

Préréglage (tous les appareils, valable uniquement pour la session)​

MéthodeCheminCorpsRé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.


Filtres de l'appareil (Inverse3 s uniquement, limités à la session)​

Les points de terminaison des filtres utilisent /{device_type}/{id}/config/filters/{filter}?session=<expr>.

Amortissement​

Contrôle à la fois l'amortissement uniforme et l'amortissement directionnel. Au moins un champ doit être présent dans le corps de la requête POST.

MéthodeCheminCorpsRé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 deuxvaleurs renvoyées
SUPPRIMER/{device_type}/{id}/config/filters/damping?session=--les deux réinitialisations

Porte de force​

MéthodeCheminCorpsRé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 par défaut défini dans les paramètres

État de l'appareil​

Transformation (tous les appareils, limitée à la session)​

Transformation de l'espace de travail (de l'espace de l'appareil vers l'espace de l'application).

MéthodeCheminCorpsRé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​

Fonctionne uniquement avec les appareils suivants : Inverse3. Attention : évitez d'enregistrer la configuration trop souvent, car le nombre d'enregistrements possibles sur un même appareil est limité (environ 10 000 écritures EEPROM).

Méthode : POST
URL : http://localhost:10001/save_configuration

Exemple de corps :

{
"device_id": "049D"
}

Exemple de réponse :

{
"ok": true
}

Paramètres​

Les points de terminaison des paramètres sont générés automatiquement pour :

  • Liste de tous les paramètres (métadonnées comprises)
  • Lecture de la valeur d'un paramètre unique
  • Application des paramètres (individuellement ou par lots)
  • Réinitialisation d'une clé à sa valeur par défaut

Vous trouverez ici les références de toutes les clés de paramètres

Itinéraires​

MéthodeItinéraireDescription
OBTENIR/settings/Récupérer toutes les clés de paramètres, leurs valeurs et leurs métadonnées.
PUBLICATION/settings/Appliquer plusieurs paramètres à la fois (par lots).
OBTENIR/settings/{key}Récupérer la valeur actuelle d'une clé de paramètre donnée.
PUBLICATION/settings/{key}Attribuer une nouvelle valeur à une clé donnée.
SUPPRIMER/settings/{key}Réinitialiser une clé à sa valeur par défaut.

Forme de la réponse​

OBTENIR /settings/ (tous les paramètres)​

Renvoie un objet dont les clés correspondent aux clés des paramètres. Chaque entrée contient :

  • value : la valeur actuelle
  • metadata : type, contraintes et état de verrouillage

Exemples de saisies :

{
"devices/detection/timeout": {
"metadata": {
"constraint": {
"range": {
"max": 15,
"min": 1,
"step": 0
}
},
"locked": false,
"type_hint": "INT"
},
"value": 5
}
}

OBTENIR /settings/{key} (paramètre unique)​

Renvoie uniquement la valeur (sans métadonnées) de la clé demandée.

Application des paramètres​

PUBLICATION /settings/ (application par lot)​

Appliquez plusieurs clés à la fois.

Format de corps suggéré : un objet JSON associant les clés à leurs valeurs.

{
"devices/detection/timeout": 5,
"devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}

PUBLICATION /settings/{key} (application unique)​

Applique une nouvelle valeur à une seule clé.

Format de corps suggéré : soit une valeur JSON brute, soit une valeur encapsulée (de préférence, pour plus de clarté).

{
"value": 5
}

Réinitialisation des paramètres​

SUPPRIMER /settings/{key}​

Réinitialise la clé à sa valeur par défaut.

Cela revient à « rétablir les paramètres par défaut ».

Indications de type​

Le service effectue automatiquement la déduction type_hint. GENERIC est utilisé comme solution de secours pour les types complexes.

Indications prises en charge :

  • BOOL
  • INT
  • FLOAT
  • STRING
  • VEC2
  • VEC3
  • VEC4
  • TRANSFORM
  • ARR_INT
  • ARR_FLOAT
  • ARR_STRING
  • GENERIC

Points de terminaison hérités obsolètes​

Plusieurs points d'arrivée POST sont toujours acceptés, mais génèrent un avertissement de dépréciation et seront supprimés dans la version 4.0. Consultez le Guide de migration 3.5 pour consulter le tableau complet de correspondance entre les itinéraires obsolètes et les itinéraires de remplacement.