《VerseGrip》第02期

实时传输第一个有线 VerseGrip 的方向数据（四元数+ Z-X-Y 欧拉角）、霍尔传感器读数以及按键状态。

您将学到：

Die quaternion- 从状态帧中读取方向
将一个以Z-X-Y欧拉角表示的四元数转换为以度为单位的坐标系（+X在右侧，+Y在前方，+Z在上方）
probe_orientation 将 als 用作独立观察者的保持活动机制
仅在第一条消息中使用的握手模式（如教程 01 所示）

流程

建立与的 WebSocket 连接 ws://localhost:10001 然后等待第一个状态帧。
请选择 device_id 来自该阵列的首款有线VerseGrip verse_grip.
请使用以下方式提交请求：会议简介以及一个设备专用的 probe_orientation-Keepalive（一个带有空对象的命令，用于确保在状态帧中持续传输手柄方向）。
提交请求后，请取消勾选该复选框 session — 这是一种一次性握手。
在每个后续帧中，将四元数转换为欧拉角，并输出经过限速处理的遥测数据。在每个循环中重新发送保持活动信号。

参数

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

欧拉约定

该转换是在应用程序坐标系中进行的内在 Z-X-Y 旋转（偏航 → 俯仰 → 滚转） +X right, +Y forward, +Z up. 请勿使用 glm::eulerAngles — 它遵循另一种约定，因此在此处返回了错误的值。这三种语言变体都实现了相同的数学运算；您可以在源代码中找到该公式。

Wann probe_orientation 实际上确实需要

probe_orientation 只有当您的会话 keinen 向Inverse3 发送命令。一旦您通过命令（力、位置、扭矩等）控制Inverse3 ，该服务就会在每个状态帧中自动流式传输已配对的 VerseGrip 的姿态——此时无需进行采样。请使用 probe_orientation 仅适用于像本教程中这样的独立手柄监控工具。

已读取的状态字段

Aus data.verse_grip[0].state:

orientation — quaternion (w, x, y, z)
hall — 整数霍尔传感器值
button — 布尔值
transform.rotation — 工作区旋转 (quaternion); 对于仅能检测方向的设备，位置和缩放不适用，因此永远不会输出

部分更新中的语义

transform.rotation 如果它与身份四元数 {w:1,x:0,y:0,z:0} 与……相对应。阅读时请设定一个默认值。启用 serialization/explicit_fields，以确保它总能被传输出去。

发送 / 接收

WebSocket 循环接收一个状态帧，建立握手并创建 probe_orientation- 发送保持活动（Keepalive）数据包并将其发回。第一个发出的数据包包含会话配置文件；此后每个帧仅包含保持活动数据包。

Python
C++ (nlohmann)
C++ (Glaze)

单个异步循环 — 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["verse_grip"][0]["device_id"]
            request_msg = {
                "session": {"configure": {"profile": {
                    "name": "co.haply.inverse.tutorials:print-verse-grip"}}},
                "verse_grip": [{
                    "device_id": device_id,
                    "commands": {"probe_orientation": {}}  # empty — keepalive
                }]
            }

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

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["verse_grip"][0].at("device_id").get<std::string>();
        request_msg = {
            {"session", {{"configure", {{"profile",
                {{"name", "co.haply.inverse.tutorials:print-versegrip"}}}}}}},
            {"verse_grip", json::array({
                {{"device_id", device_id},
                 {"commands", {{"probe_orientation", json::object()}}}},
            })},
        };
    }

    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

相同的 libhv 回调模型。用类型化结构替换 nlohmann::json — probe_orientation_cmd 是一个空结构（格莱兹将其写为 {}). std::optional<session_cmd> 负责处理一次性的握手过程： .reset() 在首次发送后，后续输出的 JSON 中将省略该字段。

// Struct models
struct quat { float w{1.0f}, x{}, y{}, z{}; };
struct grip_state { quat orientation{}; bool button{}; uint8_t hall{}; };
struct grip_device { std::string device_id; grip_state state; };
struct devices_message { std::vector<grip_device> verse_grip; };

struct probe_orientation_cmd {};  // empty object on the wire
struct commands_message {
    std::optional<session_cmd> session;  // one-shot — omitted when unset
    std::vector<device_commands> verse_grip;
};

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

    if (first_message) {
        first_message = false;
        out_cmds.session = session_cmd{ /* profile = print-versegrip */ };
        device_commands dc{ .device_id = data.verse_grip[0].device_id };
        dc.commands.probe_orientation = probe_orientation_cmd{};
        out_cmds.verse_grip.push_back(std::move(dc));
    }

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

命令行选项（Python）

Python 版本支持与教程 01 相同的两个标志：

--full — 输出经过格式化的原始 JSON 有效载荷，而不是单行摘要。
--query-config — 在每个结束小节处添加 session.force_render_full_state 再次添加，使得每个帧都包含 config-包含“块”（设备类型、固件、安装转换……），而不仅仅是状态变化。这对于在运行过程中调试设置更改非常有用。

这两个标志可以组合使用。C++ 版本不提供这些标志。

包含在 SDK 安装程序中

教程 02 也会随 SDK 一起本地安装——您可以在以下位置找到它： tutorials/02-haply-inverse-print-verse-grip/ 位于该服务的安装目录中。

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

另见： 类型（四元数） · 控制命令 (probe_orientation) · WebSocket 协议 · 教程 03（无线 VG）

流程​

参数​

已读取的状态字段​

发送 / 接收​

命令行选项（Python）​

流程

参数

已读取的状态字段

发送 / 接收

命令行选项（Python）