Haply Inverse SDK

Le Haply Inverse SDK 는 햅틱 기기 Haply 를 위한 WebSocket + HTTP 기반의 언어 독립적 인터페이스입니다 — Inverse3, Inverse3x, Minverse, VerseGrip 및 Wireless VerseGrip과 같은 햅틱 기기를 위한 웹소켓(WebSocket) + HTTP 기반의 언어 독립적 인터페이스입니다[email protected]. 이 인터페이스는 로컬 서비스로 실행되며, 기기 탐색, 시리얼 통신, 보안 모니터링 및 상태 전파를 처리하므로, 애플리케이션은 소켓을 통해 JSON으로만 통신하면 됩니다.

주요 기능은 다음과 같습니다:

• 기기 탐색 및 관리 — REST HTTP API를 통해 연결된 기기를 자동으로 식별하고 구성합니다 Haply .
• 실시간 상태 전송 — WebSockets를 통해 햅틱 제어 주파수(수 kHz)로 기기의 상태를 전송합니다.
• 명령 처리 — 정밀한 햅틱 피드백을 제공하기 위해 힘 및 위치 명령을 높은 정확도로 실행합니다.
• 백그라운드에서 작동 — 로컬 서비스로 실행되며, 사용자의 개입 없이 기기를 항상 사용 가능한 상태로 유지합니다.

Haply 허브를 사용한 설치

시작하는 가장 간단한 방법은 Haply Hub를 사용하는 것입니다. Hub는 기기를 설치, 실행, 구성, 테스트 및 모니터링할 수 있는 데스크톱 애플리케이션입니다( Haply). 이 애플리케이션은 펌웨어를 최신 상태로 유지하고, Inverse Service를 통합하며, 코드를 한 줄도 작성하기 전에 하드웨어를 확인할 수 있는 데모 기능을 포함하고 있습니다.

Haply Hub

Haply Hub의 최신 버전 다운로드

허브를 다운로드하여 설치하고 기기를 연결하면, 허브가 펌웨어 업데이트 전 과정을 안내해 드립니다. 설치가 완료되면, 허브를 열 때마다 Inverse Service가 백그라운드에서 자동으로 실행됩니다.

독립형 설치를 원하시나요?

또한 허브를 거치지 않고도 Inverse Service의 특정 버전을 시스템 서비스(Windows) 또는 데몬(Linux/macOS)으로 설치할 수 있습니다. 설치 프로그램 링크 및 설치 방법은 ‘서비스 실행’을 참조하십시오.

간단한 예시

서비스에 연결한 후, 첫 번째 Inverse3 의 커서 위치를 확인하고, 서비스가 상태 프레임을 계속 전송하도록 하기 위해 강제 값이 0인 유지 메시지를 전송하십시오:

파이썬

import asyncio, json, websockets

async def main():
    # Connect to the Haply Inverse service WebSocket
    async with websockets.connect("ws://localhost:10001") as ws:
        # Read the first state frame to discover the device id
        first_state = json.loads(await ws.recv())
        device_id = first_state["inverse3"][0]["device_id"]

        # Build a zero-force keepalive command targeting that device
        keepalive = {"inverse3": [{
            "device_id": device_id,
            "commands": {"set_cursor_force": {"vector": {"x": 0, "y": 0, "z": 0}}}
        }]}

        # Realtime loop: one send per tick, then read the resulting state
        while True:
            await ws.send(json.dumps(keepalive))
            state = json.loads(await ws.recv())
            pos = state["inverse3"][0]["state"]["cursor_position"]
            print(f"pos: {pos}")

asyncio.run(main())

자바스크립트 (Node)

import WebSocket from 'ws'

// Connect to the Haply Inverse service WebSocket
const ws = new WebSocket('ws://localhost:10001')
let keepalive

ws.on('message', (msg) => {
  const state = JSON.parse(msg)
  if (!keepalive) {
    // Read the first state frame to discover the device id
    const deviceId = state.inverse3[0].device_id
    // Build a zero-force keepalive command targeting that device
    keepalive = JSON.stringify({
      inverse3: [
        {
          device_id: deviceId,
          commands: { set_cursor_force: { vector: { x: 0, y: 0, z: 0 } } },
        },
      ],
    })
    ws.send(keepalive)
    return
  }
  // Realtime loop: one send per tick, then read the resulting state
  ws.send(keepalive)
  console.log('pos:', state.inverse3[0].state.cursor_position)
})

C++ (nlohmann)

#include <external/libhv.h>
#include <nlohmann/json.hpp>

