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 chemin | Signification |
|---|---|
inverse3/0 | Inverse3 s principales selon l'index (base 0) |
inverse3/A14 | Inverse3 dont l'identifiant de l'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 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 :
GETrejette les sélecteurs ambigus ou contenant des caractères génériques (renvoie400).POSTetDELETEacceptent 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.
| Expression | Signification |
|---|---|
| (omis) | Toutes les sessions (DELETE uniquement) |
#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 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éthode | Chemin | Description |
|---|---|---|
| OBTENIR | /sessions | Afficher toutes les sessions v3.1 actives |
| OBTENIR | /sessions/{session_id} | Obtenir une session |
| OBTENIR | /sessions/{session_id}/profile | Récupérer le nom du profil de session |
| PUBLICATION | /sessions/{session_id}/profile | Définir le profil de session |
| SUPPRIMER | /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 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éthode | Chemin | 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" (par défaut) |
Mise à l'échelle du couple (Inverse3 s uniquement)
| Méthode | Chemin | 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 de la gravité (Inverse3 s uniquement)
| Méthode | Chemin | 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, à portée de session)
| Méthode | Chemin | 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" } |
Monter (tous les appareils, à portée de session)
| Méthode | Chemin | 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 `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éthode | Chemin | 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.
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éthode | Chemin | 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 réinitialisations |
Porte de force
| Méthode | Chemin | 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 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 |
|---|---|---|---|
| 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éthode | Itinéraire | Description |
|---|---|---|
| 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 actuellemetadata: 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 :
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
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.