Zum Hauptinhalt springen
Version: 3.1.0

Haply Inverser Dienst

Der Haply Inverse Service ist eine grundlegende Komponente, die die taktilen Geräte von Haply mit interaktiven Anwendungen verbindet und als Windows-Hintergrunddienst läuft, um Interaktionen in Echtzeit zu ermöglichen. Seine Funktionalitäten umfassen:

  • Erkennung und Verwaltung von Geräten: Identifiziert und konfiguriert angeschlossene Haply Geräte automatisch.
  • Verwaltung der Eigentümerschaft: Verwaltet den Zugriff auf Geräte über mehrere Anwendungen hinweg und gewährleistet so einen reibungslosen Betrieb.
  • Status-Streaming in Echtzeit: Liefert Aktualisierungen der Gerätezustände in hoher Frequenz für eine präzise Steuerung.
  • Befehlsverarbeitung: Führt Befehle für Kraft oder Position mit hoher Wiedergabetreue aus und verbessert so das haptische Feedback.
  • Hintergrundbetrieb: Läuft im Hintergrund und hält das Gerät ohne Benutzereingriff betriebsbereit.

Laufen, anhalten, neu starten​

Unter Windows:

  • Öffnen Sie die Dienstleistungen Desktop-App: Drücken Sie . Windows+R zum Öffnen des Laufen lassen Feld, geben Sie services.mscund drücken Sie dann Enter oder wählen Sie OK.

Unter Ubuntu:

  • Start
    • systemctl start haply-inverse-service.service
  • Stopp
    • systemctl stop haply-inverse-service.service
  • Aktivieren Sie
    • systemctl enable haply-inverse-service.service
  • Deaktivieren Sie
    • systemctl disable haply-inverse-service.service

Wichtige Dateien​

Unter Windows:

  • Die Konfigurationsdateien befinden sich in: %PROGRAMDATA%\Haply\Inverse\*-config.json
  • Die Protokolldateien befinden sich in: %PROGRAMDATA%\Haply\Inverse\*-log.log

