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 documente les routes HTTP exposées par le service.

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

Enveloppe de réponse standard

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

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

{ "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 ciblés.

Exemple de segment de chemin	Signification
`inverse3/0`	Premier Inverse3 selon l'index (base 0)
`inverse3/A14`	Inverse3 dont l'identifiant d'appareil est `A14`
`inverse3/*`	Tous les appareils Inverse3 (caractère générique)
`verse_grip/0`	Premier Verse Grip selon l'index
`wireless_verse_grip/*`	Tous les Wireless Verse Grip
`inverse/`	Tous les appareils de la famille Inverse (Inverse3, Inverse3x, Minverse)
`verse_grip/`	Tous les appareils de la famille Verse Grip (Verse Grip, Wireless VG)

Règles relatives aux caractères génériques :

GET rejette les sélecteurs ambigus ou à caractères génériques (retourne 400).
POST et DELETE acceptent les caractères génériques : l'opération est appliquée à tous les appareils correspondants.

Sélecteur de session

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

Expression	Signification
(omis)	Toutes les sessions (DELETE seulement)
`#123` ou `123`	Session dont l'identifiant numérique est 123
`:-1`	Dernière session selon l'index
`:0`	Premiè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 expert

Méthode : GET
URL : http://localhost:10001/expert/status

Retourne des informations détaillées sur le statut, incluant la détection, les appareils, les sessions et les paramètres globaux.

Appareils

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

Retourne l'inventaire actuel des appareils, incluant config, state et status.

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

Exemple de réponse :

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

Sessions

Méthode	Chemin	Description
GET	`/sessions`	Liste toutes les sessions v3.1 actives
GET	`/sessions/{session_id}`	Obtenir une session
GET	`/sessions/{session_id}/profile`	Obtenir le nom du profil de session
POST	`/sessions/{session_id}/profile`	Définir le profil de session
DELETE	`/sessions/{session_id}/profile`	Ré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 à portée de session (basis, mount, preset) exigent en plus un paramètre de requête ?session=<expr>.

Latéralité (Inverse3 seulement)

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/handedness`	--	`"left"` ou `"right"`
POST	`/{device_type}/{id}/config/handedness`	`"left"` ou `"right"`	valeur renvoyée
DELETE	`/{device_type}/{id}/config/handedness`	--	`"right"` (par défaut)

Mise à l'échelle du couple (Inverse3 seulement)

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/torque_scaling`	--	`{ "enabled": bool }`
POST	`/{device_type}/{id}/config/torque_scaling`	`{ "enabled": bool }`	valeur renvoyée
DELETE	`/{device_type}/{id}/config/torque_scaling`	--	`{ "enabled": false }`

Compensation de la gravité (Inverse3 seulement)

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/gravity_compensation`	--	`{ "enabled": bool, "scaling_factor": float }`
POST	`/{device_type}/{id}/config/gravity_compensation`	`{ "enabled": bool, "scaling_factor": float }`	valeur renvoyée
DELETE	`/{device_type}/{id}/config/gravity_compensation`	--	`{ "enabled": true, "scaling_factor": 1.0 }`

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

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/basis?session=`	--	`{ "permutation": "XYZ" }`
POST	`/{device_type}/{id}/config/basis?session=`	`{ "permutation": "ZXY" }`	valeur renvoyée
DELETE	`/{device_type}/{id}/config/basis?session=`	--	`{ "permutation": "XYZ" }`

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

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/mount?session=`	--	`{ "transform": {...} }`
POST	`/{device_type}/{id}/config/mount?session=`	`{ "transform": {...} }`	valeur renvoyée
DELETE	`/{device_type}/{id}/config/mount?session=`	--	transformation identité

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, limité à la session)

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/preset?session=`	--	`{ "preset": "arm_front_centered" }`
POST	`/{device_type}/{id}/config/preset?session=`	`{ "preset": "arm_front_centered" }`	valeur renvoyée
DELETE	`/{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 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éthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/filters/damping?session=`	--	`{ "scalar": float, "vector": { "x": f, "y": f, "z": f } }`
POST	`/{device_type}/{id}/config/filters/damping?session=`	`{ "scalar": float }` ou `{ "vector": {...} }` ou les deux	valeurs renvoyées
DELETE	`/{device_type}/{id}/config/filters/damping?session=`	--	les deux remises à zéro

Porte de force

Méthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/config/filters/force_gate?session=`	--	`{ "gain": float }`
POST	`/{device_type}/{id}/config/filters/force_gate?session=`	`{ "gain": float }`	valeur renvoyée
DELETE	`/{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éthode	Chemin	Corps	Réponse
GET	`/{device_type}/{id}/state/transform?session=`	--	`{ "transform": {...} }`
POST	`/{device_type}/{id}/state/transform?session=`	`{ "transform": {...} }`	valeur renvoyée
DELETE	`/{device_type}/{id}/state/transform?session=`	--	transformation identité

Enregistrer la configuration

Fonctionne uniquement avec les appareils Inverse3. Attention : évitez d'enregistrer la configuration trop souvent, car le nombre d'enregistrements pouvant être effectués 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 incluses)
Lecture de la valeur d'un paramètre unique
Application de paramètres (individuellement ou par lot)
Réinitialisation d'une clé à sa valeur par défaut

Les références de toutes les clés de paramètres se trouvent ici

Routes

Méthode	Route	Description
GET	`/settings/`	Obtenir toutes les clés de paramètres, leurs valeurs et leurs métadonnées.
POST	`/settings/`	Appliquer plusieurs paramètres à la fois (par lot).
GET	`/settings/{key}`	Obtenir la valeur actuelle d'une clé de paramètre donnée.
POST	`/settings/{key}`	Appliquer une nouvelle valeur à une clé donnée.
DELETE	`/settings/{key}`	Réinitialiser une clé à sa valeur par défaut.

Forme de la réponse

GET `/settings/` (tous les paramètres)

Retourne un objet dont les clés sont les clés de paramètres. Chaque entrée contient :

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

Exemples d'entrées :

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

GET `/settings/{key}` (paramètre unique)

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

Application des paramètres

POST `/settings/` (application par lot)

Applique 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"]
}

