02. 打印 VerseGrip

从首个有线 VerseGrip 实时输出姿态（四元数+ Z-X-Y 欧拉角）、霍尔传感器电平以及按键状态。

学习内容：

• 从状态帧中读取 quaternion 姿态
• 将四元数转换为以度为单位的 Z-X-Y 欧拉角（+X 表示右，+Y 表示前，+Z 表示上）
• 将 probe_orientation 用作独立观察者的保活命令
• 仅首条消息需要握手模式（与教程 01相同）

工作流程

1. 打开指向 ws://localhost:10001 的 WebSocket，并等待第一个状态帧。
2. 从 verse_grip 从数组中选取第一个带有线VerseGrip的 device_id。
3. 使用 会话配置 以及针对每台设备的 probe_orientation 构建保活命令请求（这是一个空对象命令，用于确保握持姿态数据持续出现在状态帧中）。
4. 发送请求，然后取消 session 字段——它仅用于一次性握手。
5. 随后每一帧都会将四元数转换为欧拉角，并以限流方式打印遥测数据。每个周期都会重新发送心跳命令。

参数

名称	默认值	用途
URI	ws://localhost:10001	WebSocket 仿真通道的 URL
PRINT_EVERY_MS	100	控制台输出节流间隔
会话配置名称	co.haply.inverse.tutorials:print-verse-grip	用于在Haply Hub中标识本次仿真

欧拉角约定

转换采用应用坐标系 +X right, +Y forward, +Z up 向下的内旋，顺序为 Z-X-Y（偏航 → 俯仰 → 横滚）。请勿使用 glm::eulerAngles——它遵循不同的约定，因此会得到错误的结果。三种语言版本实现的数学计算结果相同，具体公式请参阅源代码。

何时需要 probe_orientation

只有当会话未向Inverse3 发送任何命令时，probe_orientation 才有用。一旦你向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

单个异步循环——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

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["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

C++ (Glaze)

沿用相同的 libhv 回调模型。强类型结构体取代了 nlohmann::json——probe_orientation_cmd 空结构体（Glaze 将其写为 {}）。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）