01. Inverse3의 출력

시뮬레이션 WebSocket에연결하여, 서비스가 보고하는 첫 번째 Inverse3 데이터부터 커서의 위치, 속도 및 힘을 스트리밍합니다.

학습 내용:

• WebSocket 연결을 열고, 초기 완전 상태 메시지를 수신하는 것
• 제로력의set_cursor_force‘Keep-Alive’를 전송하여 세션을 계속 유지하기
• Haply 허브가 시뮬레이션을 인식할 수 있도록세션 프로필을등록해야 합니다.
• 첫 번째 메시지만으로 핸드셰이크를 수행하는 방식 — 첫 번째 전송 후 session/configure를 제거해야 함
• 부분 업데이트의 의미론에 따라, 워크스페이스의 transform(위치, 회전, 크기)를 읽어들이기
• 콘솔 출력을 읽기 쉬운 빈도로 제한하는 것

워크플로우

1. ws://localhost:10001 WebSocket 연결을 엽니다. 서비스는 즉시 연결된 기기 목록을 표시합니다.완벽한 상태의 프레임보냅니다.
2. 첫 번째 프레임에서, 첫 번째 Inverse3의 device_id 을 가져와 두 부분으로 구성된 요청 메시지를 생성합니다:
   • session.configure.profile.name — 시뮬레이션을Haply Hub에 등록합니다.
   • 제로 벡터를 지정한, 기기별set_cursor_force명령어. 서비스는 이를 키프얼라이브(keep-alive)로 사용합니다. 명령어가 계속 수신되는 한, 상태 프레임을 계속 전송합니다.
3. 메시지를 다시 보내드리겠습니다.다음 틱이 발생하기 전에 session 필드를 제거해 주세요. 세션 프로파일은 일회성 핸드셰이크이며, 이후의 틱에서는 명령어만 전송합니다.
4. 이후의 각 상태 프레임마다, 커서의vec3필드(위치, 속도, 힘)를 약 10 Hz로 제한하여 출력하고, 제로 힘 키프-얼라이브 신호를 재전송합니다.

매개변수

이름	기본값	용도
URI	ws://localhost:10001	시뮬레이션 채널 WebSocket URL
PRINT_EVERY_MS	100	콘솔 출력 억제 간격
세션 프로필 이름	co.haply.inverse.tutorials:print-inverse3	Haply 허브 내에서 이 시뮬레이션을 식별합니다

읽기 전용 상태 필드

data.inverse3[0].state 다음 내용을 읽어옵니다:

• cursor_position、cursor_velocity、current_cursor_force — 모두vec3
• transform — 워크스페이스 변환. 하위 객체로 position(vec3),rotation(quaternion),scale(vec3)를 가지고 있습니다

부분 업데이트의 의미론

항등원(단위원)의 기본값(position: {0,0,0}、rotation: {w:1,x:0,y:0,z:0}、scale: {1,1,1})와 동일한 서브필드는 대역폭을 절약하기 위해 페이로드에서생략됩니다. 읽기 시에는 반드시 기본값을 지정해 주십시오(예: C++에서는 .value("position", default_pos)、파이썬에서는 .get("position", default_pos)). 모든 필드를 항상 수신하려면,serialization/explicit_fields을 활성화해 주십시오.

송수신

WebSocket 루프에서는 상태 프레임을 수신하고,명령 프레임만들어 다시 보냅니다. 첫 번째 명령 프레임에는 세션 핸드셰이크와 제로 포스의set_cursor_force‘KeepAlive’가 포함됩니다. 이후 프레임에는‘Keep Alive’만이 포함됩니다(세션은 제외됩니다).

파이썬

