본문으로 건너뛰기

HTTP

기본적으로 HTTP 서비스는 http://localhost:10001에서 시작됩니다.

포트는 서비스의 설정에서 변경할 수 있습니다.

개요​

이 섹션에서는 서비스가 제공하는 HTTP 라우트를 설명합니다.

아래 모든 라우트는 기본 베이스 URL인 http://localhost:10001을 기준으로 합니다.

표준 응답 엔벨로프​

모든 엔드포인트는 다음 두 가지 엔벨로프 중 하나를 반환합니다:

데이터 없는 응답 (변경 전용 엔드포인트에서 사용):

{ "ok": true }
{ "ok": false, "error": "reason string" }

데이터 응답 (GET 요청과 적용된 값을 그대로 반환하는 설정 엔드포인트의 POST/DELETE 요청에서 사용):

{ "ok": true, "data": { "..." : "..." } }
{ "ok": false, "error": "reason string" }

장치 선택자 문법​

장치 수준 경로는 /{device_type}/{id_or_index}/... 패턴을 사용합니다. {device_type}과 {id_or_index} 경로 세그먼트는 대상 장치를 식별합니다.

예시 경로 세그먼트의미
inverse3/0인덱스(0부터 시작)로 지정한 첫 번째 Inverse3
inverse3/A14장치 ID가 A14인 Inverse3
inverse3/*모든 Inverse3 장치(와일드카드)
verse_grip/0인덱스로 지정한 첫 번째 Verse Grip
wireless_verse_grip/*모든 Wireless Verse Grip
*inverse/*Inverse 계열 장치 전체(Inverse3, Inverse3x, Minverse)
*verse_grip/*Verse Grip 계열 장치 전체(Verse Grip, Wireless VG)

와일드카드 규칙:

  • GET은 모호하거나 와일드카드가 포함된 선택자를 거부합니다(400 반환).
  • POST와 DELETE는 와일드카드를 허용합니다 -- 작업이 일치하는 모든 장치에 적용됩니다.

세션 선택자​

세션 범위 엔드포인트(basis, mount, preset, transform, filters)는 세션을 식별하기 위해 ?session=<expr> 쿼리 매개변수가 필요합니다.

표현식의미
(생략)모든 세션(DELETE 전용)
#123 또는 123숫자 ID 123인 세션
:-1인덱스 기준 마지막 세션
:0인덱스 기준 첫 번째 세션

예시: GET /inverse3/0/config/basis?session=:0

버전​

메서드: GET
URL: http://localhost:10001/version

응답 예시:

{
  "build_time": "2024-08-07T16:01:53Z",
  "git_branch": "main",
  "git_describe": "3.5.0-2-gce34c39e",
  "git_hash": "ce34c39e",
  "git_tag": "3.5.0",
  "project_name": "haply-inverse-service",
  "project_version": "3.5.0"
}

전문가 상태​

메서드: GET
URL: http://localhost:10001/expert/status

감지, 장치, 세션 및 전역 설정을 포함한 상세 상태 정보를 반환합니다.

장치​

메서드: GET
URL: http://localhost:10001/devices

config, state, status를 포함한 현재 장치 목록을 반환합니다.

선택적으로 ?session=<expr>을 전달하여 스냅샷을 특정 세션의 관점으로 필터링할 수 있습니다(해당 세션의 basis, mount, transform을 반환되는 값에 적용합니다).

응답 예시:

{
  "inverse3": [
    {
      "device_id": "04BA",
      "config": { "...": "..." },
      "state": { "...": "..." },
      "status": { "...": "..." }
    }
  ]
}

세션​

메서드경로설명
GET/sessions활성 v3.1 세션 전체 목록 조회
GET/sessions/{session_id}단일 세션 조회
GET/sessions/{session_id}/profile세션 프로필 이름 조회
POST/sessions/{session_id}/profile세션 프로필 설정
DELETE/sessions/{session_id}/profile프로필을 "default"로 재설정

POST /sessions/{session_id}/profile 본문:

{
  "name": "my_profile"
}

포트​

메서드: POST
URL: http://localhost:10001/ports/{port}/reset

차단된 시리얼 포트를 해제합니다. { "ok": true }를 반환합니다.

장치 구성​

모든 구성(config) 엔드포인트는 /{device_type}/{id_or_index}/config/{setting} 패턴을 사용합니다.

세션 범위 엔드포인트(basis, mount, preset)는 추가로 ?session=<expr> 쿼리 매개변수가 필요합니다.

손 방향 (Handedness, Inverse3 전용)​

메서드경로본문응답
GET/{device_type}/{id}/config/handedness--"left" 또는 "right"
POST/{device_type}/{id}/config/handedness"left" 또는 "right"입력값 그대로 반환
DELETE/{device_type}/{id}/config/handedness--"right" (기본값)

토크 스케일링 (Inverse3 전용)​

메서드경로본문응답
GET/{device_type}/{id}/config/torque_scaling--{ "enabled": bool }
POST/{device_type}/{id}/config/torque_scaling{ "enabled": bool }입력값 그대로 반환
DELETE/{device_type}/{id}/config/torque_scaling--{ "enabled": false }

중력 보상 (Inverse3 전용)​

메서드경로본문응답
GET/{device_type}/{id}/config/gravity_compensation--{ "enabled": bool, "scaling_factor": float }
POST/{device_type}/{id}/config/gravity_compensation{ "enabled": bool, "scaling_factor": float }입력값 그대로 반환
DELETE/{device_type}/{id}/config/gravity_compensation--{ "enabled": true, "scaling_factor": 1.0 }

Basis (모든 장치, 세션 범위)​

메서드경로본문응답
GET/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }
POST/{device_type}/{id}/config/basis?session={ "permutation": "ZXY" }입력값 그대로 반환
DELETE/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }

Mount (모든 장치, 세션 범위)​

메서드경로본문응답
GET/{device_type}/{id}/config/mount?session=--{ "transform": {...} }
POST/{device_type}/{id}/config/mount?session={ "transform": {...} }입력값 그대로 반환
DELETE/{device_type}/{id}/config/mount?session=--항등 변환(identity transform)

Transform 구조 (mount 및 state/transform에서 사용):

{
  "transform": {
    "position": { "x": 0, "y": 0, "z": 0 },
    "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
    "scale": { "x": 1, "y": 1, "z": 1 }
  }
}

프리셋 (모든 장치, 세션 범위)​

메서드경로본문응답
GET/{device_type}/{id}/config/preset?session=--{ "preset": "arm_front_centered" }
POST/{device_type}/{id}/config/preset?session={ "preset": "arm_front_centered" }반환된 값
DELETE/{device_type}/{id}/config/preset?session=--{ "preset": "device_defaults" }

사용 가능한 값: device_defaults, arm_front, arm_front_centered, led_front, led_front_centered, custom.

장치 필터 (Inverse3 전용, 세션 범위)​

필터 엔드포인트는 /{device_type}/{id}/config/filters/{filter}?session=<expr> 경로를 사용합니다.

댐핑​

균일 댐핑과 방향성 댐핑 모두를 제어합니다. POST 본문에는 최소 한 개의 필드가 있어야 합니다.

메서드경로본문응답
GET/{device_type}/{id}/config/filters/damping?session=--{ "scalar": float, "vector": { "x": f, "y": f, "z": f } }
POST/{device_type}/{id}/config/filters/damping?session={ "scalar": float } 또는 { "vector": {...} } 또는 둘 다반환된 값
DELETE/{device_type}/{id}/config/filters/damping?session=--둘 다 0으로 재설정

포스 게이트​

메서드경로본문응답
GET/{device_type}/{id}/config/filters/force_gate?session=--{ "gain": float }
POST/{device_type}/{id}/config/filters/force_gate?session={ "gain": float }반환된 값
DELETE/{device_type}/{id}/config/filters/force_gate?session=--설정의 기본 gain 값

장치 상태​

변환 (모든 장치, 세션 범위)​

워크스페이스 변환 (장치 공간에서 애플리케이션 공간으로).

메서드경로본문응답
GET/{device_type}/{id}/state/transform?session=--{ "transform": {...} }
POST/{device_type}/{id}/state/transform?session={ "transform": {...} }반환된 값
DELETE/{device_type}/{id}/state/transform?session=--항등 변환

구성 저장​

Inverse3 장치에서만 작동합니다. 경고: 구성을 너무 자주 저장하지 마십시오. 장치 하나에 적용할 수 있는 저장 횟수는 제한되어 있기 때문입니다 (약 10,000회 EEPROM 쓰기).

메서드: POST
URL: http://localhost:10001/save_configuration

본문 예시:

{
  "device_id": "049D"
}

응답 예시:

{
  "ok": true
}

설정​

설정 엔드포인트는 다음 항목에 대해 자동으로 생성됩니다:

  • 메타데이터를 포함한 모든 설정 나열
  • 단일 설정 값 읽기
  • 설정 적용 (단일 또는 일괄)
  • 키를 기본값으로 재설정

모든 설정 키 참조는 여기에서 확인할 수 있습니다

라우트​

메서드라우트설명
GET/settings/모든 설정 키, 값 및 메타데이터를 가져옵니다.
POST/settings/여러 설정을 한 번에 일괄 적용합니다.
GET/settings/{key}특정 설정 키의 현재 값을 가져옵니다.
POST/settings/{key}특정 키에 새 값을 적용합니다.
DELETE/settings/{key}키를 기본값으로 재설정합니다.

응답 형식​

GET /settings/ (모든 설정)​

설정 키를 키로 하는 객체를 반환합니다. 각 항목에는 다음이 포함됩니다:

  • value: 현재 값
  • metadata: 타입 + 제약 조건 + 잠금 상태

항목 예시:

{
  "devices/detection/timeout": {
    "metadata": {
      "constraint": {
        "range": {
          "max": 15,
          "min": 1,
          "step": 0
        }
      },
      "locked": false,
      "type_hint": "INT"
    },
    "value": 5
  }
}

GET /settings/{key} (단일 설정)​

요청한 키에 대해 값만 (메타데이터 제외) 반환합니다.

설정 적용​

POST /settings/ (일괄 적용)​

여러 키를 한 번에 일괄 적용합니다.

권장 본문 형식: 키를 값에 매핑하는 JSON 객체.

{
  "devices/detection/timeout": 5,
  "devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}

POST /settings/{key} (단일 적용)​

단일 키에 새 값을 적용합니다.

권장 본문 형식: 원시 JSON 값 또는 래핑된 값 중 하나 (명확성을 위해 래핑된 값을 권장합니다).

{
  "value": 5
}

설정 재설정​

DELETE /settings/{key}​

키를 기본값으로 되돌립니다.

이는 "기본값으로 재설정"과 같습니다.

타입 힌트​

서비스가 type_hint를 자동으로 추론합니다. 복잡한 타입에는 대체값으로 GENERIC이 사용됩니다.

지원되는 힌트:

  • BOOL
  • INT
  • FLOAT
  • STRING
  • VEC2
  • VEC3
  • VEC4
  • TRANSFORM
  • ARR_INT
  • ARR_FLOAT
  • ARR_STRING
  • GENERIC

사용 중단된 레거시 엔드포인트​

여러 POST 엔드포인트는 여전히 허용되지만 사용 중단 경고를 출력하며 4.0에서 제거될 예정입니다. 자세한 사용 중단 경로 → 대체 라우트 표는 3.5 마이그레이션 가이드를 참조하십시오.