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 liefern 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

Geräteebene-Routen verwenden das 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 Verse Grip nach Index
`wireless_verse_grip/*`	Alle Wireless Verse Grips
`inverse/`	Alle Geräte der Inverse-Familie (Inverse3, Inverse3x, Minverse)
`verse_grip/`	Alle Geräte der Verse-Grip-Familie (Verse Grip, Wireless VG)

Platzhalterregeln:

GET lehnt mehrdeutige bzw. Platzhalter-Selektoren ab (liefert 400).
POST und DELETE akzeptieren Platzhalter -- die Operation wird auf alle passenden Geräte angewendet.

Sitzungsselektor

Sitzungsbezogene Endpunkte (basis, mount, preset, transform, filters) benötigen den Query-Parameter ?session=<expr>, um die Sitzung zu identifizieren.

Ausdruck	Bedeutung
(weggelassen)	Alle Sitzungen (nur DELETE)
`#123` oder `123`	Sitzung mit numerischer ID 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

Antwortbeispiel:

{
  "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"
}

Expert-Status

Methode: GET
URL: http://localhost:10001/expert/status

Gibt detaillierte Statusinformationen zurück, einschließlich Erkennung, Geräten, Sitzungen und globalen Einstellungen.

Geräte

Methode: GET
URL: http://localhost:10001/devices

Gibt das aktuelle Geräteinventar 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).

Antwortbeispiel:

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

Sitzungen

Methode	Pfad	Beschreibung
GET	`/sessions`	Listet alle aktiven v3.1-Sitzungen auf
GET	`/sessions/{session_id}`	Ruft eine einzelne Sitzung ab
GET	`/sessions/{session_id}/profile`	Ruft den Namen des Sitzungsprofils ab
POST	`/sessions/{session_id}/profile`	Legt das Sitzungsprofil fest
DELETE	`/sessions/{session_id}/profile`	Setzt das Profil auf `"default"` zurück

Body von POST /sessions/{session_id}/profile:

{
  "name": "my_profile"
}

Ports

Methode: POST
URL: http://localhost:10001/ports/{port}/reset

Gibt einen blockierten seriellen Port frei. Gibt { "ok": true } zurück.

Gerätekonfiguration

Alle Konfigurations-Endpunkte verwenden das Muster /{device_type}/{id_or_index}/config/{setting}.

Sitzungsbezogene Endpunkte (basis, mount, preset) benötigen zusätzlich den Query-Parameter ?session=<expr>.

Händigkeit (nur Inverse3)

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/handedness`	--	`"left"` oder `"right"`
POST	`/{device_type}/{id}/config/handedness`	`"left"` oder `"right"`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/config/handedness`	--	`"right"` (Standard)

Drehmomentskalierung (nur Inverse3)

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/torque_scaling`	--	`{ "enabled": bool }`
POST	`/{device_type}/{id}/config/torque_scaling`	`{ "enabled": bool }`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/config/torque_scaling`	--	`{ "enabled": false }`

Gravitationskompensation (nur Inverse3)

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/gravity_compensation`	--	`{ "enabled": bool, "scaling_factor": float }`
POST	`/{device_type}/{id}/config/gravity_compensation`	`{ "enabled": bool, "scaling_factor": float }`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/config/gravity_compensation`	--	`{ "enabled": true, "scaling_factor": 1.0 }`

Basis (alle Geräte, sitzungsbezogen)

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/basis?session=`	--	`{ "permutation": "XYZ" }`
POST	`/{device_type}/{id}/config/basis?session=`	`{ "permutation": "ZXY" }`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/config/basis?session=`	--	`{ "permutation": "XYZ" }`

Mount (alle Geräte, sitzungsbezogen)

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/mount?session=`	--	`{ "transform": {...} }`
POST	`/{device_type}/{id}/config/mount?session=`	`{ "transform": {...} }`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/config/mount?session=`	--	Identitäts-Transformation

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 }
  }
}

