01. Print Inverse3

Connects to the simulation WebSocket and streams cursor position, velocity, and force from the first Inverse3 the service reports.

What you'll learn:

• Opening a WebSocket connection and receiving the initial full-state message
• Sending a zero-force set_cursor_force keepalive to keep the session ticking
• Registering a session profile so Haply Hub recognises your simulation
• The first-message-only handshake pattern — strip session/configure after the first send
• Reading the workspace transform (position, rotation, scale) with partial-update semantics
• Throttling console output to a readable rate

Workflow

1. Open a WebSocket to ws://localhost:10001. The service immediately pushes a full-state frame listing connected devices.
2. On the first frame, pick the first Inverse3's device_id and build a request message with two parts:
   • session.configure.profile.name — registers the simulation with Haply Hub.
   • A per-device set_cursor_force command with a zero vector. The service uses this as a keepalive — it keeps emitting state frames as long as commands keep arriving.
3. Send the message back. Strip the session field before the next tick — session profile is a one-shot handshake; subsequent ticks send only the command.
4. Each subsequent state frame: print the cursor vec3 fields (position, velocity, force), throttled to ~10 Hz, and resend the zero-force keepalive.

Parameters

Name	Default	Purpose
URI	ws://localhost:10001	Simulation channel WebSocket URL
PRINT_EVERY_MS	100	Console-output throttle
Session profile name	co.haply.inverse.tutorials:print-inverse3	Identifies this simulation in Haply Hub

State fields read

From data.inverse3[0].state:

• cursor_position, cursor_velocity, current_cursor_force — vec3 each
• transform — workspace transform; sub-object with position (vec3), rotation (quaternion), scale (vec3)

Partial-update semantics

Sub-fields equal to their identity default (position: {0,0,0}, rotation: {w:1,x:0,y:0,z:0}, scale: {1,1,1}) are omitted from the payload to save bandwidth. Always supply a default when reading (e.g. .value("position", default_pos) in C++, .get("position", default_pos) in Python). Enable serialization/explicit_fields to always receive every field.

Send / receive

The WebSocket loop: receive a state frame, build and send back a command frame. The first command frame carries the session handshake and a zero-force set_cursor_force keepalive; every subsequent frame carries only the keepalive (session is stripped).

Python

Single async loop — recv() → build command → send() → repeat.

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 drives the WebSocket on its own I/O thread — the per-frame work lives in ws.onmessage. The main thread just blocks on ENTER.

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)

Same libhv callback model as the nlohmann variant — only the body changes. Glaze uses compile-time reflection: declare structs that mirror the JSON shape, call glz::read / glz::write_json. std::optional<session_cmd> carries the one-shot handshake; when unset, Glaze omits the field from the serialized JSON.

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

Command-line flags (Python)

The Python variant accepts two flags to change what the tutorial prints:

Flag	Effect
--full	Pretty-prints the raw JSON payload of every state frame instead of the one-line summary. Useful for discovering which fields the service emits.
--query-config	Re-injects session.force_render_full_state: {} on every outbound tick so the service re-emits a complete snapshot (including the config block — device type, firmware, preset, mount, filters, …) on every frame. Without it, config only arrives on the first frame and subsequent frames are streaming deltas.

Both flags combine — python 01-haply-inverse-print-inverse3.py --full --query-config dumps a full JSON payload with config visible every tick, which is handy when watching settings change live from Haply Hub or the HTTP API. See session.force_render_full_state for the underlying WebSocket command.

The C++ variants do not expose these flags — they always print the one-line summary and receive config only on the first frame.

Shipping with the SDK installer

Tutorial 01 is also installed locally with the SDK — look in tutorials/01-haply-inverse-print-inverse3/ under the service install directory.

Source: Python · C++ · C++ Glaze

Related: WebSocket Protocol · Control Commands (set_cursor_force) · Sessions · Types (vec3)