설정 참고 사항
이 문서에는 다음 내용이 나열되어 있습니다. /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 'advanced'로 표시된 설정을 포함할 수 있으며, 다음을 전달합니다. ?deprecated=true 더 이상 사용되지 않는 별칭을 포함할 수 있습니다. 숨김 설정은 내부 용도로만 사용되며, 오직 다음을 통해서만 POST /settings/misc/hidden_settings 설정 misc/hidden_settings 그 후에 표시됩니다(해당하는 쿼리 매개변수가 없는 경우). 필터 플래그 간에는 논리적 ‘AND’ 관계가 적용되며, 즉 동시에 다음으로 표시된 경우 advanced 와 hidden 해당 키를 사용하려면 두 가지 제한 조건이 동시에 충족되어야 합니다. 알려진 키에 대해 POST 및 DELETE 작업을 수행하는 경우에는 위의 제한 사항이 적용되지 않습니다.
정확한 스펙 키를 사용하여 단일 키 읽기 수행 (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 | 부팅 | HTTP 및 WebSocket 서버가 바인딩된 IP 주소. |
communication/bind_all_interfaces | bool | 부팅 | 서버를 다음 위치에 바인딩합니다. 0.0.0.0 localhost가 아니라. |
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/…
직렬 포트 스캔 정책. 모든 항목은 고급 설정(advanced)입니다.
| 키 | 유형 | 제약 | 설명 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 범위 100–10000; 시작 시 적용됨 | 시리얼 포트 스캔 간격(밀리초). |
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 | 장치 제어 잠금을 해제하기 전까지의 시간 초과 기간(밀리초). |
devices/*inverse/query_orientation_on_idle | bool | — | 장비가 유휴 상태일 때 펌웨어를 통해 기체 자세를 조회합니다. |
devices/*inverse/safeties/expose_in_snapshot | bool | — | 에서 GET /devices/{id} 스냅샷에는 각 장치의 보안 태그가 포함되어 있습니다. |
devices/presets
| 키 | 유형 | 제약 | 설명 |
|---|---|---|---|
devices/presets | json | — | 각 장치 유형에 대한 기본 장치 구성 프리셋(설치 변환, basis 등 포함, 다음의 경우에 적용됨) 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 | — | 그립이 수직으로 세워진 상태에서 grip-hook 자동 잠금 기능이 활성화됩니다. |
features/grip_hook/use_hall | bool | — | 자세 대신 홀 센서의 임계값을 사용하여 그립 감지를 수행합니다. |
features/grip_hook/hall | int | 범위 1–32 | 그립 잠금을 작동시키는 홀 센서의 수치 임계값. |
features/grip_hook/hold_duration | int | 범위 10–1000 | 트리거된 후 잠금 상태가 유지되는 시간(밀리초). |
features/navigation/bubble/…
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 허브 페어링 인터페이스를 지원합니다.
| 키 | 유형 | 제약 | 설명 |
|---|---|---|---|
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/…
변환 출력 형식——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 | — | 각 transform 출력에는 항상 다음이 포함됩니다. position、rotation 와 scale, 여기에는 자세 정보만 제공하는 기기(Verse Grip, Wireless Verse Grip)도 포함되며, 이러한 기기들은 원래는 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/* 아래; 이전 경로는 더 이상 사용되지 않는 별칭을 통해 계속 해석됩니다.
| 키 | 유형 | 제약 | 설명 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 0차 유지(ZOH) 창: 이 창 내에서 수신된 탐지 메시지를 억제합니다(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 디버깅을 위해 제공되지만, 향후 마이너 버전에서 정식 설정으로 전환되거나 이름이 변경되거나 제거될 수 있으므로, 클라이언트 동작을 이에 의존하지 마십시오.