01. Inverse3的输出

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

学习内容：

• 建立 WebSocket 连接，并接收初始的完整状态消息
• 零力set_cursor_force发送“Keep-Alive”请求，以保持会话持续运行
• Haply 注册会话配置文件，以便集线器能够识别模拟
• 仅通过首条消息完成握手的方式——在首次发送后移除 session/configure
• 在部分更新的语义中，工作区的 transform读取（位置、旋转、缩放）
• 将控制台输出控制在易于阅读的频率内

工作流

1. ws://localhost:10001 建立 WebSocket 连接。该服务会立即列出已连接的设备列表完好无损的车架将发送。
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 在Hub内识别此模拟

读取状态字段

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}）与之相等的子字段，为了节省带宽，将从有效载荷中省略。读取时请务必指定默认值（例如：在 C++ 中 .value("position", default_pos)、在Python中 .get("position", default_pos)）。若要始终接收所有字段，请serialization/explicit_fields请启用该功能。

收发

在 WebSocket 循环中，接收状态帧，命令帧将其创建并发送回去。在第一个命令帧中，包含会话握手和零力set_cursor_force包含“Keep Alive”。后续帧中仅限“Keep Alive”包含（会话将被移除）。

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	在每个要发送的Tick中 session.force_render_full_state: {} 并添加，使服务在每一帧生成完整的快照（config 块——包括设备类型、固件、预设、挂载、滤波器等——将重新发送。如果没有此标志，config 仅在第一个帧中发送，后续帧则采用流式传输的增量更新方式。

这两个标志可以结合使用。python 01-haply-inverse-print-inverse3.py --full --query-config 执行后，每帧 config 将输出显示的完整 JSON 有效载荷。这在通过Haply Hub 或 HTTP API 实时查看配置更改时非常有用。关于基础的 WebSocket 命令，请参阅：session.force_render_full_state 请参阅。

在 C++ 变体中，不提供这些标志。始终输出一行摘要，config 仅在第一个帧中接收。

随SDK安装程序一起提供

教程01也已随SDK一起安装在本地。位于服务安装目录下的 tutorials/01-haply-inverse-print-inverse3/ 请确认。

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

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