02. VerseGrip 출력

첫 번째 유선 VerseGrip에서 방향(쿼터니언 + Z-X-Y 오일러 각), 홀 센서 레벨, 버튼 상태를 스트리밍합니다.

학습 내용:

• 상태 프레임에서 quaternion 방향 읽기
• 쿼터니언을 도 단위의 Z-X-Y 오일러 각으로 변환하기 (+X 오른쪽, +Y 앞쪽, +Z 위쪽)
• probe_orientation을 단독 옵저버용 keepalive로 사용하기
• 첫 메시지에만 보내는 핸드셰이크 패턴 (튜토리얼 01과 동일)

워크플로

1. ws://localhost:10001로 WebSocket를 열고 첫 번째 상태 프레임을 기다립니다.
2. verse_grip 배열에서 첫 번째 유선 VerseGrip의 device_id를 선택합니다.
3. 세션 프로필과 디바이스별 probe_orientation keepalive를 포함한 요청을 만듭니다(상태 프레임에서 그립 방향 데이터가 계속 전달되도록 하는 빈 객체 명령).
4. 요청을 전송한 뒤 session 필드를 제거합니다. 이 필드는 일회성 핸드셰이크용입니다.
5. 이후 모든 프레임에서 쿼터니언을 오일러 각으로 변환하고 스로틀된 텔레메트리를 출력합니다. 매 틱마다 keepalive를 다시 보냅니다.

매개변수

이름	기본값	용도
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에서 내재(intrinsic) Z-X-Y(yaw → pitch → roll) 방식입니다. 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 keepalive를 구성하여 다시 송신합니다. 첫 번째 송신 메시지에는 세션 프로필이 포함되며, 이후 모든 프레임에는 keepalive만 포함됩니다.

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

관련: 타입 (quaternion) · 제어 명령 (probe_orientation) · WebSocket 프로토콜 · 튜토리얼 03 (Wireless VG)