POST `/settings/{key}` (application unique)

Applique une nouvelle valeur à une seule clé.

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

{
  "value": 5
}

Réinitialisation des paramètres

DELETE `/settings/{key}`

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

Cela équivaut à « réinitialiser à la valeur par défaut ».

Indications de type

Le service déduit automatiquement type_hint. GENERIC est utilisé comme solution de repli 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 dépréciés

Plusieurs points de terminaison 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 le tableau complet de correspondance entre les chemins dépréciés et les routes de remplacement.

Vue d'ensemble​

Enveloppe de réponse standard​

Syntaxe du sélecteur d'appareil​

Sélecteur de session​

Version​

Statut expert​

Appareils​

Sessions​

Ports​

Configuration de l'appareil​

Latéralité (Inverse3 seulement)​

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

Compensation de la gravité (Inverse3 seulement)​

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

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

Préréglage (tous les appareils, limité à la session)​

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

Amortissement​

Porte de force​

État de l'appareil​

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

Enregistrer la configuration​

Paramètres​

Routes​

Forme de la réponse​

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

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

Application des paramètres​

POST /settings/ (application par lot)​

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

Réinitialisation des paramètres​

DELETE /settings/{key}​

Indications de type​

Points de terminaison hérités dépréciés​

Vue d'ensemble

Enveloppe de réponse standard

Syntaxe du sélecteur d'appareil

Sélecteur de session

Version

Statut expert

Appareils

Sessions

Ports

Configuration de l'appareil

Latéralité (Inverse3 seulement)

Mise à l'échelle du couple (Inverse3 seulement)

Compensation de la gravité (Inverse3 seulement)

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

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

Préréglage (tous les appareils, limité à la session)

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

Amortissement

Porte de force

État de l'appareil

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

Enregistrer la configuration

Paramètres

Routes

Forme de la réponse

GET `/settings/` (tous les paramètres)

GET `/settings/{key}` (paramètre unique)

Application des paramètres

POST `/settings/` (application par lot)

POST `/settings/{key}` (application unique)

Réinitialisation des paramètres

DELETE `/settings/{key}`

Indications de type

Points de terminaison hérités dépréciés