설정 참조
이 문서는 /settings/ 엔드포인트가 반환하는 모든 설정을 키, 타입(type_hint 기준), 제약 조건(metadata.constraint.range 및 해당하는 경우 locked 기준)과 함께 나열합니다.
locked 설정은 런타임에 읽기 전용입니다. 설정 파일 또는 Haply Hub 설정 페이지를 통해 변경할 수 있지만, 변경 사항을 적용하려면 서비스를 완전히 재시작해야 합니다. 이러한 설정은 아래 표에서 boot로 표시됩니다.
구성
서비스 시작 중 설정을 재정의하는 구성 파일은 다음 위치에 있습니다:
| 플랫폼 | 위치 |
|---|---|
| Windows | C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json |
| MacOS | /Library/Application Support/Haply/Inverse/haply-inverse-service-config.json |
| Linux | /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/)는 기본적으로 기본(basic) 설정만 반환합니다. advanced 플래그가 지정된 설정을 포함하려면 ?advanced=true를, deprecated 플래그가 지정된 별칭을 포함하려면 ?deprecated=true를 전달하십시오. 숨김 설정은 내부 용도로 예약되어 있으며, POST /settings/misc/hidden_settings를 통해 misc/hidden_settings가 설정된 경우에만 표시됩니다(이에 해당하는 쿼리 매개변수는 없음). 필터 플래그는 AND로 결합됩니다. advanced와 hidden 플래그가 모두 지정된 키는 두 게이트가 모두 열려 있어야 합니다. 알려진 키에 대한 POST 및 DELETE는 게이트의 제한을 받지 않습니다.
정식 키(canonical key)를 정확히 사용하면 단일 키 조회(GET /settings/<key>)는 advanced/deprecated 게이트를 우회합니다. 사전 지식이 있는 클라이언트에 유용합니다. 숨김 키는 여전히 게이트의 제한을 받습니다.
세 가지 런타임 토글이 게이트의 초기값을 설정하며, 이 값은 서비스 수명 동안 유지됩니다:
| 키 | 타입 | 제약 조건 | 설명 |
|---|---|---|---|
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 및 이벤트 스트림 서버의 네트워크 포트와 바인드 주소입니다. 대부분의 항목은 boot 전용입니다.
| 키 | 타입 | 제약 조건 | 설명 |
|---|---|---|---|
communication/serial/enabled | bool | — | 시리얼 장치 통신을 활성화하거나 비활성화합니다. |
communication/bind_address | string | boot | HTTP 및 WebSocket 서버가 바인딩할 IP 주소입니다. |
communication/bind_all_interfaces | bool | boot | localhost 대신 서버를 0.0.0.0에 바인딩합니다. |
communication/http/port | int | boot | HTTP REST API 포트(기본값 10000). |
communication/websocket/port | int | boot | 기본 v3.1 WebSocket 포트(기본값 10001). |
communication/websocket/legacy_port | int | boot | 레거시 v3.0 WebSocket 포트(기본값 10000). |
communication/events/port | int | boot | 이벤트 스트림 WebSocket 포트(기본값 10020). |
devices/…
devices/detection/…
시리얼 포트 스캔 정책입니다. 모든 항목은 고급(advanced) 설정입니다.
| 키 | 타입 | 제약 조건 | 설명 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 범위 100–10000; 부팅 시 | 시리얼 포트 스캔 간격(ms). |
devices/detection/handshake_timeout_s | int | 범위 1–15 | 포트별 핸드셰이크 타임아웃(s). |
devices/detection/max_retries | int | 범위 1–10 | 포트별 최대 핸드셰이크 재시도 횟수. |
devices/detection/failure_log_delay_s | int | 범위 1–60 | 감지 실패를 다시 기록하기 전의 지연 시간(s). |
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의 마운트 변환, basis 등). |
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 | — | 안전 궤적(safe-trajectory) 속도 제한기를 활성화합니다. |
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–10000 | 강제 재알림 사이의 간격(ms)입니다. |
features/verse_grip_pairing/force_attached | bool | — | 홀 센서를 우회하여 연결 상태를 true로 영구 고정합니다(하드웨어 장애 우회용). |
session/serialization/…
Transform 출력 형식 — WebSocket 및 HTTP JSON 페이로드에 영향을 미칩니다. 이 키들은 세션별 범위를 반영하기 위해 3.5.1 버전에서 serialization/*에서 session/serialization/*로 이동되었습니다. 기존 경로는 지원 중단(deprecated) 별칭을 통해 여전히 해석됩니다.
| 키 | 타입 | 제약 조건 | 설명 |
|---|---|---|---|
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 버전에서 도입되었습니다 — 아래의 네 개 rate/websocket/* 키는 이전에 session/commands/* 아래에 있었으며, 기존 경로는 지원 중단(deprecated) 별칭을 통해 여전히 해석됩니다.
| 키 | 타입 | 제약 조건 | 설명 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 제로 차수 홀드(zero-order-hold) 윈도우 — 이 윈도우 내에 수신된 프로브를 억제합니다(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/*(오일러 쿼터니언 출력 및 Wireless VerseGrip 라우팅 등 출시 전 직렬화 실험)입니다. 디버깅을 위해 misc/hidden_settings를 통해 접근할 수 있지만, 이후 마이너 버전에서 승격, 이름 변경 또는 제거될 수 있으므로 클라이언트 동작을 이 설정에 고정하지 마십시오.