01. Inverse3 drucken

Stellt eine Verbindung zum Simulations-WebSocket her und überträgt die Cursorposition, Geschwindigkeit und Kraft des ersten Inverse3 Dienst meldet.

Was Sie lernen werden:

• Eine WebSocket-Verbindung herstellen und die erste Full-State-Nachricht empfangen
• Eine Kraft von Null senden set_cursor_force Keepalive, um die Sitzung aufrechtzuerhalten
• Ein Sitzungsprofil registrieren, damit Haply Ihre Simulation erkennt
• Das Handshake-Muster „Nur erste Nachricht“ – „strip session/configure“ nach dem ersten Sendevorgang
• Den Arbeitsbereich lesen transform (Position, Drehung, Skalierung) mit Teilaktualisierungssemantik
• Die Konsolenausgabe auf ein überschaubares Maß drosseln

Arbeitsablauf

1. Öffne einen WebSocket zu ws://localhost:10001. Der Dienst sendet umgehend eine Vollbild Auflistung der verbundenen Geräte.
2. Wähle im ersten Frame die ersten Inverse3 aus device_id und erstellen Sie eine Anforderungsnachricht, die aus zwei Teilen besteht:
   • session.configure.profile.name — registriert die Simulation bei Haply Hub.
   • Pro Gerät set_cursor_force Befehl mit einem Nullvektor. Der Dienst nutzt dies als Keepalive – er sendet so lange Status-Frames, wie Befehle eingehen.
3. Sende die Nachricht zurück. Entfernen Sie die session Feld vor dem nächsten Tick – das Sitzungsprofil ist ein einmaliger Handshake; bei den folgenden Ticks wird nur der Befehl gesendet.
4. Bei jedem folgenden Status-Frame: Cursor anzeigen vec3 Felder (Position, Geschwindigkeit, Kraft), auf ca. 10 Hz gedrosselt, und das Keepalive-Signal für Nullkraft erneut senden.

Parameter

Name	Standard	Zweck
URI	ws://localhost:10001	WebSocket-URL des Simulationskanals
PRINT_EVERY_MS	100	Drosselung der Konsolenausgabe
Name des Sitzungsprofils	co.haply.inverse.tutorials:print-inverse3	Identifiziert diese Simulation im Haply

Statusfelder gelesen

Von data.inverse3[0].state:

• cursor_position, cursor_velocity, current_cursor_force — vec3 jeweils
• transform — Arbeitsbereichstransformation; Unterobjekt mit position (vec3), rotation (quaternion), scale (vec3)

Semantik der Teilaktualisierung

