02. VerseGrip 显示屏

持续显示来自首款有线VerseGrip的姿态（四元数+欧拉角Z-X-Y）、霍尔传感器电平以及按钮状态。

您将学到：

阅读指南 quaternion 基于状态图
将四元数转换为以度为单位的Z-X-Y欧拉角（+X向右，+Y向前，+Z向上）
使用 probe_orientation 作为维持自主观测器的信号
握手示例，仅在第一条消息中发送（与教程01中的示例相同）

流程

建立与……的 WebSocket 连接 ws://localhost:10001 并等待第一个状态帧。
请选择 device_id 表格中首个带线的VerseGrip verse_grip.
使用会话配置文件以及一个保持信号 probe_orientation 按设备（一个空对象命令，用于在状态帧中保持手柄的朝向流）。
发送请求，然后删除该字段 session : 这只是一次性的握手。
在每个后续帧中，将四元数转换为欧拉角，并以限速方式显示遥测数据。在每个周期中返回保持信号。

参数

Nom	默认值	角色
`URI`	`ws://localhost:10001`	WebSocket 模拟通道的 URL
`PRINT_EVERY_MS`	`100`	控制台显示的刷新率限制
会话配置文件名称	`co.haply.inverse.tutorials:print-verse-grip`	在Haply Hub中识别此模拟

欧拉公约

转换是在映射坐标系中进行的Z-X-Y方向（横滚→俯仰→滚转）的固有旋转。 +X right, +Y forward, +Z up. 请勿使用 glm::eulerAngles ：该函数遵循另一种约定，在此处会返回错误的值。这三种语言版本都实现了相同的计算；请查阅源代码以了解计算公式。

Quand probe_orientation 确实有必要

probe_orientation 只有当您的会话 不发送任何 向Inverse3 发送指令。一旦您向Inverse3 发送指令（力、位置、扭矩等），该服务会自动在每个状态帧中广播相应的VerseGrip方向：无需发送保持信号。请使用 probe_orientation 仅适用于本教程中介绍的此类独立式手柄追踪工具。

阅读过的州冠军

自 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. 第一条传出消息包含会话配置文件；随后的每帧仅包含保持信号。

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（无线视频游戏）

流程​

参数​

阅读过的州冠军​

发送/接收​

命令行选项（Python）​

流程

参数

阅读过的州冠军

发送/接收

命令行选项（Python）