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": { "...": "..." }
}
]
}
세션
| 메서드 | 패스 | 설명 |
|---|---|---|
| 받기 | /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 가 사용됩니다.
지원되는 팁:
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
권장되지 않는 레거시 엔드포인트
몇 가지 POST 엔드포인트는 계속 접수되지만, 권장하지 않는다는 경고가 표시됩니다.
이러한 항목들은 4.0 에서 삭제될 예정입니다.
권장되지 않는 경로에서 대체 경로로 전환되는 전체 대응표에 대해서는,3.5 마이그레이션 가이드확인해 주세요.