설정 참조
이 문서에서는,/settings/엔드포인트가 반환하는 모든 설정을 각각의키、형(type_hint(부터), 그리고제약(metadata.constraint.range, 그리고 해당되는 경우locked(~부터)와 함께 목록으로 정리해 두었습니다.
locked설정은,실행 시에는 읽기 전용입니다. 설정 파일에서, 또는Haply Hub설정 페이지에서 변경할 수 있지만, 변경 사항을 적용하려면서비스를 완전히 재시작해야 합니다.입니다. 이에 대해서는 다음 표에서부팅라고 표기되어 있습니다.
구성
서비스 시작 시 설정을 덮어쓰기 위한 구성 파일은 다음 위치에 있습니다:
| 플랫폼 | 장소 |
|---|---|
| Windows | C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json |
| macOS | /Library/Application Support/Haply/Inverse/haply-inverse-service-config.json |
| 리눅스 | /etc/haply-inverse-service/haply-inverse-service-config.json |
설정 파일은 설정 키와 덮어쓰기 값을 서로 연결합니다.플랫한 JSON 객체입니다. 키는,/settings/ HTTP 경로（API 참조(참조)에서 반환하는 유효한 설정 키여야 합니다. 지정되지 않은 키의 경우 서비스의 기본값이 사용됩니다.
예를 들어, 네트워크 구성의 덮어쓰기 설정은 다음과 같습니다:
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
표시 및 필터링
/settings목록 엔드포인트(GET /settings、GET /settings/)는 기본적으로기본설정만 반환합니다. 고급 설정을 포함하려면?advanced=true를, 권장되지 않는 별칭을 포함하려면?deprecated=true을 지정해 주십시오. ‘숨김’ 설정은 내부 용도로만 사용되며,POST /settings/misc/hidden_settings~을 통해misc/hidden_settings이 설정된 경우에만 표시됩니다(이에 상응하는 쿼리 매개변수는 없습니다). 필터 플래그는 AND 조건으로 결합됩니다.advanced그리고hidden두 플래그가 모두 설정된 키의 경우, 두 게이트를 모두 열어야 합니다. 알려진 키에 대한 POST 및 DELETE 요청은 게이트의 적용 대상에서 제외됩니다.
정식 키를 정확하게 지정한 경우, 단일 키 읽기(GET /settings/<key>)는 advanced/deprecated 게이트를 우회합니다. 사전 지식이 있는 클라이언트에게 유용합니다. 숨겨진 키는 계속해서 게이트의 대상이 됩니다.
3개의 런타임 토글이 게이트의 초기값을 설정합니다. 이 값들은 서비스가 실행되는 동안 계속 유지됩니다:
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
misc/advanced_settings | bool | — | GET /settings목록에advanced플래그가 설정된 항목도 포함합니다(기본값은false). 모든 요청에서?advanced=true~을 건네주는 것과 같습니다. |
misc/deprecated_settings | bool | — | GET /settings목록에deprecated플래그가 설정된 항목도 포함합니다(기본값은false). 모든 요청에서?deprecated=true~을 건네주는 것과 같습니다. |
형 매핑
API가 반환하는 타입 힌트는 다음 JSON 형식을 지원합니다:
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3({x, y, z}(해당 속성을 가진 객체)GENERIC→json(임의의 구조화된 값)
communication/…
HTTP, WebSocket 및 이벤트 스트림 서버의 네트워크 포트와 바인딩 주소입니다.대부분의 항목은 부팅 시에만유효합니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
communication/serial/enabled | bool | — | 직렬 장치 통신을 활성화하거나 비활성화합니다. |
communication/bind_address | string | 부팅 | HTTP 및 WebSocket 서버가 바인딩하는 IP 주소. |
communication/bind_all_interfaces | bool | 부팅 | localhost 대신 서버를0.0.0.0에 바인딩합니다. |
communication/http/port | int | 부팅 | HTTP REST API의 포트(기본값) 10000). |
communication/websocket/port | int | 부팅 | 기본 v3.1 WebSocket 포트(기본값) 10001). |
communication/websocket/legacy_port | int | 부팅 | 레거시 v3.0 WebSocket 포트(기본값) 10000). |
communication/events/port | int | 부팅 | 이벤트 스트림 WebSocket 포트(기본값) 10020). |
devices/…
devices/detection/…
직렬 포트 스캔 정책입니다. 모든 항목은 고급 설정입니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 범위 100–10000; 시작 시 | 직렬 포트의 스캔 간격(ms). |
devices/detection/handshake_timeout_s | int | 범위 1–15 | 포트별 핸드셰이크 타임아웃(초). |
devices/detection/max_retries | int | 범위 1–10 | 포트별 핸드셰이크의 최대 재시도 횟수. |
devices/detection/failure_log_delay_s | int | 범위 1–60 | 탐지 실패를 다시 로그에 기록하기까지의 지연 시간(초). |
devices/detection/block_looping_ports | bool | — | 루프가 발생하는 포트가 감지되면 장치의 준비 완료 상태를 차단합니다. |
devices/detection/excluded_ports | json | — | 탐지 시 건너뛸 직렬 포트 경로. |
devices/detection/additional_ports | string[] | — | 무조건 스캔할 추가 직렬 포트의 경로. |
devices/detection/allowed_vendor_id_filter | string[] | — | 포트 열거 시 허용할 USB 벤더 ID. |
devices/detection/port_name_substring_filter | string[] | — | 일치시킬 플랫폼별 포트 이름의 부분 문자열. |
devices/detection/wireless_verse_grip_description_filter | string[] | — | 무선 VerseGrip 감지를 위한 포트 설명의 일부 문자열. |
devices/detection/inverse3x_description_filter | string[] | — | Inverse3x 감지를 위한 포트 설명의 일부 문자열. |
devices/detection/extra_ports (권장하지 않음) | string[] | — | 대신 devices/detection/additional_ports 을 사용해 주십시오. 읽기 및 쓰기 작업은 정규 키로 투명하게 전달됩니다. |
devices/*inverse/…
이는 모든 Inverse3 제품군 장치에 적용되는 전역 기본값입니다. 세션별 재정의 설정이 우선 적용됩니다.
3.5.0에서는 글로브는 devices/inverse*/… 였습니다. 현재는 맨 앞의 * 하지만 inverse 앞에 배치됩니다. 구형 리터럴을 사용하는 설정 파일은 3.5.1에서 바인딩에 실패하므로 업데이트해 주십시오. 키 자체에는 그 외의 변경 사항은 없습니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | 범위 0.0–2.0 | 모든 장치에 적용되는 전 세계적인 출력 계수. |
devices/*inverse/filters/force_gate/gain | float | 범위 0.0–1.0 | 새 세션의 기본 포스 게이트 게인. |
devices/*inverse/control_timeout_ms | int | 범위 50–10000 | 장치 제어 잠금을 해제하기까지의 타임아웃(ms). |
devices/*inverse/query_orientation_on_idle | bool | — | 기기가 유휴 상태일 때, 펌웨어를 통해 기기의 방향을 확인합니다. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | 기기별 안전 플래그를 GET /devices/{id} 의 스냅샷에 포함합니다. |
devices/presets
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
devices/presets | json | — | 기기 유형별 기본 기기 구성 프리셋(마운트 변환, 기저 등. 대상은 inverse_arm_front_*、inverse_led_front_*、minverse_*、verse_grip_default、wireless_verse_grip_default、custom_verse_grip_default). |
devices/wireless_verse_grip/…
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | 배터리 잔량(%)이 이 값보다 낮아지면 배터리 부족 경고가 표시됩니다. |
devices/wireless_verse_grip/battery/critical_threshold | int | — | 배터리 잔량(%)이 이 수치보다 낮아지면 배터리 위험 경고가 발생합니다. |
devices/wireless_verse_grip/battery/reset_margin | int | — | 배터리 경고가 해제될 때까지의 히스테리시스 여유량. |
devices/wireless_verse_grip/filters/orientation_filter | json | 시작 시 | 무선 VerseGrip의 방향에 따른 One Euro Filter 설정. |
features/…
features/calibration/…
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/calibration/hall_threshold | int | 범위 1–32 | 보정 중에 펜이 장착되어 있다고 판정되는 홀 센서의 레벨. |
features/grip_hook/…
그립 후크의 자동 작동 기능입니다. 그립이 수직으로 유지되는 동안 커서를 고정합니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/grip_hook/enabled | bool | — | 그립이 수직으로 유지될 때, 그립 후크를 통한 자동 잠금 기능을 활성화합니다. |
features/grip_hook/use_hall | bool | — | 그립 감지 시 방향이 아닌 홀 센서의 임계값을 사용합니다. |
features/grip_hook/hall | int | 범위 1–32 | 홀 센서 값이 특정 임계값에 도달하면 그립 잠금 장치가 작동합니다. |
features/grip_hook/hold_duration | int | 범위 10–1000 | 트리거 후 잠금을 유지하는 시간(ms). |
features/navigation/bubble/…
버블 내비게이션 모듈의 기본값입니다.bubble 의 동작이 처음 활성화되면 세션으로 전달됩니다. 각 필드의 실행 시 의미에 대해서는,네비게이션 모듈 해당 페이지를 참조해 주십시오.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | 버블의 중심 위치에 대한 기본값. |
features/navigation/bubble/center_enabled | bool | — | 버블 동작이 처음 활성화되었을 때 설정된 center 을 적용합니다. |
features/navigation/bubble/rotation_enabled | bool | — | 작업 공간의 회전을 탐색 방향에 적용합니다. |
features/navigation/bubble/scale_enabled | bool | — | 워크스페이스의 배율을 탐색 속도에 적용합니다. |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | auto_follow 중심 모드에서의 드리프트 속도 (m/s). |
features/navigation/bubble/max_velocity | float | — | 속도 구역 내의 최대 내비게이션 속도 (m/s). |
features/navigation/bubble/velocity_zone_width | float | — | 거품 표면 바깥쪽에 위치한 속도 영역의 폭 (m). |
features/navigation/bubble/reset_velocity_on_entry | bool | — | 커서가 버블 안으로 들어갈 때 속도를 0으로 재설정합니다. |
features/navigation/bubble/spring_inner | float | — | 버블 중심에서의 탄성 계수 (N/m). |
features/navigation/bubble/spring_surface | float | — | 거품 표면의 탄성 계수 (N/m). |
features/navigation/bubble/spring_outer | float | — | 외측 경계에서의 탄성 계수 (N/m). |
features/navigation/bubble/damping_inner | float | — | 버블 중심에서의 감쇠 계수 (Ns/m). |
features/navigation/bubble/damping_surface | float | — | 거품 표면의 감쇠 계수 (Ns/m). |
features/navigation/bubble/damping_outer | float | — | 외측 경계에서의 감쇠 계수 (Ns/m). |
features/navigation/bubble/wall_stiffness | float | — | 외측 경계에 있는 단단한 벽의 강성 (N/m). |
features/navigation/bubble/bump_width | float | — | 거품 표면의 촉각 돌기 너비 (m). |
features/navigation/bubble/bump_stiffness | float | — | 버블 표면의 촉각 범프의 강성 (N/m). |
features/navigation/bubble/stop_at_collision | bool | — | 충돌이 유효한 동안, 버블의 중심이 충돌 방향으로 이동하는 것을 방지합니다. |
features/navigation/bubble/collision_threshold | float | > 0 | 충돌을 감지하는 외력의 크기 (N). |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | 충돌이 유효한 동안,velocity_zone_width 에 적용되는 배수. |
features/navigation/bubble/collision_exit_ratio | float | 범위 (0, 1] | 히스테리시스 비율.|ext_force| 하지만 collision_threshold × this 이 값보다 낮아지면 충돌을 해제합니다.1.0 이 경우 히스테리시스가 비활성화됩니다. |
features/navigation/bubble/avatar_boundary_enabled | bool | — | 아바타의 월드 위치를, 미리 설정된 avatar_boundary SDF 형상 범위 내로 제한합니다. |
features/safe_trajectory/…
엔드 이펙터의 움직임에 대한 속도 제한 장치입니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | 안전 궤적의 속도 제한 장치를 활성화합니다. |
features/safe_trajectory/max_vel | float | 범위 0.01–2.0 | 엔드 이펙터의 최대 허용 속도 (m/s). |
features/screensaver/…
세션에 의해 제어되지 않을 때, ‘Inverse3 ’ 기기에서 재생되는 유휴 애니메이션입니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/screensaver/enabled | bool | — | Inverse3 기기에서 유휴 상태일 때 화면 보호기 애니메이션을 활성화합니다. |
features/screensaver/speed | float | 범위 0.001–0.2 | 스크린세이버 애니메이션의 속도. |
features/screensaver/distracted_speed | float | 범위 0.001–0.2 | 사용자가 근처에 있지만 기기를 조작하지 않을 때의 애니메이션 속도. |
features/sdf/…
부호화된 거리장(SDF)의 촉각 효과 모듈(SDF HFX).
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/sdf/enabled | bool | — | SDF 촉각 효과 모듈을 활성화하거나 비활성화합니다. |
features/sdf/state_output | bool | — | 기본적으로 장치의 출력 페이로드에 SDF 상태를 포함합니다. |
features/sdf/max_count | int | 범위 0–128 | 유효한 SDF 효과의 최대 개수 (0 = (무제한). |
features/sdf/events/created | bool | — | 새로운 SDF 이펙트가 생성되면 이벤트를 발생시킵니다. |
features/sdf/events/deleted | bool | — | SDF 이펙트가 삭제되면 이벤트를 발생시킵니다. |
features/sdf/events/updated | bool | — | SDF 이펙트가 업데이트되면 이벤트를 발생시킵니다. |
features/sdf/probe_on_zero_force/enabled | bool | — | 인가력이 거의 0일 때, SDF 필드를 자동으로 탐지합니다. |
features/sdf/probe_on_zero_force/delay | float | 범위 0.001–60.0 | 힘이 0으로 떨어진 후 자동 프로브가 시작되기까지의 지연 시간 (s). |
features/verse_grip_pairing/…
Inverse3 (유선 또는 무선) Verse Grip과의 장착/분리 상태를 추적합니다. 이는 ‘Haply Hub’ 페어링 UI의 기반이 됩니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | 페어링 및 장착/분리 추적을 활성화합니다. |
features/verse_grip_pairing/hall_threshold_vg | int | 범위 1–32 | 유선 VerseGrip이 장착된 것으로 판정되는 홀 레벨. |
features/verse_grip_pairing/hall_threshold_wvg | int | 범위 1–32 | 무선 VerseGrip이 장착된 것으로 판정되는 홀 레벨. |
features/verse_grip_pairing/detach_debounce_ms | int | 범위 0–1000 | 제거를 확정하기까지의 디바운스 시간 (ms). |
features/verse_grip_pairing/heartbeat_ms | int | 범위 100–10,000 | 강제 재알림 간격 (ms). |
features/verse_grip_pairing/force_attached | bool | — | 홀 센서를 우회하여, 장착 상태를 항상 true 을 강제 적용합니다(하드웨어 장애 발생 시의 대응책). |
session/serialization/…
출력 형식 변환 — WebSocket 및 HTTP JSON 페이로드에 영향을 미칩니다. 이러한 키는 세션 단위의 범위를 반영하기 위해 3.5.1에서 serialization/* 부터 session/serialization/* 로 이동했습니다. 기존 경로는 더 이상 사용되지 않는 별칭을 통해 계속해서 해결됩니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | 직렬화된 출력에, 항등(아이덴티티) 기본값과 동일한 transform 필드를 포함합니다(예: position: {0,0,0}、rotation: {w:1,…}). 클라이언트가 모든 필드의 명시적인 존재를 요구하는 경우에 유용합니다. 기본값: false。 |
session/serialization/force_complete_transforms | bool | — | 방향 조절 전용 장치(Verse Grip, Wireless Verse Grip)를 포함하여 모든 transform 출력에는 position、rotation、그리고 scale 을 항상 출력합니다. 이러한 장치는 일반적으로 rotation 만 출력합니다.session/serialization/explicit_fields 의 상위 호환 버전이며, 해당 기능을 모두 포함합니다. 기본값: false。 |
serialization/explicit_fields (권장하지 않음) | bool | — | 대신 session/serialization/explicit_fields 을 사용해 주십시오. 읽기 및 쓰기 작업은 정규 키로 투명하게 전달됩니다. |
serialization/force_complete_transforms (권장하지 않음) | bool | — | 대신 session/serialization/force_complete_transforms 을 사용해 주십시오. 읽기 및 쓰기 작업은 정규 키로 투명하게 전달됩니다. |
session/…
세션 스케줄러.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 범위 20–500 | 경고가 발생하기 전의 장치 시뮬레이션 속도에 대한 최소 허용값(Hz). |
rate/…
서비스 페이싱. 3.5.1에서 도입되었습니다 — 다음 4가지 rate/websocket/* 키는 예전에는 session/commands/* ... 아래에 있었습니다. 기존 경로는 더 이상 권장되지 않는 별칭을 통해 계속해서 해결됩니다.
| 키 | 형 | 제약 | 설명 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 0차 홀드 윈도우 — 이 윈도우 범위 내에서 수신된 프로브를 억제합니다(ms). |
rate/websocket/drop_warning_threshold | int | — | 경고를 표시하기 전까지 창 내에 드롭된 명령어의 수. |
rate/websocket/drop_warning_window_ms | int | — | 드롭된 명령어를 계산하기 위한 슬라이딩 윈도우의 크기(ms). |
rate/websocket/tick_on_empty_batch | bool | 상급 | WebSocket 배치 전체가 삭제된 경우에도,main_loop 틱을 예약합니다. |
session/commands/zoh_window_ms (권장하지 않음) | int | — | 대신 rate/websocket/zoh_window_ms 을 사용해 주십시오. 읽기 및 쓰기 작업은 투명하게 전달됩니다. |
session/commands/drop_warning_threshold (권장하지 않음) | int | — | 대신 rate/websocket/drop_warning_threshold 을 사용해 주십시오. 읽기 및 쓰기 작업은 투명하게 전달됩니다. |
session/commands/drop_warning_window_ms (권장하지 않음) | int | — | 대신 rate/websocket/drop_warning_window_ms 을 사용해 주십시오. 읽기 및 쓰기 작업은 투명하게 전달됩니다. |
session/commands/tick_on_empty_batch (권장하지 않음) | bool | — | 대신 rate/websocket/tick_on_empty_batch 을 사용해 주십시오. 읽기 및 쓰기 작업은 투명하게 전달됩니다. |
내부 전용 설정
3.5.1에서는 몇 가지 설정 그룹이 hidden 로 제공되며, 내부 전용으로 지정되어 있습니다 — rate/dispatch/*(AIMD의 디스패치율 상한 및 백프레셔 임계값),session/freeform/*(동작 지문 인식), 그리고 session/serialization/preview/*(오일러 4원수 출력 및 Wireless VerseGrip 라우팅 등의 프리릴리스 버전 직렬화 실험). 이들은 디버깅 용도로 misc/hidden_settings 에서 액세스할 수 있지만, 향후 마이너 버전에서 등급이 상향 조정되거나, 이름이 변경되거나, 삭제될 가능성이 있습니다. 클라이언트의 동작을 이에 의존하지 마십시오.