Preset (alle Geräte, sitzungsbezogen)

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/preset?session=`	--	`{ "preset": "arm_front_centered" }`
POST	`/{device_type}/{id}/config/preset?session=`	`{ "preset": "arm_front_centered" }`	zurückgegebener Wert
DELETE	`/{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	Body	Antwort
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 }` oder `{ "vector": {...} }` oder beides	zurückgegebene Werte
DELETE	`/{device_type}/{id}/config/filters/damping?session=`	--	beide auf null zurückgesetzt

Force Gate

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/config/filters/force_gate?session=`	--	`{ "gain": float }`
POST	`/{device_type}/{id}/config/filters/force_gate?session=`	`{ "gain": float }`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/config/filters/force_gate?session=`	--	Gain aus den Standardeinstellungen

Gerätezustand

Transform (alle Geräte, sitzungsbezogen)

Workspace-Transformation (vom Gerätebereich zum Anwendungsbereich).

Methode	Pfad	Body	Antwort
GET	`/{device_type}/{id}/state/transform?session=`	--	`{ "transform": {...} }`
POST	`/{device_type}/{id}/state/transform?session=`	`{ "transform": {...} }`	zurückgegebener Wert
DELETE	`/{device_type}/{id}/state/transform?session=`	--	Identitätstransformation

Konfiguration speichern

Funktioniert nur mit Inverse3-Geräten. Warnung: Vermeiden Sie es, die Konfiguration zu oft zu speichern, da pro Gerät nur eine begrenzte Anzahl an Speichervorgä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:

Auflisten aller Einstellungen (einschließlich Metadaten)
Lesen eines einzelnen Einstellungswerts
Anwenden von Einstellungen (einzeln oder im Batch)
Zurücksetzen eines Schlüssels auf seinen Standardwert

Alle Referenzen auf Einstellungsschlüssel finden Sie hier

Routen

Methode	Route	Beschreibung
GET	`/settings/`	Ruft alle Einstellungsschlüssel, Werte und Metadaten ab.
POST	`/settings/`	Wendet mehrere Einstellungen auf einmal im Batch an.
GET	`/settings/{key}`	Ruft den aktuellen Wert eines bestimmten Einstellungsschlüssels ab.
POST	`/settings/{key}`	Wendet einen neuen Wert auf einen bestimmten Schlüssel an.
DELETE	`/settings/{key}`	Setzt einen Schlüssel auf seinen Standardwert zurück.

Aufbau der Antwort

GET `/settings/` (alle Einstellungen)

Gibt ein Objekt zurück, das nach Einstellungsschlüssel indiziert ist. Jeder Eintrag enthält:

value: der aktuelle Wert
metadata: Typ + Einschränkungen + Sperrstatus

Beispieleinträge:

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

GET `/settings/{key}` (einzelne Einstellung)

Gibt nur den Wert (ohne Metadaten) für den angeforderten Schlüssel zurück.

Einstellungen anwenden

POST `/settings/` (Batch-Anwendung)

Wendet mehrere Schlüssel auf einmal 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"]
}

POST `/settings/{key}` (einzelne 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 der Übersichtlichkeit halber bevorzugt).

{
  "value": 5
}

Zurücksetzen von Einstellungen

DELETE `/settings/{key}`

Setzt den Schlüssel auf seinen Standardwert zurück.

Dies entspricht „auf Standardwert zurücksetzen“.

Typ-Hinweise

Der Dienst leitet type_hint automatisch ab. GENERIC wird als Ausweichlösung für komplexe Typen verwendet.

Unterstützte Hinweise:

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

Veraltete Legacy-Endpunkte

Einige POST-Endpunkte werden noch akzeptiert, lösen aber eine Deprecation-Warnung aus und werden in 4.0 entfernt. Siehe den Migrationsleitfaden zu 3.5 für die vollständige Zuordnungstabelle von veraltetem Pfad → Ersatzroute.

Übersicht​

Standardstruktur der Antwort​

Syntax des Geräteselektors​

Sitzungsselektor​

Version​

Expert-Status​

Geräte​

Sitzungen​

Ports​

Gerätekonfiguration​

Händigkeit (nur Inverse3)​

Drehmomentskalierung (nur Inverse3)​

Gravitationskompensation (nur Inverse3)​

Basis (alle Geräte, sitzungsbezogen)​

Mount (alle Geräte, sitzungsbezogen)​

Preset (alle Geräte, sitzungsbezogen)​

Gerätefilter (nur Inverse3, sitzungsbezogen)​

Dämpfung​

Force Gate​

Gerätezustand​

Transform (alle Geräte, sitzungsbezogen)​

Konfiguration speichern​

Einstellungen​

Routen​

Aufbau der Antwort​

GET /settings/ (alle Einstellungen)​

GET /settings/{key} (einzelne Einstellung)​

Einstellungen anwenden​

POST /settings/ (Batch-Anwendung)​

POST /settings/{key} (einzelne Anwendung)​

Zurücksetzen von Einstellungen​

DELETE /settings/{key}​

Typ-Hinweise​

Veraltete Legacy-Endpunkte​