01. 输出Inverse3

连接到WebSocket 模拟，并实时传输服务报告的首个Inverse3 的光标位置、速度和力度。

学习内容：

• 建立 WebSocket 连接并接收初始完整状态消息
• 通过……发送一个强度为零的Keepalive set_cursor_force, 以便保持会话处于活动状态
• 注册会话配置文件，以便Haply Hub 识别您的仿真
• 第一条消息的握手模式——在首次发送后移除 session/configure
• 读取工作区-transform （位置、旋转、缩放）及其部分更新的语义
• 将控制台输出限制在易于阅读的速率

流程

1. 通过 WebSocket 连接到 ws://localhost:10001. 该服务会立即发送一个 全状态帧 与已连接的设备。
2. 在第一帧中，请选择 device_id 从第一个Inverse3 开始，并编写一条包含两部分的查询消息：
   • session.configure.profile.name — 在以下处注册该模拟： Haply Hub.
   • 一个特定于设备的命令 set_cursor_force 使用一个零向量。该服务将其用作保持活动机制——只要继续收到命令，它就会持续发送状态帧。
3. 请将该消息发回。 删除该字段 session 在下一个时槽之前——会话配置文件是一次性的握手；后续时槽仅发送命令。
4. 在每个后续的状态帧中，请填写光标字段 vec3 (位置、速度、力)，将其采样率降至约10 Hz，然后再次发送力值为零的保持活动信号。

参数

名称	标准值	Zweck
URI	ws://localhost:10001	模拟频道的 WebSocket URL
PRINT_EVERY_MS	100	限制主机输出
会话配置文件名称	co.haply.inverse.tutorials:print-inverse3	在Haply Hub中识别此模拟

已读取的状态字段

Aus 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; 每个后续帧包含 nur 保持连接（会话将被清除）。

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 ……主线程仅会阻塞，直到按下回车键为止。

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 auf. 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: {} ein，以便该服务在每个帧中重新输出一个完整的快照（包括 config-模块 — 设备类型、固件、预设、支架、滤波器、……）。如果不设置此标志，则 config 仅在第一个帧中传输；后续帧均为流式增量数据。

这两种旗帜可以组合使用—— python 01-haply-inverse-print-inverse3.py --full --query-config 返回一个完整的 JSON 有效载荷，其中 config 在每个周期中都可见。当您实时跟踪通过Haply Hub或HTTP API进行的设置更改时，此功能非常实用。参见 session.force_render_full_state 用于相应的 WebSocket 命令。

C++ 的变体不提供这些标志——它们总是输出单行摘要，并返回 config 仅在第一帧中。

包含在 SDK 安装程序中

此外，教程 01 已随 SDK 一起本地安装——请在该服务的安装目录下查看 tutorials/01-haply-inverse-print-inverse3/ nach.

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

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