07. 베이스 & 마운트 플레이그라운드

디바이스의 마운트 변환을 대화형으로 제어하고, configure.basis, configure.preset, configure.mount와이어 프로토콜 수준에서 이 두 요소가 어떻게 함께 작동하는지 보여줍니다. 대화형 포커스가 configure 명령에 머물도록 수평 바닥을 고정합니다.

학습 내용:

• 기초 순열 설정 ("XZY" → Y축 위쪽 방향 (애플리케이션 프레임)
• 프리셋(arm_front) 선택 및 해당 프리셋이 구성하는 내용을 이해하기
• 회전 쿼터니언을 사용하여 런타임에 마운트 재정의 (키보드 입력 기반)
• 상호 배타 규칙: mount와 preset은과 같은 장치 구성 동일한 블록에 함께 존재할 수 없습니다
• 일회성 configure 동작: 키를 누를 때마다 configure 메시지가 정확히 한 번 전송됩니다.
• (C++ 글레이즈) std::optional을 이용한 상호 배타적 필드 모델링

워크플로우

1. 첫 메시지를 받으면 세션 프로필, configure.basis: "XZY", configure.preset: arm_front를 전송합니다. 고정 바닥용으로 set_cursor_force 전송을 시작합니다.
2. 매 틱마다 커서의 Y 값을 읽고 force_y = max(0, (floor_pos - y) * stiffness)를 계산하여 전송합니다.
3. 사용자가 마운트 회전 키를 누르면 pending_configure = true로 설정합니다.
4. 다음 틱에서 rotation이 단위 쿼터니언(현재 피치/요의 Z-then-X 합성)인 변환을 포함하는 configure.mount 블록을 구성합니다. preset은 생략합니다. 이 두 필드는 와이어 상에서 상호 배타적입니다.
5. 재설정 키(R)는 오버라이드를 해제합니다. 다음 configure 단계에서는 다시 preset을 사용합니다.

매개변수

이름	기본값	용도
BASIS	"XZY"	축 순열 — Y축 위쪽 방향 애플리케이션 프레임
DEVICE_PRESET / DEVICE_CONFIG_PRESET	"arm_front"	이름이 지정된 프리셋 — 원점은 장치 베이스
FLOOR_POS_Y	0.0 m	고정 바닥 평면 (애플리케이션 Y)
STIFFNESS	1000 해당 없음	바닥 스프링 상수
MOUNT_STEP_DEG	10°	키 입력당 회전 각도
PRINT_EVERY_MS	200	텔레메트리 스로틀

제어

키	동작
W / S	장치 + X축(피치) 기준 마운트를 ±10° 회전
A / D	장치를 Z축(요) 기준으로 ±10° 회전시켜 장착
R	마운트 재설정 — 사전 설정으로 되돌리기
H	제어 키 표시
Q	종료

mount와 preset은 서로 배타적입니다

이 서비스는 두 필드를 모두 포함하는 장치 구성 블록을 거부합니다. 사용자가 마운트를 재정의하면 튜토리얼은 이후의 모든 configure에서 preset을 생략합니다. R을 누르면 다음 configure에서 preset이것이 다시 사용되고 mount는 제외됩니다.

입력 모델의 차이

C++ 변형은 백그라운드 stdin 스레드에서 줄 단위로 입력을 읽습니다(문자를 입력할 때마다 Enter 키를 누릅니다). Python은 메인 비동기 루프에서 keyboard 이 패키지는 실시간 키 입력을 폴링하므로 ENTER 키를 누를 필요가 없습니다. 키와 명령은 동일합니다.

읽기 상태 필드

data.inverse3[i].state에서 읽은 값:

• cursor_position.y — vec3. 바닥 관통량을 계산하는 데 사용됩니다.
• current_cursor_force — 텔레메트리용으로 보고됩니다.

송신 / 수신

페이로드 구조는 모든 변형에서 동일합니다. 차이점은 각 변형이 서로 배타적이라는 점입니다. mount / preset 분기를 구성하는 방식과, 입력 스레드가 WebSocket 스레드에 신호를 보내는 방식입니다.

파이썬

단일 비동기 루프에서 keyboard 패키지를 통해 실시간 키 입력을 폴링합니다. pending_configure는 키 핸들러가 설정하는 전역 플래그이며, configure 블록이 전송될 때마다 초기화됩니다.

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"]
            # Handshake: profile + basis + preset
            request_msg = {
                "session": {"configure": {"profile": {"name": SLUG}}},
                "inverse3": [{
                    "device_id": device_id,
                    "configure": build_configure_block(first_handshake=True),
                    # -> {"basis": {"permutation": "XZY"},
                    #     "preset": {"preset": "arm_front"}}
                }],
            }
        else:
            handle_key_inputs()  # may set pending_configure = True (classic, not shown)

            y       = data["inverse3"][0]["state"]["cursor_position"]["y"]
            force_y = 0.0 if y > FLOOR_POS_Y else (FLOOR_POS_Y - y) * STIFFNESS

            entry = {
                "device_id": device_id,
                "commands": {"set_cursor_force":
                    {"vector": {"x": 0.0, "y": force_y, "z": 0.0}}},
            }
            if pending_configure:
                entry["configure"] = build_configure_block(first_handshake=False)
                # -> {"mount": {...}}   OR   {"preset": {...}}   (never both)
                pending_configure = False

            request_msg = {"inverse3": [entry]}

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

C++ (nlohmann)

이것은 두 스레드 모델입니다. 백그라운드 stdin 스레드가 줄을 읽고 pending_configure(std::atomic<bool>)를 설정하면, libhv I/O 스레드가 매 틱마다 이를 확인하여 값이 설정되어 있을 때 configure를 전송합니다.

std::atomic<bool> pending_configure{false};

ws.onmessage = [&](const std::string &msg) {
    const json data = json::parse(msg);
    if (!data.contains("inverse3") || data["inverse3"].empty()) return;

    const bool do_handshake = first_message;
    if (first_message) first_message = false;
    const bool do_configure = do_handshake || pending_configure.exchange(false);

    json request = {};
    if (do_handshake) {
        request["session"] = {{"configure", {{"profile",
            {{"name", "co.haply.inverse.tutorials:basis-and-mount"}}}}}};
    }

    request["inverse3"] = json::array();
    for (auto &el : data["inverse3"].items()) {
        json dev_cmd = {{"device_id", el.value()["device_id"]}};

        if (do_configure) {
            json cfg = {};
            if (do_handshake) cfg["basis"] = {{"permutation", BASIS}};
            if (mount_overridden) {
                cfg["mount"] = {{"transform", {
                    {"position", {{"x", 0.0}, {"y", 0.0}, {"z", 0.0}}},
                    {"rotation", quat_from_xz_deg(mount_angle_x_deg, mount_angle_z_deg)},
                    {"scale",    {{"x", 1.0}, {"y", 1.0}, {"z", 1.0}}},
                }}};
            } else {
                cfg["preset"] = {{"preset", DEVICE_CONFIG_PRESET}};
            }
            dev_cmd["configure"] = cfg;
        }

        const float y = el.value()["state"]["cursor_position"]["y"].get<float>();
        const float force_y = y > FLOOR_POS_Y ? 0.0f : (FLOOR_POS_Y - y) * STIFFNESS;
        dev_cmd["commands"] = {{"set_cursor_force",
            {{"vector", {{"x", 0.0}, {"y", force_y}, {"z", 0.0}}}}}};

        request["inverse3"].push_back(dev_cmd);
    }
    ws.send(request.dump());
};
std::thread input_thr(input_thread_func);  // stdin reader — flips pending_configure
ws.open("ws://localhost:10001");
while (running.load()) std::this_thread::sleep_for(50ms);

C++ (Glaze)

상호 배타 규칙은 std::optional<preset_cfg>와 std::optional<mount_cfg>로 자연스럽게 표현됩니다. 값이 입력된 항목만 직렬화된 JSON에 포함됩니다. 프리셋 이름은 enum class로 모델링하고, glz::meta 특수화를 사용하여 서비스가 요구하는 문자열과 매핑합니다.

// The preset set modelled as an enum
enum class device_preset {
    defaults, arm_front, arm_front_centered,
    led_front, led_front_centered, custom,
};

// Glaze meta — serialize the enum as the JSON string the service expects
template <> struct glz::meta<device_preset> {
    using enum device_preset;
    static constexpr auto value =
        enumerate(defaults, arm_front, arm_front_centered,
                  led_front, led_front_centered, custom);
};

// Transform + the configure block
struct vec3 { float x{}, y{}, z{}; };
struct quat { float w{1.0f}, x{}, y{}, z{}; };
struct transform_t { vec3 position{}; quat rotation{}; vec3 scale{1,1,1}; };

struct preset_cfg { device_preset preset; };
struct basis_cfg  { std::string permutation; };
struct mount_cfg  { transform_t transform; };
struct device_configure {
    std::optional<preset_cfg> preset;  // mutually exclusive with mount
    std::optional<basis_cfg>  basis;
    std::optional<mount_cfg>  mount;   // mutually exclusive with preset
};

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

    const bool do_handshake = first_message.exchange(false);
    const bool do_configure = do_handshake || pending_configure.exchange(false);

    commands_message out_cmds{};
    if (do_handshake) {
        out_cmds.session = session_cmd{ /* profile = basis-and-mount */ };
    }

    for (const auto &dev : data.inverse3) {
        device_commands dc{ .device_id = dev.device_id };

        if (do_configure) {
            device_configure cfg{};
            if (do_handshake) cfg.basis = basis_cfg{BASIS};
            if (mount_overridden) {
                cfg.mount = mount_cfg{ .transform = transform_t{
                    .rotation = quat_from_xz_deg(mount_angle_x_deg, mount_angle_z_deg)}};
            } else {
                cfg.preset = preset_cfg{DEVICE_CONFIG_PRESET};
            }
            dc.configure = std::move(cfg);
        }

        const float y = dev.state.cursor_position.y;
        const float force_y = y > FLOOR_POS_Y ? 0.0f : (FLOOR_POS_Y - y) * STIFFNESS;
        dc.commands.set_cursor_force = set_cursor_force_cmd{{0.0f, force_y, 0.0f}};
        out_cmds.inverse3.push_back(std::move(dc));
    }

    std::string out_json;
    (void)glz::write_json(out_cmds, out_json);
    ws.send(out_json);
};
std::thread input_thr(input_thread_func);
ws.open("ws://localhost:10001");
while (running.load()) std::this_thread::sleep_for(50ms);

SDK 설치 프로그램과 함께 제공됨

튜토리얼 07은 SDK와 함께 로컬에도 설치됩니다. 서비스 설치 디렉터리 아래의 tutorials/07-haply-inverse-basis-and-mount/에서 확인할 수 있습니다.

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

관련 항목: Basis 순열 · 마운트 및 작업 공간 · 장치 구성 · 제어 명령 (set_cursor_force) · 유형 (변환) · 튜토리얼 04 (Hello Floor)