HTTP
Standardmäßig wird der HTTP-Dienst unter http://localhost:10001 gestartet.
Der Port kann in der Konfiguration des Dienstes geändert werden.
Übersicht
Dieser Abschnitt dokumentiert die vom Dienst bereitgestellten HTTP-Routen.
Alle folgenden Routen gehen von der Standard-Basis-URL aus: http://localhost:10001.
Standardstruktur der Antwort
Alle Endpunkte geben eine von zwei Antwortstrukturen zurück:
Antwort ohne Daten (wird von Endpunkten verwendet, die nur Änderungen vornehmen):
{ "ok": true }
{ "ok": false, "error": "reason string" }
Antwort mit Daten (wird von GET sowie von POST/DELETE bei Konfigurationsendpunkten verwendet, die den übernommenen Wert zurückgeben):
{ "ok": true, "data": { "..." : "..." } }
{ "ok": false, "error": "reason string" }
Syntax des Geräteselektors
Routen auf Geräteebene folgen dem Muster /{device_type}/{id_or_index}/.... Die Pfadsegmente {device_type} und {id_or_index} identifizieren die Zielgeräte.
| Beispiel-Pfadsegment | Bedeutung |
|---|---|
inverse3/0 | Erstes „ Inverse3 “-Gerät nach Index (0-basiert) |
inverse3/A14 | Inverse3 mit Geräte-ID A14 |
inverse3/* | Alle „ Inverse3 “-Geräte (Platzhalter) |
verse_grip/0 | Erster Vers – Griff nach Index |
wireless_verse_grip/* | Alle Wireless Verse Griffe |
*inverse/* | Alle Geräte der Inverse-Familie (Inverse3, Inverse3x, Minverse) |
*verse_grip/* | Alle Geräte der Verse-Grip-Familie (Verse Grip, Wireless VG) |
Platzhalterregeln:
GETlehnt mehrdeutige bzw. Platzhalter-Selektoren ab (liefert400).POSTundDELETEPlatzhalter akzeptieren – die Aktion wird auf alle passenden Geräte angewendet.
Sitzungsauswahl
Sitzungsbezogene Endpunkte (basis, mount, preset, transform, filters) erfordern den Query-Parameter ?session=<expr>, um die Sitzung zu identifizieren.
| Ausdruck | Bedeutung |
|---|---|
| (ausgelassen) | Alle Sitzungen (nur DELETE) |
#123 oder 123 | Sitzung mit der Nummer 123 |
:-1 | Letzte Sitzung nach Index |
:0 | Erste Sitzung nach Index |
Beispiel: GET /inverse3/0/config/basis?session=:0
Version
Methode: GET
URL: http://localhost:10001/version
Beispielantwort:
{
"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"
}
Expertenstatus
Methode: GET
URL: http://localhost:10001/expert/status
Liefert detaillierte Statusinformationen zurück, darunter Erkennung, Geräte, Sitzungen und globale Einstellungen.
Geräte
Methode: GET
URL: http://localhost:10001/devices
Gibt die aktuelle Geräteübersicht zurück, einschließlich config, state und status.
Sie können optional ?session=<expr> übergeben, um den Snapshot auf die Perspektive einer bestimmten Sitzung zu filtern (dabei werden die Basis, der Mount und die Transformationen dieser Sitzung auf die zurückgegebenen Werte angewendet).
Beispielantwort:
{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}
Sitzungen
| Methode | Pfad | Beschreibung |
|---|---|---|
| HOLEN | /sessions | Listet alle aktiven v3.1-Sitzungen auf |
| HOLEN | /sessions/{session_id} | Ruft eine einzelne Sitzung ab |
| HOLEN | /sessions/{session_id}/profile | Ruft den Namen des Sitzungsprofils ab |
| BEITRAG | /sessions/{session_id}/profile | Legt das Sitzungsprofil fest |
| LÖSCHEN | /sessions/{session_id}/profile | Stellt das Profil ein auf "default" zurück |
Text von POST /sessions/{session_id}/profile:
{
"name": "my_profile"
}
Anschlüsse
Methode: POST
URL: http://localhost:10001/ports/{port}/reset
Gibt einen blockierten seriellen Port frei. Gibt { "ok": true } zurück.
Gerätekonfiguration
Alle Konfigurationsendpunkte folgen dem Muster /{device_type}/{id_or_index}/config/{setting}.
Sitzungsbezogene Endpunkte (basis, mount, preset) erfordern zusätzlich den Query-Parameter ?session=<expr>.
Händigkeit (nur Inverse3)
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/handedness | -- | "left" oder "right" |
| BEITRAG | /{device_type}/{id}/config/handedness | "left" oder "right" | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/handedness | -- | "right" (Standard) |
Drehmomentskalierung (nur Inverse3)
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/torque_scaling | -- | { "enabled": bool } |
| BEITRAG | /{device_type}/{id}/config/torque_scaling | { "enabled": bool } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/torque_scaling | -- | { "enabled": false } |
Gravitationskompensation (nur Inverse3)
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/gravity_compensation | -- | { "enabled": bool, "scaling_factor": float } |
| BEITRAG | /{device_type}/{id}/config/gravity_compensation | { "enabled": bool, "scaling_factor": float } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/gravity_compensation | -- | { "enabled": true, "scaling_factor": 1.0 } |
Grundlage (alle Geräte, sitzungsbezogen)
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/basis?session= | -- | { "permutation": "XYZ" } |
| BEITRAG | /{device_type}/{id}/config/basis?session= | { "permutation": "ZXY" } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/basis?session= | -- | { "permutation": "XYZ" } |
Mount (alle Geräte, sitzungsbezogen)
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/mount?session= | -- | { "transform": {...} } |
| BEITRAG | /{device_type}/{id}/config/mount?session= | { "transform": {...} } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/mount?session= | -- | Identitätswandel |
Struktur der Transformation (verwendet von „mount“ und „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 }
}
}
Voreinstellung (alle Geräte, sitzungsbezogen)
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/preset?session= | -- | { "preset": "arm_front_centered" } |
| BEITRAG | /{device_type}/{id}/config/preset?session= | { "preset": "arm_front_centered" } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/preset?session= | -- | { "preset": "device_defaults" } |
Verfügbare Werte: device_defaults, arm_front, arm_front_centered, led_front, led_front_centered, custom.
Gerätefilter (nur Inverse3, sitzungsbezogen)
Filter-Endpunkte verwenden /{device_type}/{id}/config/filters/{filter}?session=<expr>.
Dämpfung
Steuert sowohl die gleichmäßige als auch die richtungsabhängige Dämpfung. Im POST-Body muss mindestens ein Feld vorhanden sein.
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/filters/damping?session= | -- | { "scalar": float, "vector": { "x": f, "y": f, "z": f } } |
| BEITRAG | /{device_type}/{id}/config/filters/damping?session= | { "scalar": float } oder { "vector": {...} } oder beides | zurückgegebene Werte |
| LÖSCHEN | /{device_type}/{id}/config/filters/damping?session= | -- | beide auf Null zurückgesetzt |
Krafttor
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/config/filters/force_gate?session= | -- | { "gain": float } |
| BEITRAG | /{device_type}/{id}/config/filters/force_gate?session= | { "gain": float } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/config/filters/force_gate?session= | -- | Verstärkung anhand der Standardeinstellungen |
Gerätezustand
Transformieren (alle Geräte, sitzungsbezogen)
Arbeitsbereichstransformation (vom Gerätebereich zum Anwendungsbereich).
| Methode | Pfad | Hauptteil | Antwort |
|---|---|---|---|
| HOLEN | /{device_type}/{id}/state/transform?session= | -- | { "transform": {...} } |
| BEITRAG | /{device_type}/{id}/state/transform?session= | { "transform": {...} } | zurückgegebener Wert |
| LÖSCHEN | /{device_type}/{id}/state/transform?session= | -- | Identitätswandel |
Konfiguration speichern
Funktioniert nur mit „ Inverse3 “-Geräten. Warnung: Speichern Sie die Konfiguration nicht zu oft, da pro Gerät nur eine begrenzte Anzahl von Schreibvorgängen möglich ist (ca. 10.000 EEPROM-Schreibvorgänge).
Methode: POST
URL: http://localhost:10001/save_configuration
Beispiel für den Body:
{
"device_id": "049D"
}
Beispiel für die Antwort:
{
"ok": true
}
Einstellungen
Die Endpunkte für Einstellungen werden automatisch generiert für:
- Auflistung aller Einstellungen (einschließlich Metadaten)
- Auslesen eines einzelnen Einstellungswerts
- Einstellungen anwenden (einzeln oder im Stapel)
- Zurücksetzen eines Schlüssels auf seinen Standardwert
Alle Verweise auf Einstellungsschlüssel finden Sie hier
Routen
| Methode | Route | Beschreibung |
|---|---|---|
| HOLEN | /settings/ | Ruft alle Einstellungsschlüssel, Werte und Metadaten ab. |
| BEITRAG | /settings/ | Wendet mehrere Einstellungen gleichzeitig im Batch an. |
| HOLEN | /settings/{key} | Ruft den aktuellen Wert eines bestimmten Einstellungsschlüssels ab. |
| BEITRAG | /settings/{key} | Wendet einen neuen Wert auf einen bestimmten Schlüssel an. |
| LÖSCHEN | /settings/{key} | Setzt einen Schlüssel auf seinen Standardwert zurück. |
Aufbau der Antwort
HOLEN /settings/ (alle Einstellungen)
Gibt ein Objekt zurück, das nach Einstellungsschlüsseln indiziert ist. Jeder Eintrag enthält:
value: der aktuelle Wertmetadata: Typ + Einschränkungen + Sperrstatus
Beispiel-Einträge:
{
"devices/detection/timeout": {
"metadata": {
"constraint": {
"range": {
"max": 15,
"min": 1,
"step": 0
}
},
"locked": false,
"type_hint": "INT"
},
"value": 5
}
}
HOLEN /settings/{key} (Einzelne Einstellung)
Gibt nur den Wert (ohne Metadaten) für den angeforderten Schlüssel zurück.
Einstellungen anwenden
BEITRAG /settings/ (Batch-Anwendung)
Wendet mehrere Schlüssel gleichzeitig im Batch an.
Empfohlenes Body-Format: ein JSON-Objekt, das Schlüssel auf Werte abbildet.
{
"devices/detection/timeout": 5,
"devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}
BEITRAG /settings/{key} (einmalige Anwendung)
Wendet einen neuen Wert auf einen einzelnen Schlüssel an.
Empfohlenes Body-Format: entweder ein roher JSON-Wert oder ein in ein Objekt verpackter Wert (Letzteres wird aus Gründen der Übersichtlichkeit bevorzugt).
{
"value": 5
}
Einstellungen zurücksetzen
LÖSCHEN /settings/{key}
Setzt den Schlüssel auf seinen Standardwert zurück.
Dies entspricht „Auf Standardwert zurücksetzen“.
Tipps
Der Dienst leitet type_hint automatisch. GENERIC wird als Ausweichlösung für komplexe Typen verwendet.
Unterstützte Hinweise:
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
Veraltete Legacy-Endpunkte
Einige POST-Endpunkte werden zwar noch akzeptiert, lösen jedoch eine Deprecation-Warnung aus
und werden in 4.0 entfernt. Siehe den Migrationsleitfaden zu 3.5
für die vollständige Zuordnungstabelle von veraltetem Weg → Ersatzroute.