Unter Ubuntu:

  • Die Konfigurationsdateien befinden sich in: /etc/haply-inverse-service/*-config.json
  • Die Protokolldateien befinden sich in: /var/log/haply-inverse-service/*-log.log

Unter OSX:

  • Die Konfigurationsdateien befinden sich in: $TMPDIR/Haply/Inverse/*-config.json
  • Die Protokolldateien befinden sich in: $TMPDIR/Haply/Inverse/*-log.log

JSON-Format-Versionen​

Der Dienst unterstützt derzeit zwei verschiedene JSON Formate: 3.0 und 3.1. Beide Versionen sind gleichzeitig verfügbar, um die Abwärtskompatibilität zu gewährleisten. Wenn Sie die 3.0 Format in Ihren Simulationen verwenden, sind keine Änderungen erforderlich - es wird weiterhin wie bisher funktionieren. Wir empfehlen Ihnen jedoch, auf die neue Version 3.1.x Version, um die Vorteile der Erweiterungen und der verbesserten Leistung bei der Integration von Spiel-Engines zu nutzen.

Wichtige Details​

  • 3.0 Version

    • Vollständig dokumentiert in der 3.0.x Dokumentationsseiten.
    • HTTP standardmäßig zugänglich auf http://localhost:10000/3.0.
    • Websockets standardmäßig zugänglich auf Hafen 10000.

  • 3.1 Version

    • Vollständig dokumentiert in der 3.1.x Dokumentationsseiten.
    • HTTP standardmäßig zugänglich auf http://localhost:10000/3.1.
    • Websockets standardmäßig zugänglich auf Hafen 10001.
    • Bietet Verbesserungen in der Funktionalität und eine schnellere Integration mit Spiel-Engines.

Sie können auch auf die 3.1 Format zur Verfügung stellen, um die Vorteile ohne Unterbrechung Ihrer bestehenden Arbeitsabläufe zu nutzen.

Schnittstellen​

Sowohl die HTTP- als auch die Websocket-Schnittstelle verwenden JSON formatierte Nutzdaten.

Infos

Wenn Sie die Position des Endeffektors lesen, müssen Sie einen Kraftwert an das Gerät senden (auch wenn die Kraftwerte alle Nullen sind).

HTTP​

Standardmäßig wird der HTTP-Dienst eingeschaltet: http://localhost:10000. Hinweis: Der Anschluss kann in der Konfiguration geändert werden.

Dashboard​

Das Dashboard ist verfügbar unter: http://localhost:10000

Version​

Methode: GET

URL: http://localhost:10000/3.1/version

Beispiel für eine Antwort:

{
    "build_time": "2024-08-07T16:01:53Z",
    "git_branch": "main",
    "git_describe": "3.0.0-2-gce34c39e",
    "git_hash": "ce34c39e",
    "git_tag": "3.0.0",
    "project_name": "haply-inverse-service",
    "project_version": "3.0.0.0"
}

Geräte​

Methode: GET

URL: http://localhost:10000/3.1/devices

Beispiel für eine Antwort:

{
    "inverse3": [
        {
            "device_id": "04BA",
            "config": {
                "type": "inverse3",
                "device_info": {
                    "firmware_version": 1,
                    "hardware_version": 7,
                    "id": "04BA",
                    "model": 4,
                    "uuid": ""
                },
                "port": "COM13",
                "extended_device_id": "2D35F80DD9005F599B68F49944CB04BA",
                "extended_firmware_version": "8C20FDC8010AA1E15AA133CDA2534874",
                "gravity_compensation": {
                    "enabled": true,
                    "scaling_factor": 1
                },
                "handedness": "right",
                "torque_scaling": {
                    "enabled": true
                }
            },
            "state": {
                "angular_position": {
                    "a0": -69.31704,
                    "a1": 137.62952,
                    "a2": 19.832787
                },
                "angular_velocity": {
                    "a0": 0,
                    "a1": 0,
                    "a2": 0
                },
                "body_orientation": {
                    "x": -0.01940918,
                    "y": 0.7026367,
                    "z": 0.00048828125,
                    "w": 0.7113037
                },
                "cursor_position": {
                    "x": 0.07842738,
                    "y": -0.14836666,
                    "z": 0.14297646
                },
                "cursor_velocity": {
                    "x": -0.011969013,
                    "y": 0.0012009288,
                    "z": -0.043197
                },
                "mode": "idle"
            },
            "status": {
                "calibrated": false,
                "in_use": false,
                "power_supply": true,
                "ready": true,
                "started": true
            }
        }
    ],
    "verse_grip": [
        {
            "device_id": "61548",
            "config": {
                "port": "COM3",
                "type": "verse_grip"
            },
            "state": {
                "button": false,
                "hall": 0,
                "orientation": {
                    "x": -0.5019531,
                    "y": 0.8632202,
                    "z": -0.048095703,
                    "w": -0.022338867
                }
            },
            "status": {
                "error": 0,
                "ready": true
            }
        }
    ],
    "wireless_verse_grip": [
        {
            "device_id": "0",
            "config": {
                "port": "COM6",
                "type": "wireless_verse_grip"
            },
            "state": {
                "battery_level": 0.42000008,
                "buttons": {
                    "a": false,
                    "b": false,
                    "c": false
                },
                "hall": 16,
                "orientation": {
                    "x": -0.019866943,
                    "y": -0.017486572,
                    "z": 0.05508423,
                    "w": -0.9963989
                }
            },
            "status": {
                "ready": true
            }
        }
    ]
}

Kraft-Skala​

Methode: POST

URL: http://localhost:10000/3.1/force_scale

Beispiel Körper:

{
    "force_scale": 0.5
}

Beispiel für eine Antwort:

{
    "ok": true
}

Schwerkraft-Kompensation​

Methode: POST

URL: http://localhost:10000/3.1/gravity_compensation

Beispiel Körper:

{
    "device_id": "049D",
    "enable": true,
    "gravity_scaling_factor": 0.8
}

Beispiel für eine Antwort:

{
    "ok": true
}

Skalierung des Drehmoments​

Methode: POST

URL: http://localhost:10000/3.1/torque_scaling

Beispiel Körper:

{
    "device_id": "049D",
    "enable": true
}

Beispiel für eine Antwort:

{
    "ok": true
}

Handlichkeit des Geräts​

Methode: POST

URL: http://localhost:10000/3.1/device_handedness

Beispiel Körper:

{
    "device_id": "049D",
    "handedness": "right"
}

Beispiel für eine Antwort:

{
    "ok": true
}

Konfiguration speichern​

Funktioniert nur mit Inverse3 Geräten. Warnung: Vermeiden Sie es, die Konfiguration zu oft zu speichern, da es nur eine begrenzte Anzahl von Speicherungen gibt, die auf ein bestimmtes Gerät angewendet werden können.

Methode: POST

URL: http://localhost:10000/3.1/save_configuration

Beispiel Körper:

{
    "device_id": "049D"
}

Beispiel für eine Antwort:

{
    "ok": true
}

Serielle Freigabe​

Aktivieren oder deaktivieren Sie die gesamte serielle Kommunikation. Wenn die serielle Kommunikation deaktiviert ist, ist es nicht möglich, Befehle an die Geräte zu senden.

Methode: POST

URL: http://localhost:10000/3.1/serial_enable

Beispiel Körper:

{
    "enable": true
}

Beispiel für eine Antwort:

{
    "ok": true
}

Grip Vertikalstopper​

Aktivieren oder deaktivieren Sie die experimentelle Funktion des vertikalen Stoppers des Griffs. Diese Funktion überprüft die Ausrichtung des drahtlosen VerseGrip, um zu erkennen, wenn der VerseGrip fallen gelassen wird. Wenn sie ausgelöst wird, wird die Inverse3 in ihrer aktuellen Position in Positionskontrolle versetzt, damit der Endeffektor nicht herunterfällt. Sie wird automatisch deaktiviert, wenn der VerseGrip wieder aufgenommen wird.

Warnung

Da es sich um eine experimentelle Funktion handelt, ist sie standardmäßig deaktiviert und muss zur Aktivierung explizit aktiviert werden.

Methode: POST

URL: http://localhost:10000/3.1/experimental/features/grip_dropped_simulation_stopper

Beispiel Körper:

{
    "enable": true,
    "hall_effect_threshold": 17
}

Beispiel für eine Antwort:

{
    "ok": true
}

Websocket​

Die Standard-URL für den Websocket lautet ws://localhost:10001. Hinweis: Der Anschluss kann in der Konfiguration geändert werden.

Initiale Nachricht​

Der Dienst sendet eine Nachricht mit der vollständigen Geräteliste, wenn eine Verbindung zu einem Websocket hergestellt wird. Die erste Nachricht hat den folgenden Inhalt JSON Format:

{
    "inverse3": [
        {
            "device_id": "04BA",
            "config": {
                "type": "inverse3",
                "device_info": {
                    "firmware_version": 1,
                    "hardware_version": 7,
                    "id": "04BA",
                    "model": 4,
                    "uuid": ""
                },
                "port": "COM13",
                "extended_device_id": "2D35F80DD9005F599B68F49944CB04BA",
                "extended_firmware_version": "8C20FDC8010AA1E15AA133CDA2534874",
                "gravity_compensation": {
                    "enabled": true,
                    "scaling_factor": 1
                },
                "handedness": "right",
                "torque_scaling": {
                    "enabled": true
                }
            },
            "state": {
                "angular_position": {
                    "a0": -69.31704,
                    "a1": 137.62952,
                    "a2": 19.832787
                },
                "angular_velocity": {
                    "a0": 0,
                    "a1": 0,
                    "a2": 0
                },
                "body_orientation": {
                    "x": -0.01940918,
                    "y": 0.7026367,
                    "z": 0.00048828125,
                    "w": 0.7113037
                },
                "cursor_position": {
                    "x": 0.07842738,
                    "y": -0.14836666,
                    "z": 0.14297646
                },
                "cursor_velocity": {
                    "x": -0.011969013,
                    "y": 0.0012009288,
                    "z": -0.043197
                },
                "mode": "idle"
            },
            "status": {
                "calibrated": false,
                "in_use": false,
                "power_supply": true,
                "ready": true,
                "started": true
            }
        }
    ],
    "verse_grip": [
        {
            "device_id": "61548",
            "config": {
                "port": "COM3",
                "type": "verse_grip"
            },
            "state": {
                "button": false,
                "hall": 0,
                "orientation": {
                    "x": -0.5019531,
                    "y": 0.8632202,
                    "z": -0.048095703,
                    "w": -0.022338867
                }
            },
            "status": {
                "error": 0,
                "ready": true
            }
        }
    ],
    "wireless_verse_grip": [
        {
            "device_id": "0",
            "config": {
                "port": "COM6",
                "type": "wireless_verse_grip"
            },
            "state": {
                "battery_level": 0.42000008,
                "buttons": {
                    "a": false,
                    "b": false,
                    "c": false
                },
                "hall": 16,
                "orientation": {
                    "x": -0.019866943,
                    "y": -0.017486572,
                    "z": 0.05508423,
                    "w": -0.9963989
                }
            },
            "status": {
                "ready": true
            }
        }
    ]
}

Status Update Nachricht​

Der Dienst sendet für jede empfangene Befehlsnachricht eine Statusaktualisierungsnachricht, die den Status aller Geräte enthält.

Wenn Sie den Zustand der Maschine wissen wollen, müssen Sie ihr vorher eine Nachricht schicken, z. B. einen Kraftwert (auch wenn die Werte Nullen sind). Dies ist besonders wichtig, wenn unsere Geräte als Eingabegerät verwendet werden, z. B. um die Position zu verfolgen und keine Kraft anzuwenden. Die Zustandsaktualisierungsnachricht hat folgenden Inhalt JSON Format:

{
    "inverse3": [
        {
            "device_id": "04BA",
            "state": {
                "angular_position": {
                    "a0": -69.31704,
                    "a1": 137.62952,
                    "a2": 19.832787
                },
                "angular_velocity": {
                    "a0": 0,
                    "a1": 0,
                    "a2": 0
                },
                "body_orientation": {
                    "x": -0.01940918,
                    "y": 0.7026367,
                    "z": 0.00048828125,
                    "w": 0.7113037
                },
                "cursor_position": {
                    "x": 0.07842738,
                    "y": -0.14836666,
                    "z": 0.14297646
                },
                "cursor_velocity": {
                    "x": -0.011969013,
                    "y": 0.0012009288,
                    "z": -0.043197
                },
                "mode": "idle"
            },
            "status": {
                "calibrated": false,
                "in_use": false,
                "power_supply": true,
                "ready": true,
                "started": true
            }
        }
    ],
    "verse_grip": [
        {
            "device_id": "61548",
            "state": {
                "button": false,
                "hall": 0,
                "orientation": {
                    "x": -0.5019531,
                    "y": 0.8632202,
                    "z": -0.048095703,
                    "w": -0.022338867
                }
            },
            "status": {
                "error": 0,
                "ready": true
            }
        }
    ],
    "wireless_verse_grip": [
        {
            "device_id": "0",
            "state": {
                "battery_level": 0.42000008,
                "buttons": {
                    "a": false,
                    "b": false,
                    "c": false
                },
                "hall": 16,
                "orientation": {
                    "x": -0.019866943,
                    "y": -0.017486572,
                    "z": 0.05508423,
                    "w": -0.9963989
                }
            },
            "status": {
                "ready": true
            }
        }
    ]
}

Befehlsnachricht​

Zum Senden von Befehlen an das inverse3 muss der Client eine Befehlsnachricht senden. Hier ist ein Beispiel:

{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "set_cursor_force": {
                    "values": {
                        "x": 1.0,
                        "y": 2.0,
                        "z": 3.0
                    }
                }
            }
        }
    ],
    "verse_grip": [],
    "wireless_verse_grip": []
}

Es ist auch möglich, Befehle an mehrere Geräte in einer einzigen Nachricht zu senden. Hier ein Beispiel:

{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "set_cursor_force": {
                    "values": {
                        "x": 1.0,
                        "y": 2.0,
                        "z": 3.0
                    }
                }
            }
        },
        {
            "device_id": "049E",
            "commands": {
                "set_cursor_force": {
                    "values": {
                        "x": 1.0,
                        "y": 2.0,
                        "z": 3.0
                    }
                }
            }
        }
    ],
    "verse_grip": [],
    "wireless_verse_grip": []
}

Die folgenden Befehle sind derzeit auf der Website inverse3:

Cursorposition einstellen​
{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "set_cursor_position": {
                    "values": {
                        "x": 1.0,
                        "y": 2.0,
                        "z": 3.0
                    }
                }
            }
        }
    ],
    "verse_grip": [],
    "wireless_verse_grip": []
}
Cursorkraft einstellen​
{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "set_cursor_force": {
                    "values": {
                        "x": 1.0,
                        "y": 2.0,
                        "z": 3.0
                    }
                }
            }
        }
    ],
    "verse_grip": [],
    "wireless_verse_grip": []
}
Winkellage einstellen​
{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "set_cursor_force": {
                    "values": {
                        "x": 1.0,
                        "y": 2.0,
                        "z": 3.0
                    }
                }
            }
        }
    ],
    "verse_grip": [],
    "wireless_verse_grip": []
}
Winkelmoment einstellen​
{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "set_angular_torque": {
                    "values": {
                        "a0": 1.0,
                        "a1": 2.0,
                        "a2": 3.0
                    }
                }
            }
        }
    ],
    "verse_grip": [],
    "wireless_verse_grip": []
}
Sondierungsbefehle​

probe_cursor_position, probe_angular_position für die inverse3, und probe_orientation für Verse grips all enthält keine Befehlsdaten.

{
    "inverse3": [
        {
            "device_id": "049D",
            "commands": {
                "probe_cursor_position": {},
                "probe_angular_position": {}
            }
        }
    ],
    "verse_grip": [
        {
            "device_id": "049D",
            "commands": {
                "probe_orientation": {}
            }
        }
    ],
    "wireless_verse_grip": [
        {
            "device_id": "049D",
            "commands": {
                "probe_orientation": {}
            }
        }
    ]
}