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 创建一个包含“Keep Alive”（通过空对象命令，使抓手姿态持续流向状态帧）的请求。
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 在实际需要的情况下

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

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