int main() {
    hv::WebSocketClient ws;
    nlohmann::json keepalive;

    ws.onmessage = [&](const std::string& msg) {
        auto state = nlohmann::json::parse(msg);
        if (keepalive.is_null()) {
            // Read the first state frame to discover the device id
            auto device_id = state["inverse3"][0]["device_id"];
            // Build a zero-force keepalive command targeting that device
            keepalive = {{"inverse3", nlohmann::json::array({{
                {"device_id", device_id},
                {"commands", {{"set_cursor_force",
                    {{"vector", {{"x", 0}, {"y", 0}, {"z", 0}}}}}}}
            }})}};
            ws.send(keepalive.dump());
            return;
        }
        // Realtime loop: one send per tick, then read the resulting state
        ws.send(keepalive.dump());
        auto pos = state["inverse3"][0]["state"]["cursor_position"];
        std::cout << "pos: " << pos << "\n";
    };
    // Connect to the Haply Inverse service WebSocket
    ws.open("ws://localhost:10001");
    std::cin.get();
}

C++ (최적화됨)

컴파일 시 리플렉션을 위해 세계에서 가장 빠른 JSON 라이브러리 중 하나인 Glaze를 사용합니다. 햅틱 주파수(수 kHz 수준)에서는 JSON 분석에 소요되는 1마이크로초마다 제어 루프에서 1마이크로초가 빼앗기게 되므로, 이 점이 매우 중요합니다. 읽고 쓰는 구조는 최소한으로만 선언하십시오. 나머지는 무시됩니다.

#include <external/libhv.h>
#include <glaze/glaze.hpp>

struct vec3 { float x{}, y{}, z{}; };
struct inverse_state { vec3 cursor_position; };
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 device_cmd { std::string device_id;
    struct { std::optional<set_cursor_force_cmd> set_cursor_force; } commands; };
struct commands_message { std::vector<device_cmd> inverse3; };

int main() {
    hv::WebSocketClient ws;
    commands_message keepalive;
    ws.onmessage = [&](const std::string& msg) {
        devices_message state{};
        if (glz::read_json(state, msg)) return;
        if (keepalive.inverse3.empty()) {
            // Read the first state frame to discover the device id
            auto device_id = state.inverse3[0].device_id;
            // Build a zero-force keepalive command targeting that device
            keepalive.inverse3.push_back({device_id});
            keepalive.inverse3[0].commands.set_cursor_force = set_cursor_force_cmd{};
            std::string out; (void)glz::write_json(keepalive, out);
            ws.send(out);
            return;
        }
        // Realtime loop: one send per tick, then read the resulting state
        std::string out; (void)glz::write_json(keepalive, out);
        ws.send(out);
        printf("pos: %f %f %f\n", state.inverse3[0].state.cursor_position.x,
               state.inverse3[0].state.cursor_position.y,
               state.inverse3[0].state.cursor_position.z);
    };
    // Connect to the Haply Inverse service WebSocket
    ws.open("ws://localhost:10001");
    std::cin.get();
}

러스트

다음 예시를 통해 설명합니다. tokio-tungstenite + serde_json.

use futures_util::{SinkExt, StreamExt};
use serde_json::json;
use tokio_tungstenite::{connect_async, tungstenite::Message};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to the Haply Inverse service WebSocket
    let (mut ws, _) = connect_async("ws://localhost:10001").await?;

    // Read the first state frame to discover the device id
    let first = match ws.next().await {
        Some(Ok(Message::Text(m))) => m,
        _ => anyhow::bail!("no initial state frame"),
    };
    let first_state: serde_json::Value = serde_json::from_str(&first)?;
    let device_id = first_state["inverse3"][0]["device_id"].as_str().unwrap();

    // Build a zero-force keepalive command targeting that device
    let keepalive = json!({
        "inverse3": [{
            "device_id": device_id,
            "commands": { "set_cursor_force": { "vector": { "x": 0, "y": 0, "z": 0 } } }
        }]
    }).to_string();

    // Realtime loop: one send per tick, then read the resulting state
    loop {
        ws.send(Message::Text(keepalive.clone())).await?;
        let msg = match ws.next().await {
            Some(Ok(Message::Text(m))) => m,
            _ => break,
        };
        let state: serde_json::Value = serde_json::from_str(&msg)?;
        println!("pos: {}", state["inverse3"][0]["state"]["cursor_position"]);
    }
    Ok(())
}

주의

힘 값은 신중하게 조정하십시오. 힘 값을 갑자기 크게 설정하면 기기가 손상되거나 예기치 않은 동작이 발생할 수 있습니다.

정보

메시지 래퍼, 포트 및 콘텐츠 유형 규칙에 대해서는 ‘JSON 규약’ 페이지를 참조하십시오.

더 많은 예시

파이썬, C++(nlohmann) 및 C++(Glaze)에 대한 포괄적인 튜토리얼(햅틱 피드백, 위치 제어, 다중 장치 구성, 마운팅 및 기준점 설정, 이벤트 흐름 등을 다룹니다)을 보려면 튜토리얼 페이지를 참조하십시오.