본문으로 바로 가기

설정 참조

이 문서는 /settings/ 엔드포인트가 반환하는 모든 설정을 키, 유형(type_hint (기준), 제약 조건(metadata.constraint.range 및 해당되는 경우 locked (기준)과 함께 나열합니다.

locked 설정은 실행 시 읽기 전용입니다. 구성 파일이나 Haply Hub 설정 페이지를 통해 변경할 수 있지만, 변경 사항이 적용되려면 서비스 전체를 다시 시작해야 합니다. 아래 표에서 이러한 설정은 부팅로 표시됩니다.

구성​

서비스 시작 시 설정을 재정의하는 구성 파일의 위치는 다음과 같습니다:

플랫폼위치
WindowsC:\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
}

타입 매핑​

API가 반환하는 타입 힌트는 다음 JSON 형식으로 매핑됩니다:

  • STRING → string
  • BOOL → bool
  • INT → int
  • FLOAT → float
  • ARR_STRING → string[]
  • VEC3 → vec3 ({x, y, z}(를 가진 객체)
  • GENERIC → json (임의의 구조화된 값)

communication/…​

HTTP, WebSocket 및 이벤트 스트림 서버의 네트워크 포트와 바인드 주소입니다. 대부분의 항목은 부팅 시에만 설정할 수 있습니다.

키유형제약 조건설명
communication/serial/enabledbool—시리얼 장치 통신을 활성화하거나 비활성화합니다.
communication/bind_addressstring부팅 시HTTP 및 WebSocket 서버가 바인딩하는 IP 주소입니다.
communication/bind_all_interfacesbool부팅 시localhost 대신 0.0.0.0서버에 바인딩합니다.
communication/http/portint부팅 시HTTP REST API 포트(기본값 10000)입니다.
communication/websocket/portint부팅 시기본 v3.1 WebSocket 포트(기본값 10001)입니다.
communication/websocket/legacy_portint부팅 시레거시 v3.0 WebSocket 포트(기본값 10000)입니다.
communication/events/portint부팅 시이벤트 스트림 WebSocket 포트(기본값 10020)입니다.

devices/…​

devices/detection/…​

이것은 시리얼 포트 스캔 정책입니다. 모든 항목은 고급 설정입니다.

키유형제약 조건설명
devices/detection/scan_period_msint범위 100–10000; 부팅 시직렬 포트 스캔 간격(ms)입니다.
devices/detection/handshake_timeout_sint범위 1–15포트별 핸드셰이크 제한 시간(초)입니다.
devices/detection/max_retriesint범위 1–10포트당 최대 핸드셰이크 재시도 횟수입니다.
devices/detection/failure_log_delay_sint범위 1–60감지 실패를 다시 기록하기 전까지의 지연 시간(초)입니다.
devices/detection/block_looping_portsbool—루핑 포트가 감지되면 장치의 준비 상태를 차단합니다.
devices/detection/excluded_portsjson—감지 중에 건너뛸 직렬 포트 경로입니다.
devices/detection/additional_portsstring[]—조건 없이 스캔할 추가 시리얼 포트 경로입니다.
devices/detection/allowed_vendor_id_filterstring[]—포트 열거 시 허용되는 USB 벤더 ID입니다.
devices/detection/port_name_substring_filterstring[]—일치시킬 플랫폼별 포트 이름의 일부 문자열입니다.
devices/detection/wireless_verse_grip_description_filterstring[]—무선 VerseGrip 감지를 위한 포트 설명의 일부 문자열입니다.
devices/detection/inverse3x_description_filterstring[]—Inverse3x 감지를 위한 포트 설명의 일부 문자열입니다.
devices/detection/extra_ports (사용 중단됨)string[]—대신 devices/detection/additional_ports를 사용하십시오. 읽기 및 쓰기 작업은 표준 키를 통해 투명하게 전달됩니다.

devices/inverse*/…​

Inverse3 이 계열의 모든 장치에 적용되는 전역 기본값입니다. 세션별 재정의가 우선합니다.

키유형제약 조건설명
devices/inverse*/filters/force_scale/gainfloat범위 0.0–2.0모든 장치에 적용되는 전역 힘 출력 배율입니다.
devices/inverse*/filters/force_gate/gainfloat범위 0.0–1.0새 세션의 기본 힘 게이트 이득입니다.
devices/inverse*/control_timeout_msint범위 50–10,000장치 제어 잠금이 해제되기 전까지의 제한 시간(ms)입니다.
devices/inverse*/query_orientation_on_idlebool—장치가 유휴 상태일 때 펌웨어에서 본체의 방향을 확인합니다.

devices/presets​

키유형제약 조건설명
devices/presetsjson—장치 유형별 기본 장치 구성 프리셋입니다(inverse_arm_front_*, inverse_led_front_*, minverse_*, verse_grip_default, wireless_verse_grip_default, custom_verse_grip_default(마운트 변환(mount transform), 기저 등).

devices/wireless_verse_grip/…​

키유형제약 조건설명
devices/wireless_verse_grip/battery/low_thresholdint—배터리 잔량(%)이 이 값보다 낮아지면 배터리 부족 경고가 표시됩니다.
devices/wireless_verse_grip/battery/critical_thresholdint—배터리 잔량(%)이 이 값보다 낮아지면 배터리 위험 알림이 표시됩니다.
devices/wireless_verse_grip/battery/reset_marginint—배터리 경고를 해제하기 전의 히스테리시스 여유값입니다.
devices/wireless_verse_grip/filters/orientation_filterjson부팅 시무선 VerseGrip 방향에 대한 One Euro Filter 설정입니다.

features/…​

features/calibration/…​

키유형제약 조건설명
features/calibration/hall_thresholdint범위 1–32이 수준은 보정 중에 펜이 부착된 것으로 간주되는 홀 센서의 위치입니다.

features/grip_hook/…​

그립 후크가 자동으로 작동합니다. 그립을 똑바로 세워 잡고 있는 동안 커서가 고정됩니다.

키유형제약 조건설명
features/grip_hook/enabledbool—그립을 똑바로 세워 잡았을 때 그립 후크 자동 잠금 기능이 활성화됩니다.
features/grip_hook/use_hallbool—그립 감지 시 방향 대신 홀 센서 임계값을 사용합니다.
features/grip_hook/hallint범위 1–32그립 잠금을 작동시키는 홀 센서 값의 임계값입니다.
features/grip_hook/hold_durationint범위 10–1000트리거 발생 후 잠금 상태를 유지하는 시간(ms)입니다.

features/navigation/bubble/…​

버블 내비게이션 모듈의 기본값입니다. bubble 동작이 처음 활성화될 때 세션에 전달됩니다.

키유형제약 조건설명
features/navigation/bubble/centervec3—버블 중심 위치의 기본값입니다.
features/navigation/bubble/max_velocityfloat—속도 영역에서 허용되는 최대 항법 속도(m/s)입니다.
features/navigation/bubble/velocity_zone_widthfloat—버블 표면 바깥쪽 속도 영역의 폭(m)입니다.
features/navigation/bubble/reset_velocity_on_entrybool—커서가 버블에 들어가면 속도를 0으로 재설정합니다.
features/navigation/bubble/spring_innerfloat—버블 중심에서의 스프링 계수(N/m)입니다.
features/navigation/bubble/spring_surfacefloat—버블 표면에서의 스프링 계수(N/m)입니다.
features/navigation/bubble/spring_outerfloat—외부 경계에서의 스프링 계수(N/m)입니다.
features/navigation/bubble/damping_innerfloat—버블 중심에서의 감쇠 계수(Ns/m)입니다.
features/navigation/bubble/damping_surfacefloat—버블 표면에서의 감쇠 계수(Ns/m)입니다.
features/navigation/bubble/damping_outerfloat—외부 경계에서의 감쇠 계수(Ns/m)입니다.
features/navigation/bubble/wall_stiffnessfloat—바깥쪽 경계에 있는 단단한 벽의 강성(N/m)입니다.
features/navigation/bubble/bump_widthfloat—버블 표면의 촉각 돌기 너비(m)입니다.
features/navigation/bubble/bump_stiffnessfloat—버블 표면의 촉각 돌기의 강성(N/m)입니다.

features/safe_trajectory/…​

엔드 이펙터의 움직임에 대한 속도 제한 장치입니다.

키유형제약 조건설명
features/safe_trajectory/enabledbool—안전 궤적 속도 제한기를 활성화합니다.
features/safe_trajectory/max_velfloat범위 0.01–2.0엔드 이펙터의 최대 허용 속도(m/s)입니다.

features/screensaver/…​

세션이 장치를 구동하지 않을 때 Inverse3 장치에서 재생되는 유휴 애니메이션입니다.

키유형제약 조건설명
features/screensaver/enabledbool—Inverse3 장치의 대기 모드 화면 보호기 애니메이션을 켭니다.
features/screensaver/speedfloat범위 0.001–0.2화면 보호기 애니메이션 속도입니다.
features/screensaver/distracted_speedfloat범위 0.001–0.2사용자가 근처에 있지만 조작하지 않을 때의 애니메이션 속도입니다.

features/sdf/…​

부호 있는 거리장(Signed-distance-field) 햅틱 효과 모듈(SDF HFX)입니다.

키유형제약 조건설명
features/sdf/enabledbool—SDF 햅틱 효과 모듈을 켜거나 끕니다.
features/sdf/state_outputbool—기본적으로 장치 출력 페이로드에 SDF 상태를 포함합니다.
features/sdf/max_countint범위 0–128활성 SDF 효과의 최대 개수입니다 (0 = 무제한).
features/sdf/events/createdbool—새로운 SDF 효과가 생성되면 이벤트를 발생시킵니다.
features/sdf/events/deletedbool—SDF 효과가 제거되면 이벤트를 발생시킵니다.
features/sdf/events/updatedbool—SDF 효과가 업데이트되면 이벤트를 발생시킵니다.
features/sdf/probe_on_zero_force/enabledbool—가해지는 힘이 0에 가까워지면 SDF 필드를 자동으로 탐색합니다.
features/sdf/probe_on_zero_force/delayfloat범위 0.001–60.0힘이 0이 된 후 자동 프로브를 시작하기 전까지의 지연 시간(초)입니다.

features/verse_grip_pairing/…​

Inverse3 및 (유선 또는 무선) Verse Grip 간의 연결/분리 상태를 추적하는 기능입니다. 이는 ‘ Haply ’ 허브 페어링 UI의 기반이 됩니다.

키유형제약 조건설명
features/verse_grip_pairing/enabledbool—페어링 / 부착-분리 추적을 활성화합니다.
features/verse_grip_pairing/hall_threshold_vgint범위 1–32유선 VerseGrip의 경우, 이 홀 레벨이 부착된 것으로 간주됩니다.
features/verse_grip_pairing/hall_threshold_wvgint범위 1–32무선 VerseGrip의 경우, 이 홀 레벨이 부착된 것으로 간주됩니다.
features/verse_grip_pairing/detach_debounce_msint범위 0–1000분리가 확정되기 전의 디바운스 구간입니다 (ms).
features/verse_grip_pairing/heartbeat_msint범위 100–10,000강제 재알림 간의 간격입니다 (ms).
features/verse_grip_pairing/force_attachedbool—홀 센서를 우회하여 부착 상태를 true로 영구적으로 고정합니다 (하드웨어 장애 우회용).

serialization/…​

Transform 출력 형식 — WebSocket 및 HTTP JSON 페이로드에 영향을 미칩니다.

키유형제약 조건설명
serialization/explicit_fieldsbool—직렬화된 출력에서 항등 기본값과 같은 transform 필드(예: position: {0,0,0}, rotation: {w:1,…})도 포함합니다. 클라이언트 측에서 모든 필드가 명시적으로 존재해야 할 때 유용합니다. 기본값: false.
serialization/force_complete_transformsbool—방향만 출력하는 장치(Verse Grip, Wireless Verse Grip)를 포함하여 모든 트랜스폼 출력에 position, rotation, 그리고 scale을 항상 포함합니다. 이 장치들은 그렇지 않으면 rotation만 출력합니다. serialization/explicit_fields의 동작을 포함합니다. 기본값: false.

session/…​

세션 스케줄러 및 명령 파이프라인의 제한 사항입니다.

키유형제약 조건설명
session/min_simulation_rate_hzint범위 20–500경고가 발생하기 전까지 허용되는 최소 장치 시뮬레이션 주기(Hz)입니다.
session/commands/zoh_window_msint—0차 홀드 윈도우 — 이 구간 내에 수신된 프로브를 억제합니다 (ms).
session/commands/drop_warning_thresholdint—경고가 발생하기 전까지 Windows 내에서 실행된 명령의 개수입니다.
session/commands/drop_warning_window_msint—드롭된 명령을 집계하는 슬라이딩 윈도우 크기입니다 (ms).
session/commands/tick_on_empty_batchbool—웹소켓 배치 전체가 삭제된 경우에도 main_loop 틱을 예약합니다.