Version: 3.5.x

HTTP

Standardmäßig wird der HTTP-Dienst eingeschaltet: http://localhost:10001.

Der Port kann in der Konfiguration des Dienstes geändert werden.

Übersicht

In diesem Abschnitt werden die vom Dienst bereitgestellten HTTP-Routen beschrieben.

Bei allen unten aufgeführten Routen wird von der Standard-Basis-URL ausgegangen: http://localhost:10001.

Standard-Antwortumschlag

Alle Endpunkte geben eine von zwei Hüllkurven zurück:

Antwort „Keine Daten“ (wird bei Endpunkten verwendet, die ausschließlich auf Mutationen basieren):

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

Datenantwort (wird bei GET sowie bei POST/DELETE an Konfigurations-Endpunkten verwendet, die den übermittelten Wert zurückgeben):

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

Syntax der Geräteauswahl

Routen auf Geräteebene verwenden das Muster /{device_type}/{id_or_index}/.... Die {device_type} und {id_or_index} Pfadsegmente identifizieren das/die Zielgerät(e).

Beispiel für ein Wegsegment	Bedeutung
`inverse3/0`	Erste Inverse3 Index (0-basiert)
`inverse3/A14`	Inverse3 Geräte-ID `A14`
`inverse3/*`	Alle Inverse3 (Platzhalter)
`verse_grip/0`	Erste Strophe – Griff nach Index
`wireless_verse_grip/*`	Alle kabellosen 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)

Regeln für Platzhalter:

GET lehnt mehrdeutige/Platzhalter-Selektoren ab (gibt 400).
POST und DELETE Platzhalter zulassen – die Operation wird auf alle übereinstimmenden Geräte angewendet.

Sitzungsauswahl

Endpunkte mit Sitzungsgültigkeit (basis, mount, preset, transform, filters) erfordern eine ?session=<expr> Abfrageparameter zur Identifizierung der Sitzung.

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

Beispiel für eine Antwort:

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

Gibt 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, stateund status.

Sie können optional übergeben ?session=<expr> um den Snapshot auf die Perspektive einer bestimmten Sitzung zu filtern (wendet die Basis, die Einbindung und die Transformationen dieser Sitzung auf die zurückgegebenen Werte an).

Beispiel für eine Antwort:

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

Sitzungen

Methode	Pfad	Beschreibung
HOLEN	`/sessions`	Alle aktiven v3.1-Sitzungen auflisten
HOLEN	`/sessions/{session_id}`	Eine einzelne Sitzung buchen
HOLEN	`/sessions/{session_id}/profile`	Sitzungsprofilnamen abrufen
BEITRAG	`/sessions/{session_id}/profile`	Sitzungsprofil festlegen
LÖSCHEN	`/sessions/{session_id}/profile`	Profil zurücksetzen auf `"default"`

BEITRAG /sessions/{session_id}/profile Text:

{
  "name": "my_profile"
}

Anschlüsse

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

Löst eine Blockierung der seriellen Schnittstelle auf. Gibt { "ok": true }.

Gerätekonfiguration

Alle Konfigurationsendpunkte verwenden das Muster /{device_type}/{id_or_index}/config/{setting}.

Endpunkte mit Sitzungsgültigkeit (basis, mount, preset) erfordern zusätzlich eine ?session=<expr> Abfrageparameter.

Händigkeit (Inverse3 )

Methode	Pfad	Hauptteil	Antwort
HOLEN	`/{device_type}/{id}/config/handedness`	--	`"left"` oder `"right"`
BEITRAG	`/{device_type}/{id}/config/handedness`	`"left"` oder `"right"`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/handedness`	--	`"right"` (Standard)

Drehmomentskalierung (Inverse3 )

Methode	Pfad	Hauptteil	Antwort
HOLEN	`/{device_type}/{id}/config/torque_scaling`	--	`{ "enabled": bool }`
BEITRAG	`/{device_type}/{id}/config/torque_scaling`	`{ "enabled": bool }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/torque_scaling`	--	`{ "enabled": false }`

Schwerkraftkompensation (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 }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/gravity_compensation`	--	`{ "enabled": true, "scaling_factor": 1.0 }`

