06. 集成示例（Inverse3 + 无线 VerseGrip）

这是一个使用两台设备的教程。将手柄朝向所需方向，并按住按钮不放，光标就会沿该方向移动Inverse3 。光标移动范围仅限于球形工作区内部。

学习内容：

• 在同一状态帧中读取两种设备类型（inverse3 以及 wireless_verse_grip)
• 四元数从（局部）中提取握柄所指的方向 +Y 祝)
• set_cursor_position将光标移动到使用……计算出的目标位置
• 将目标点限制在安全工作区域内 — Minverse 使用的半径比 Inverse3 小
• 使原点位于覆盖范围的中心 工作区预设 (arm_front_centered) 设置

工作流程

1. 搜索两台设备：
   • C++ 版本信息在启动时通过 HTTP 获取 GET /devices查询后，显示校准提示信息，并等待按下ENTER键。
   • Python会在第一个 WebSocket 状态帧中读取两个设备 ID。
2. 在第一条消息中 会话配置文件注册并 configure.preset: arm_front_centered进行设置（一次性握手）。
3. 每次击球时，握杆的 orientation 以及 buttons.{a, b} 读取状态。
4. 如果按住移动按钮，握把在世界坐标系中的方向（R(q) · ĵ —计算（沿+Y轴旋转的单元），并将该结果 SPEED按比例缩放后，累积到目标位置。
5. 将目标点限定在工作区范围内后 set_cursor_position通过……进行传输。
6. （仅适用于 Python）设备的 config.type根据……调整圆的半径 — minverse为 0.04 米，其余均为 0.10 米。

参数

姓名	默认值	用途
SPEED	0.01 m/tik	按住按钮期间的移动间隔
RADIUS_INVERSE3	0.10 m	Inverse3 / Inverse3x 的工作区限制半径
RADIUS_MINVERSE	0.04 m	Minverse 的工作区限制半径（仅适用于 Python — C++ 则 0.10（固定为）
PRINT_EVERY_MS	200	遥测输出周期限制
会话配置文件名称	co.haply.inverse.tutorials:combined	Haply 在 Hub 中用于识别此模拟的值

运行前进行校准

• 让Inverse3自动进行校准（或者将笔身放在墨水瓶上方，等待LED指示灯亮起）。
• 请将笔杆从墨水瓶上取下。
• 按住 A 或 B 键的同时旋转手柄——光标将沿着手柄指向的方向移动。

“正在阅读”字段

从每个 tick 传递的状态帧中读取以下值：

• data.inverse3[0].state.cursor_position — vec3
• data.wireless_verse_grip[0].state.orientation — quaternion
• data.wireless_verse_grip[0].state.buttons.{a, b, c} — 布尔值
• （Python，仅在第一个帧中） data.inverse3[0].config.type — 请选择 Inverse3 或Minverse 中的一个
• （Python，仅在第一个帧中） data.inverse3[0].status.calibrated — 如果值为 false，则向用户发出提示

发送 / 接收

四元数中求方向的计算（R(q)到 +Y（旋转运算）和球体内部限制处理是典型的线性代数运算。详情请参阅源文件。Inverse API 方面会在每次握手和每次时钟周期调用 set_cursor_position由……组成。

Python

由单个异步循环组成。Python 在第一个状态帧中读取两个设备 ID。在握手过程中，第一个 set_cursor_position 在调用中包含个人资料和 configure.preset: arm_front_centered随信附上。

async with websockets.connect(URI) as websocket:
    while True:
        msg  = await websocket.recv()
        data = json.loads(msg)

        if first_message:
            first_message = False
            inverse3_id = data["inverse3"][0]["device_id"]
            grip_id     = data["wireless_verse_grip"][0]["device_id"]
            radius      = get_workspace_radius(data["inverse3"][0].get("config", {}))

            # Handshake: profile + preset + first position command
            request_msg = {
                "session": {"configure": {"profile": {"name": SLUG}}},
                "inverse3": [{
                    "device_id": inverse3_id,
                    "configure": {"preset": {"preset": "arm_front_centered"}},
                    "commands": {"set_cursor_position": {"position": position}},
                }],
            }
        else:
            # Per tick: update position from grip pointing direction (classic math, not shown), send
            request_msg = {
                "inverse3": [{
                    "device_id": inverse3_id,
                    "commands": {"set_cursor_position": {"position": position}},
                }],
            }

        await websocket.send(json.dumps(request_msg))

C++ (nlohmann)

C++在启动时 GET /devices通过（HTTP）获取两台设备的ID后，打开WebSocket连接。 onmessage在 libhv 的 I/O 线程中运行，主线程将阻塞直至接收到 ENTER 键输入。

// Startup (synchronous):
const std::string inv3_device_id = get_first_device_id("inverse3");
const std::string grip_device_id = get_first_device_id("wireless_verse_grip");

// Per tick:
ws.onmessage = [&](const std::string &msg) {
    json data = json::parse(msg);
    // ... classic math (not shown): update local Inverse3State + WirelessVerseGripState,
    //     compute new position from grip orientation, clamp to sphere ...

    json command;
    command["inverse3"] = json::array();
    command["inverse3"].push_back({
        {"device_id", inv3_device_id},
        {"commands", {{"set_cursor_position",
            {{"position", {{"x", pos.x}, {"y", pos.y}, {"z", pos.z}}}}}}}
    });

    if (first_message) {
        first_message = false;
        command["session"] = {{"configure", {{"profile",
            {{"name", "co.haply.inverse.tutorials:combined"}}}}}};
        command["inverse3"][0]["configure"] = {
            {"preset", {{"preset", "arm_front_centered"}}}};
    }

    ws.send(command.dump());
};
ws.open("ws://localhost:10001");
while (std::cin.get() != '\n') {}  // block main thread

C++ (Glaze)

libhv 的回调模型与此相同。它使用带类型的结构体（typed struct）来建模状态帧和发送命令。 devices_message 里面的两个 std::vector<> 多亏了……单一 glz::read 通过该调用可以获取这两种设备类型。

// 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{}; };
struct wvg_device { std::string device_id; wvg_state state; };

struct inverse_state { vec3 cursor_position{}, cursor_velocity{}; };
struct inverse_device { std::string device_id; inverse_state state; };

struct devices_message {
    std::vector<inverse_device> inverse3;
    std::vector<wvg_device> wireless_verse_grip;
};

struct set_cursor_position_cmd { vec3 position; };
struct commands_message {
    std::optional<session_cmd> session;
    std::vector<device_commands> inverse3;
};

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

    const auto &wvg = data.wireless_verse_grip[0].state;
    cursor_pos = data.inverse3[0].state.cursor_position;
    // ... classic math (not shown): if (wvg.buttons.a || wvg.buttons.b)
    //     move in pointing dir; clamp to sphere ...

    commands_message out_cmds{};
    device_commands dc{ .device_id = inv3_device_id };
    dc.commands.set_cursor_position = set_cursor_position_cmd{cursor_pos};

    if (first_message) {
        first_message = false;
        out_cmds.session = session_cmd{ /* profile = combined */ };
        dc.configure = device_configure{ .preset = preset_cfg{"arm_front_centered"} };
    }
    out_cmds.inverse3.push_back(std::move(dc));

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

包含在 SDK 安装程序中

教程 06 会随 SDK 一起安装到本地 — 位于服务安装目录下的 tutorials/06-haply-inverse-combined/ 您可以在该文件夹中查看。

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

相关条目： 控制命令 (set_cursor_position) · 类型 (四元数, vec3) · 安装与工作区（预设） · 教程 03（无线 VG） · 教程 05（位置控制）