03. 打印无线 VerseGrip

与教程 02模式相同，但适用于无线 VerseGrip——在流式状态中增加了按钮（A/B/C）和电池电量。

你将学到：

• 读取无线设备特有的状态字段：buttons.{a,b,c}、battery_level、hall
• 将 probe_orientation 用作独立观察者的保活机制
• 与教程 02相同的仅首条消息握手模式

工作流程

1. 打开到 ws://localhost:10001 的 WebSocket，并等待第一个状态帧。
2. 从 wireless_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-wireless-verse-grip	在 Haply Hub 中标识此仿真

欧拉角约定

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

何时真正需要 probe_orientation

probe_orientation 仅在你的会话没有向 Inverse3 发送任何指令时才有用。一旦你向 Inverse3 下达指令（力、位置、扭矩等），服务便会在每个状态帧中自动推送配对的 VerseGrip 方向数据——无需探测。仅在本教程这类独立抓取监控工具中使用 probe_orientation。

读取的状态字段

来自 data.wireless_verse_grip[0].state：

• orientation — quaternion（w, x, y, z）
• hall — 整数型霍尔传感器读数
• buttons.a、buttons.b、buttons.c — 布尔值
• battery_level — 浮点数（0.0 – 1.0）
• transform.rotation — 工作空间旋转（quaternion）；位置和缩放对于仅有方向的设备不适用，因此从不输出

部分更新语义

当 transform.rotation 等于单位四元数 {w:1,x:0,y:0,z:0} 时，该字段会被省略。读取时请提供默认值。启用 serialization/explicit_fields 可始终接收该字段。

发送 / 接收

与教程 02的结构相同，只是使用 wireless_verse_grip 设备数组。WebSocket 循环接收状态帧，并回传握手信息及 probe_orientation 保活指令；第一条发出的消息携带会话配置文件，之后的每一帧仅携带保活指令。

Python

单一异步循环。

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["wireless_verse_grip"][0]["device_id"]
            request_msg = {
                "session": {"configure": {"profile": {
                    "name": "co.haply.inverse.tutorials:print-wireless-verse-grip"}}},
                "wireless_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)

ws.onmessage = [&](const std::string &msg) {
    const json data = json::parse(msg);

    if (first_message) {
        first_message = false;
        device_id = data["wireless_verse_grip"][0].at("device_id").get<std::string>();
        request_msg = {
            {"session", {{"configure", {{"profile",
                {{"name", "co.haply.inverse.tutorials:print-wireless-verse-grip"}}}}}}},
            {"wireless_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)

强类型结构体。注意 button_state 是显式命名的（而非 buttons），以避免遮蔽 wvg_state 上的 buttons 字段——Glaze 按名称映射字段，因此结构体的类型名称可以任意指定。

// Struct models
struct quat { float w{1.0f}, x{}, y{}, z{}; };
struct button_state { bool a{}, b{}, c{}; };
struct wvg_state {
    quat orientation{};
    uint8_t hall{};
    button_state buttons{};
    float battery_level{};
};
struct wvg_device { std::string device_id; wvg_state state; };
struct devices_message { std::vector<wvg_device> wireless_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> wireless_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;
        request_msg.session = session_cmd{ /* profile = print-wireless-verse-grip */ };
        device_commands dc{ .device_id = data.wireless_verse_grip[0].device_id };
        dc.commands.probe_orientation = probe_orientation_cmd{};
        request_msg.wireless_verse_grip.push_back(std::move(dc));
    }

    std::string out_json;
    (void)glz::write_json(request_msg, out_json);
    ws.send(out_json);
    request_msg.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 块，而不仅仅是状态增量。

--query-config 对于无线 VerseGrip 尤其有用，因为 config 块除常规配置字段外，还包含 WVG 专用的 sub_type 字段（stylus / prototype / ruko / kingfisher，3.5 版本新增）。运行 python 03-haply-inverse-print-wireless-verse-grip.py --full --query-config 可以实时观察 config.sub_type 与其他配置值一同更新。

C++ 版本不提供这些参数。

随 SDK 安装程序提供

教程 03 也随 SDK 一同安装在本地——请在服务安装目录下的 tutorials/03-haply-inverse-print-wireless-verse-grip/ 中查找。

源代码： Python · C++ · C++ Glaze

相关内容： 教程 02（有线 VG） · 类型（四元数） · 控制指令（probe_orientation） · WebSocket 协议