단일 비동기 루프입니다 — 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["inverse3"][0]["device_id"]
            request_msg = {
                "session": {"configure": {"profile": {
                    "name": "co.haply.inverse.tutorials:print-inverse3"}}},
                "inverse3": [{
                    "device_id": device_id,
                    "commands": {"set_cursor_force":
                        {"vector": {"x": 0.0, "y": 0.0, "z": 0.0}}},
                }]
            }

        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["inverse3"][0].at("device_id").get<std::string>();
        request_msg = {
            {"session", {{"configure", {{"profile",
                {{"name", "co.haply.inverse.tutorials:print-inverse3"}}}}}}},
            {"inverse3", json::array({
                {{"device_id", device_id},
                 {"commands", {{"set_cursor_force",
                   {{"vector", {{"x", 0.0}, {"y", 0.0}, {"z", 0.0}}}}}}}},
            })},
        };
    }

    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)

nlohmann 변종과 동일한 libhv의 콜백 모델입니다. 달라지는 부분은 본체 부분뿐입니다. Glaze는 컴파일 시 리플렉션을 사용합니다. JSON의 구조를 반영한 구조체를 선언하고,glz::read / glz::write_json 를 호출합니다.std::optional<session_cmd> 한 번만 이루어지는 핸드셰이크를 유지합니다. 설정되지 않은 경우, Glaze는 직렬화된 JSON에서 해당 필드를 생략합니다.

// Struct models
struct vec3 { float x{}, y{}, z{}; };
struct inverse_state {
    vec3 cursor_position{}, cursor_velocity{}, current_cursor_force{};
    /* + body_orientation, angular_position, angular_velocity */
};
struct inverse_device { std::string device_id; inverse_state state; };
struct devices_message { std::vector<inverse_device> inverse3; };

struct set_cursor_force_cmd { vec3 vector; };
struct commands_message {
    std::optional<session_cmd> session;  // omitted from JSON when unset
    std::vector<device_commands> inverse3;
};

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

    commands_message out_cmds{};
    if (first_message) {
        first_message = false;
        out_cmds.session = session_cmd{ /* profile = print-inverse3 */ };
    }
    // ... populate out_cmds.inverse3 with zero-force keepalive ...

    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

명령줄 플래그 (Python)

Python 변형에서는 튜토리얼의 출력 결과를 변경하는 두 가지 플래그를 지정할 수 있습니다.

플래그	효과
--full	한 줄로 요약하는 것이 아니라, 각 상태 프레임의 원본 JSON 페이로드를 정리하여 출력합니다. 서비스가 전송하는 필드를 확인할 때 유용합니다.
--query-config	각 티크를 전송할 때마다 session.force_render_full_state: {} 을 추가하여, 서비스가 매 프레임마다 완전한 스냅샷(config 블록(장치 유형, 펌웨어, 프리셋, 마운트, 필터 등 포함)을 다시 전송하도록 합니다. 이 플래그가 없는 경우,config 는 첫 번째 프레임에서만 전송되며, 그 이후의 프레임은 스트리밍의 차분 데이터로 전송됩니다.

두 플래그를 함께 사용할 수 있습니다.python 01-haply-inverse-print-inverse3.py --full --query-config 이 명령을 실행하면 매 틱마다 config 표시된 전체 JSON 페이로드가 출력됩니다. 이는Haply Hub 또는 HTTP API를 통해 설정 변경 사항을 실시간으로 확인할 때 유용합니다. 기본이 되는 WebSocket 명령어에 대해서는,session.force_render_full_state 를 참조하십시오.

C++ 변형에서는 이러한 플래그가 제공되지 않습니다. 항상 한 줄의 요약을 출력하며,config 는 첫 번째 프레임에서만 수신합니다.

SDK 설치 프로그램에 포함되어 있음

튜토리얼 01도 SDK와 함께 로컬에 설치되어 있습니다. 서비스의 설치 디렉터리 아래에 있는 tutorials/01-haply-inverse-print-inverse3/ 확인해 주십시오.

출처: Python · C++ · C++ Glaze

관련: WebSocket 프로토콜 · 제어 명령어（set_cursor_force) · 세션 · 형(vec3)