Unterfelder, die ihrem Standardwert entsprechen (position: {0,0,0}, rotation: {w:1,x:0,y:0,z:0}, scale: {1,1,1}) sind weggelassen aus der Nutzlast, um Bandbreite zu sparen. Geben Sie beim Lesen immer einen Standardwert an (z. B. .value("position", default_pos) in C++, .get("position", default_pos) (in Python). Aktivieren serialization/explicit_fields um stets alle Felder zu erhalten.

Senden / Empfangen

Die WebSocket-Schleife: einen Status-Frame empfangen, einen Befehlsrahmen. Der erste Befehlsrahmen enthält den Sitzungs-Handshake und eine Nullkraft set_cursor_force Keepalive; jeder nachfolgende Frame enthält nur der Keepalive (die Sitzung wird beendet).

Python

Einzelne asynchrone Schleife — recv() → Build-Befehl → send() → Wiederholen.

async with websockets.connect(URI) as websocket:
    while True:
        msg  = await websocket.recv()
        data = json.loads(msg)

        if first_message:
            first_message = False
            device_id = data["inverse3"][0]["device_id"]
            request_msg = {
                "session": {"configure": {"profile": {
                    "name": "co.haply.inverse.tutorials:print-inverse3"}}},
                "inverse3": [{
                    "device_id": device_id,
                    "commands": {"set_cursor_force":
                        {"vector": {"x": 0.0, "y": 0.0, "z": 0.0}}},
                }]
            }

        await websocket.send(json.dumps(request_msg))
        request_msg.pop("session", None)  # one-shot handshake

C++ (nlohmann)

libhv steuert den WebSocket in einem eigenen E/A-Thread – das Frame-basierte Framework befindet sich in ws.onmessage. Der Hauptthread bleibt bei der Eingabetaste hängen.

ws.onmessage = [&](const std::string &msg) {
    const json data = json::parse(msg);

    if (first_message) {
        first_message = false;
        device_id = data["inverse3"][0].at("device_id").get<std::string>();
        request_msg = {
            {"session", {{"configure", {{"profile",
                {{"name", "co.haply.inverse.tutorials:print-inverse3"}}}}}}},
            {"inverse3", json::array({
                {{"device_id", device_id},
                 {"commands", {{"set_cursor_force",
                   {{"vector", {{"x", 0.0}, {"y", 0.0}, {"z", 0.0}}}}}}}},
            })},
        };
    }

    ws.send(request_msg.dump());
    request_msg.erase("session");  // one-shot handshake
};
ws.open("ws://localhost:10001");
while (std::cin.get() != '\n') {}  // block main thread

C++ (Glaze)

Das gleiche libhv-Callback-Modell wie bei der nlohmann-Variante – nur der Hauptteil ändert sich. Glaze nutzt Reflection zur Kompilierungszeit: Deklarieren Sie Strukturen, die die JSON-Struktur widerspiegeln, rufen Sie glz::read / glz::write_json. std::optional<session_cmd> aktiviert den einmaligen Handshake; wenn diese Option deaktiviert ist, lässt Glaze das Feld in der serialisierten JSON-Datei weg.

// Struct models
struct vec3 { float x{}, y{}, z{}; };
struct inverse_state {
    vec3 cursor_position{}, cursor_velocity{}, current_cursor_force{};
    /* + body_orientation, angular_position, angular_velocity */
};
struct inverse_device { std::string device_id; inverse_state state; };
struct devices_message { std::vector<inverse_device> inverse3; };

struct set_cursor_force_cmd { vec3 vector; };
struct commands_message {
    std::optional<session_cmd> session;  // omitted from JSON when unset
    std::vector<device_commands> inverse3;
};

// Send / receive
ws.onmessage = [&](const std::string &msg) {
    devices_message data{};
    if (glz::read<glz_settings>(data, msg)) return;

    commands_message out_cmds{};
    if (first_message) {
        first_message = false;
        out_cmds.session = session_cmd{ /* profile = print-inverse3 */ };
    }
    // ... populate out_cmds.inverse3 with zero-force keepalive ...

    std::string out_json;
    (void)glz::write_json(out_cmds, out_json);
    ws.send(out_json);
};
ws.open("ws://localhost:10001");
while (std::cin.get() != '\n') {}  // block main thread

Befehlszeilenoptionen (Python)

Die Python-Variante akzeptiert zwei Flags, um die Ausgabe des Tutorials anzupassen:

Flagge	Wirkung
--full	Gibt die rohe JSON-Datenlast jedes Status-Frames in lesbarer Form aus, anstatt nur die einzeilige Zusammenfassung. Nützlich, um herauszufinden, welche Felder der Dienst ausgibt.
--query-config	Wiederverabreichungen session.force_render_full_state: {} bei jedem ausgehenden Tick, sodass der Dienst erneut einen vollständigen Snapshot sendet (einschließlich der config Block – Gerätetyp, Firmware, Voreinstellung, Mount, Filter, …) bei jedem Frame. Ohne diese Angaben config wird nur im ersten Frame übertragen, während die nachfolgenden Frames nur Delta-Daten enthalten.

Beide Flaggen zusammen — python 01-haply-inverse-print-inverse3.py --full --query-config gibt eine vollständige JSON-Nutzlast aus mit config bei jedem Tick sichtbar, was praktisch ist, wenn man die Änderungen der Einstellungen live über Haply oder die HTTP-API verfolgt. Siehe session.force_render_full_state für den zugrunde liegenden WebSocket-Befehl.

Die C++-Varianten machen diese Flags nicht sichtbar – sie geben immer die einzeilige Zusammenfassung aus und empfangen config nur im ersten Bild.

Im Lieferumfang des SDK-Installationsprogramms enthalten

Tutorial 01 wird ebenfalls lokal mit dem SDK installiert – schau mal unter tutorials/01-haply-inverse-print-inverse3/ im Installationsverzeichnis des Dienstes.

Quelle: Python · C++ · C++ Glaze

Siehe auch: WebSocket-Protokoll · Steuerbefehle (set_cursor_force) · Sitzungen · Typen (vec3)