01. 打印Inverse3

连接到模拟 WebSocket，并从服务报告Inverse3 第一个Inverse3 流式传输光标位置、速度和力。

您将学到：

• 建立 WebSocket 连接并接收初始完整状态消息
• 发送零力 set_cursor_force 使用 keepalive 保持会话活跃
• 注册会话配置文件，以便Haply 识别您的模拟
• 仅首条消息的握手模式——在首次发送后移除会话/配置
• 读取工作区 transform （位置、旋转、缩放）采用部分更新语义
• 将控制台输出限制在可读的速度

工作流程

1. 打开一个 WebSocket 连接至 ws://localhost:10001该服务会立即推送一个 全状态帧 列出已连接的设备。
2. 在第一个帧中，选择第一个Inverse3 device_id 并构建一个包含两部分的请求消息：
   • session.configure.profile.name — 将模拟注册到 Haply Hub.
   • 按设备计 set_cursor_force 带有零向量的命令。该服务将其用作保持活动机制——只要持续收到命令，它就会不断发送状态帧。
3. 将消息发回去。 剥去 session 领域 在下一次心跳之前——会话配置文件是一次性握手；后续心跳仅发送命令。
4. 每个后续状态帧：打印光标 vec3 字段（位置、速度、力），采样率限制在约10 Hz，并重新发送零力保持信号。

参数

名称	默认	目的
URI	ws://localhost:10001	模拟通道 WebSocket URL
PRINT_EVERY_MS	100	控制台输出节流阀
会话配置文件名称	co.haply.inverse.tutorials:print-inverse3	在Haply 中标识此模拟

读取状态字段

来自 data.inverse3[0].state:

• cursor_position, cursor_velocity, current_cursor_force — vec3 每个
• transform — 工作区变换；包含 position (vec3)， rotation (quaternion)， scale (vec3)

部分更新语义

子字段的默认值与其标识符相同（position: {0,0,0}, rotation: {w:1,x:0,y:0,z:0}, scale: {1,1,1}) 是 省略 从有效载荷中省略，以节省带宽。读取时请务必提供默认值（例如 .value("position", default_pos) 在 C++ 中， .get("position", default_pos) （在 Python 中）。启用 serialization/explicit_fields 始终接收所有字段。

发送/接收

WebSocket 循环：接收状态帧，构建并发送回一个 命令框. 第一个命令帧包含会话握手信息和一个零力 set_cursor_force 保持活动；每个后续帧都携带 仅 保持连接（已移除会话信息）。

Python

单个异步循环 — recv() → 构建命令 → send() → 重复。

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 在其专用的 I/O 线程上驱动 WebSocket —— 每帧处理机制位于 ws.onmessage. 主线程在 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)

与 nlohmann 变体采用相同的 libhv 回调模型——仅主体部分有所不同。Glaze 使用编译时反射：声明与 JSON 结构相对应的结构体，调用 glz::read / glz::write_json. std::optional<session_cmd> 启用单次握手；若未设置，Glaze 将从序列化的 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

命令行选项（Python）

该 Python 变体接受两个参数来更改教程的输出内容：

旗帜	效果
--full	将每个状态帧的原始 JSON 有效载荷以可读格式呈现，而非仅显示一行摘要。这有助于发现服务发出的字段。
--query-config	重新注入 session.force_render_full_state: {} 在每次出站请求时，该服务都会重新发送一个完整的快照（包括 config block — 设备类型、固件、预设、安装、滤波器等）在每个帧上。如果没有它， config 仅在第一个帧到达，后续帧均为增量流。

这两面旗帜结合在一起—— python 01-haply-inverse-print-inverse3.py --full --query-config 输出完整的 JSON 有效载荷，其中包含 config 在每个时间步长中都能看到，这在通过Haply 或 HTTP API 实时观察设置变化时非常方便。参见 session.force_render_full_state 用于底层的 WebSocket 命令。

C++ 版本不会显示这些标志——它们总是打印一行摘要，并接收 config 仅在第一帧。

随 SDK 安装程序一起发布

教程 01 也会随 SDK 一起安装在本地——请查看 tutorials/01-haply-inverse-print-inverse3/ 位于服务安装目录下。

来源： Python·C++·C++ Glaze

相关： WebSocket 协议 · 控制命令 (set_cursor_force) · 会话 · 类型 (vec3)