본문으로 건너뛰기

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 또는 123ID 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": { "...": "..." }
}
]
}

세션​

메서드패스설명
받기/sessions활성 v3.1 세션을 모두 나열
받기/sessions/{session_id}단일 세션 가져오기
받기/sessions/{session_id}/profile세션 프로필 이름 가져오기
게시물/sessions/{session_id}/profile세션 프로필 설정
삭제/sessions/{session_id}/profile프로필을 "default" 으로 초기화

게시물 /sessions/{session_id}/profile 본문:

{
"name": "my_profile"
}

포트​

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

차단된 직렬 포트를 해제합니다.{ "ok": true } 을 반환합니다.


기기 설정​

모든 설정 엔드포인트는 /{device_type}/{id_or_index}/config/{setting} 의 패턴을 사용합니다.

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

주손(Inverse3 만 해당)​

메서드패스바디응답
받기/{device_type}/{id}/config/handedness--"left" 또는 "right"
게시물/{device_type}/{id}/config/handedness"left" 또는 "right"반환된 값
삭제/{device_type}/{id}/config/handedness--"right"(기본값)

토르크스 스케일링 (Inverse3 에만 해당)​

메서드패스바디응답
받기/{device_type}/{id}/config/torque_scaling--{ "enabled": bool }
게시물/{device_type}/{id}/config/torque_scaling{ "enabled": bool }반환된 값
삭제/{device_type}/{id}/config/torque_scaling--{ "enabled": false }

중력 보정 (Inverse3 에만 해당)​

메서드패스바디응답
받기/{device_type}/{id}/config/gravity_compensation--{ "enabled": bool, "scaling_factor": float }
게시물/{device_type}/{id}/config/gravity_compensation{ "enabled": bool, "scaling_factor": float }반환된 값
삭제/{device_type}/{id}/config/gravity_compensation--{ "enabled": true, "scaling_factor": 1.0 }

기본값 (모든 기기, 세션 범위)​

메서드패스바디응답
받기/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }
게시물/{device_type}/{id}/config/basis?session={ "permutation": "ZXY" }반환된 값
삭제/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }

마운트(모든 장치, 세션 범위)​

메서드패스바디응답
받기/{device_type}/{id}/config/mount?session=--{ "transform": {...} }
게시물/{device_type}/{id}/config/mount?session={ "transform": {...} }반환된 값
삭제/{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 }
}
}

사전 설정 (모든 기기, 세션 단위)​

메서드패스바디응답
받기/{device_type}/{id}/config/preset?session=--{ "preset": "arm_front_centered" }
게시물/{device_type}/{id}/config/preset?session={ "preset": "arm_front_centered" }반환된 값
삭제/{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 본문에는 최소한 하나의 필드가 포함되어야 합니다.

메서드패스바디응답
받기/{device_type}/{id}/config/filters/damping?session=--{ "scalar": float, "vector": { "x": f, "y": f, "z": f } }
게시물/{device_type}/{id}/config/filters/damping?session={ "scalar": float } 또는 { "vector": {...} } 또는 둘 다반환된 값
삭제/{device_type}/{id}/config/filters/damping?session=--둘 다 0으로 초기화

포스게이트​

메서드패스바디응답
받기/{device_type}/{id}/config/filters/force_gate?session=--{ "gain": float }
게시물/{device_type}/{id}/config/filters/force_gate?session={ "gain": float }반환된 값
삭제/{device_type}/{id}/config/filters/force_gate?session=--설정의 기본값인 gain

장치 상태​

변환(모든 기기, 세션 단위)​

작업 공간의 변환(장치 공간에서 애플리케이션 공간으로의 변환).

메서드패스바디응답
받기/{device_type}/{id}/state/transform?session=--{ "transform": {...} }
게시물/{device_type}/{id}/state/transform?session={ "transform": {...} }반환된 값
삭제/{device_type}/{id}/state/transform?session=--항등 변환

설정 저장​

Inverse3 이 기능은 해당 장치에서만 작동합니다. 경고: 설정을 너무 자주 저장하지 마십시오. 각 장치에 적용할 수 있는 저장 횟수에는 상한이 있습니다(EEPROM 쓰기 약 10,000회).

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

본문 예시:

{
"device_id": "049D"
}

응답 예시:

{
"ok": true
}

설정​

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

  • 모든 설정 목록 가져오기 (메타데이터 포함)
  • 단일 설정값 읽기
  • 설정 적용 (개별 또는 일괄)
  • 키를 기본값으로 재설정

설정 키 목록은여기에서확인할 수 있습니다.

경로​

메서드경로설명
받기/settings/모든 설정 키, 값 및 메타데이터를 가져옵니다.
게시물/settings/여러설정을 한 번에 적용합니다.
받기/settings/{key}특정 설정키의 현재 값을가져옵니다.
게시물/settings/{key}특정 키에 새로운 값을 적용합니다.
삭제/settings/{key}키를기본값으로재설정합니다.

응답 형식​

받기 /settings/(모든 설정)​

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

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

예시 항목:

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

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

지정된 키의값만(메타데이터 제외) 반환합니다.

설정 적용​

게시물 /settings/(일괄 적용)​

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

권장되는 데이터 형식: 키와 값 간의 매핑을 나타내는 JSON 객체.

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

게시물 /settings/{key}(단일 적용)​

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

권장되는 데이터 형식: 원시 JSON 값 또는 래핑된 값 중 하나(이해하기 쉽도록 래핑된 형식을 권장합니다).

{
"value": 5
}

설정 초기화​

삭제 /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 마이그레이션 가이드확인해 주세요.