Basis (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" }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/basis?session=`	--	`{ "permutation": "XYZ" }`

Einbinden (alle Geräte, sitzungsbezogen)

Methode	Pfad	Hauptteil	Antwort
HOLEN	`/{device_type}/{id}/config/mount?session=`	--	`{ "transform": {...} }`
BEITRAG	`/{device_type}/{id}/config/mount?session=`	`{ "transform": {...} }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/mount?session=`	--	Identitätstransformation

Form transformieren (wird von „mount“ und „state/transform“ verwendet):

{
  "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" }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/preset?session=`	--	`{ "preset": "device_defaults" }`

Mögliche Werte: device_defaults, arm_front, arm_front_centered, led_front, led_front_centered, custom.

Gerätefilter (Inverse3 , sitzungsbezogen)

Verwendung von Filter-Endpunkten /{device_type}/{id}/config/filters/{filter}?session=<expr>.

Dämpfung

Steuert sowohl die gleichmäßige als auch die gerichtete 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	übernommene 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 }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/config/filters/force_gate?session=`	--	Aus den Standardeinstellungen übernehmen

Gerätestatus

Transformieren (alle Geräte, sitzungsbezogen)

Arbeitsraumtransformation (vom Geräteraum in den Anwendungsraum).

Methode	Pfad	Hauptteil	Antwort
HOLEN	`/{device_type}/{id}/state/transform?session=`	--	`{ "transform": {...} }`
BEITRAG	`/{device_type}/{id}/state/transform?session=`	`{ "transform": {...} }`	wiedergegebener Wert
LÖSCHEN	`/{device_type}/{id}/state/transform?session=`	--	Identitätstransformation

Konfiguration speichern

Funktioniert nur mit Inverse3 . Warnung: Speichern Sie die Konfiguration nicht zu oft, da die Anzahl der Speichervorgänge, die auf ein bestimmtes Gerät angewendet werden können, begrenzt ist (~10.000 EEPROM-Schreibvorgänge).

Methode: POST
URL: http://localhost:10001/save_configuration

Beispiel Körper:

{
  "device_id": "049D"
}

Beispiel für eine Antwort:

{
  "ok": true
}

Einstellungen

Einstellungsendpunkte werden automatisch generiert für:

Alle Einstellungen auflisten (einschließlich Metadaten)
Einen einzelnen Einstellungswert auslesen
Einstellungen anwenden (einzeln oder stapelweise)
Einen Schlüssel auf seinen Standardwert zurücksetzen

Alle wichtigen Hinweise zu den Einstellungen finden Sie hier

Routen

Methode	Route	Beschreibung
HOLEN	`/settings/`	Alle Einstellungsschlüssel, Werte und Metadaten abrufen.
BEITRAG	`/settings/`	Mehrere Einstellungen gleichzeitig anwenden.
HOLEN	`/settings/{key}`	Den aktuellen Wert eines bestimmten Einstellungsschlüssels abrufen.
BEITRAG	`/settings/{key}`	Weise einem bestimmten Schlüssel einen neuen Wert zu.
LÖSCHEN	`/settings/{key}`	Einen Schlüssel auf seinen Standardwert zurücksetzen.

Antwortform

HOLEN `/settings/` (alle Einstellungen)

Gibt ein Objekt zurück, dessen Schlüssel dem angegebenen Schlüssel entsprechen. Jeder Eintrag enthält:

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

Beispiele:

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

HOLEN `/settings/{key}` (Einzel-Einstellung)

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

Einstellungen anwenden

BEITRAG `/settings/` (Stapelverarbeitung)

Mehrere Schlüssel gleichzeitig anwenden.

Empfohlenes Format für den Hauptteil: ein JSON-Objekt, das Schlüssel Werten zuordnet.

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

BEITRAG `/settings/{key}` (Einzelantrag)

Wende einen neuen Wert auf einen einzelnen Schlüssel an.

Empfohlenes Format für den Hauptteil: entweder ein JSON-Rohwert oder ein umschlossener Wert (aus Gründen der Übersichtlichkeit wird die Umschließung empfohlen).

{
  "value": 5
}

Einstellungen zurücksetzen

LÖSCHEN `/settings/{key}`

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

Das entspricht einem „Zurücksetzen auf die Standardeinstellungen“.

Typ-Hinweise

Der Dienst leitet ab type_hint automatisch. 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 Endpunkte

Mehrere POST Endpunkte werden weiterhin akzeptiert, es wird jedoch eine Verwendungswarnung ausgegeben, und sie werden in 4.0. Siehe die 3.5 Migrationsleitfaden für die vollständige Tabelle „veraltete Pfade → Ersatzrouten“.

Übersicht​

Standard-Antwortumschlag​

Syntax der Geräteauswahl​

Sitzungsauswahl​

Version​

Expertenstatus​

Geräte​

Sitzungen​

Anschlüsse​

Gerätekonfiguration​

Händigkeit (Inverse3 )​

Drehmomentskalierung (Inverse3 )​

Schwerkraftkompensation (Inverse3 )​

Basis (alle Geräte, sitzungsbezogen)​

Einbinden (alle Geräte, sitzungsbezogen)​

Voreinstellung (alle Geräte, sitzungsbezogen)​

Gerätefilter (Inverse3 , sitzungsbezogen)​

Dämpfung​

Krafttor​

Gerätestatus​

Transformieren (alle Geräte, sitzungsbezogen)​

Konfiguration speichern​

Einstellungen​

Routen​

Antwortform​

HOLEN /settings/ (alle Einstellungen)​

HOLEN /settings/{key} (Einzel-Einstellung)​

Einstellungen anwenden​

BEITRAG /settings/ (Stapelverarbeitung)​

BEITRAG /settings/{key} (Einzelantrag)​

Einstellungen zurücksetzen​

LÖSCHEN /settings/{key}​

Typ-Hinweise​

Veraltete Endpunkte​

Übersicht

Standard-Antwortumschlag

Syntax der Geräteauswahl

Sitzungsauswahl

Version

Expertenstatus

Geräte

Sitzungen

Anschlüsse

Gerätekonfiguration

Händigkeit (Inverse3 )

Drehmomentskalierung (Inverse3 )

Schwerkraftkompensation (Inverse3 )

Basis (alle Geräte, sitzungsbezogen)

Einbinden (alle Geräte, sitzungsbezogen)

Voreinstellung (alle Geräte, sitzungsbezogen)

Gerätefilter (Inverse3 , sitzungsbezogen)

Dämpfung

Krafttor

Gerätestatus

Transformieren (alle Geräte, sitzungsbezogen)

Konfiguration speichern

Einstellungen

Routen

Antwortform

HOLEN `/settings/` (alle Einstellungen)

HOLEN `/settings/{key}` (Einzel-Einstellung)

Einstellungen anwenden

BEITRAG `/settings/` (Stapelverarbeitung)

BEITRAG `/settings/{key}` (Einzelantrag)

Einstellungen zurücksetzen

LÖSCHEN `/settings/{key}`

Typ-Hinweise

Veraltete Endpunkte