본문으로 건너뛰기

v3.5.0

이는 1년 전 API 개편 이후 가장 큰 규모의 릴리스입니다. 3.5.0 버전에서는 통합된 3D 수학 레이어,Minverse 에 대한 완벽한 지원, 타입이 지정된 이벤트 스트림, 완전한 설정 API, 그리고 더욱 간소화된 HTTP 인터페이스가 도입되었습니다. 또한, 지난 1년 동안의 버그 수정 사항과 사용 편의성 개선 사항도 포함되어 있습니다.

하이라이트​

  • 통합된 3D 수학 레이어 — 합성이 가능한 변환 파이프라인을 통해, 디바이스의 베이스(프레임), 마운트 변환, 작업 공간 변환, 내비게이션 변환을 위한 최상위 프리미티브를 제공할 뿐만 아니라, 로컬, 세션, 애플리케이션, 내부 공간 간의 명시적 변환도 지원합니다.
  • 버블 내비게이션 — 형태를 가진 영역(SDF 프리미티브)을 통해 대규모 가상 작업 공간 내에서 이동할 수 있습니다. 속도 매핑을 통한 속도 제어, 히스테리시스를 고려한 충돌 감지, 선택 사항인 커서 방향으로의 드리프트 기능을 지원합니다. HTTP 및 WebSocket을 통해 완벽하게 구성할 수 있으며, 앱 공간 내 왕복 통신도 지원합니다.
  • 형식 지정 이벤트 스트림 — 장치의 수명 주기, 안전 경고, 보정, 배터리, 제어 속도 경고 및 권장되지 않는 사용 방법에 대한 정보를 다루는 전용 WebSocket 이벤트 채널입니다.
  • 설정 API — HTTP 기반 CRUD, 타입 힌트, 범위 제약 조건, 설명을 갖춘 완전한 키-값 설정 시스템입니다. 기존의 중첩된 설정 파일을 대체합니다.
  • 장치 설정의 일관성 — 모든 기기에서 공통 HTTP 경로를 사용합니다:basis、mount、preset、transform、filters、handedness、torque_scaling、gravity_compensation、home_return。
  • Minverse 펜과 기기의 동기화 보정 — 이제 기기와 펜을 함께 보정할 수 있습니다. 그립이 물리적으로 장착될 때까지 보정 기능은 잠긴 상태로 유지됩니다.
  • HTTP 사용 편의성 향상 — 인덱스 기반 장치 선택기(ID가 필요 없으며, 인덱스로 장치를 지정할 수 있음), WebSocket과 공통된 요청/응답 형식, 옵트인 방식의 {ok, error, data} 엔벨로프（?format=json), 와일드카드 세션 선택기를 탑재했습니다.

새로운 기능​

장치​

  • Minverse — 이번 릴리스에서 다음 워크플로우에 대한 공식 지원이 추가되었습니다: 탐지, 준비 완료 시퀀스, 안전 알림, 동기화 보정.
  • 이제 ‘Ruko ’와 ‘Kingfisher’ 를 공식 그립 제품 유형으로 인정하게 되었습니다.
  • 기기 시뮬레이터 지원 — 실제 기기와 더불어, 소프트웨어로 시뮬레이션된 기기를 감지하고 통신할 수 있습니다.
  • 연결 루프 보호 — 비정상적으로 작동하는 포트는 자동으로 차단됩니다.POST /ports/{port}/reset 에서 재설정할 수 있습니다.
  • 펜 장착 하트비트 — 채터링 방지(데바운스) 기능이 탑재되어 있어, 그립의 장착 및 탈착을 정확하게 감지합니다.

세션, 명령어, WebSocket​

  • 세션 프로필의 필터링 및 영구 저장 — 세션은 프로필 이름과 필요한 SDK 버전을 선언합니다. 서비스는 재연결 시에도 이를 기억하며, 클라이언트나 모니터링 도구는 해당 프로필을 기반으로 세션을 필터링하거나 지정할 수 있습니다.
  • 세션별 명령어 버퍼 — 처리 속도가 느린 세션이 다른 세션의 진행을 방해하지 않게 되었습니다.
  • 원샷 명령어를 위한 명시적인 configure 지도 — 기기별 basis、preset、mount、force_gate、damping, 그리고 세션별 profile 그리고 basis 하지만 모두 configure 로 정리되었습니다. 출력 설정 맵과 일치하도록 조정했기 때문에, 전송한 내용을 다시 불러왔을 때 일치합니다.
  • 사용자 정의가 가능한 기기 거치대 — 내장된 작업 공간 사전 설정 (defaults、arm_front、arm_front_centered、led_front、led_front_centered) 중에서 선택하거나 명시적인 변환을 전송할 수 있습니다. 마운트를 수동으로 변경하면 프리셋은 자동으로 custom 로 전환됩니다.
  • 이름이 지정된 명령어 필드 — 범용의 values 배열 대신,position、vector、angles、torques 를 사용합니다.
  • set_angular_torques 하지만 set_angular_torque 로 바뀌었습니다(단수형은 권장하지 않습니다).
  • 세션 프레임의 확장 — v3.0과 v3.1의 세션 프레임이 확장 가능한 config、state、status 이제 객체를 갖게 되었습니다. 새로운 출력 필드에는,current_cursor_force、current_cursor_position、current_angular_torques、current_angular_position、control_domain、control_mode、transform、transform_velocity, 보다 자세한 config.*, 그리고 status.safety(기본적으로 숨김)이 포함됩니다.
  • 변환의 부분 업데이트 — 마운트, 작업 공간 변환, 탐색 형상과 관련하여 변경하고자 하는 하위 필드(position、rotation、scale）만 전송할 수 있습니다.

HTTP​

  • GET / — 서비스 버전.
  • GET/POST/DELETE /settings 그리고 /settings/* — 완벽한 키-값 설정 API.
  • GET /sessions/{session} 그리고 GET/POST/DELETE /sessions/{session}/profile。
  • GET /devices?session=<selector> — 장치의 좌표를 지정된 세션의 애플리케이션 공간으로 변환합니다.
  • 인덱스 기반 장치 선택기 — ID를 지정하지 않고 인덱스를 통해 어떤 장치든 지정할 수 있습니다(첫 번째 Inverse3 는 /inverse3/0/...、Inverse 계열의 모든 디바이스는 /inverse*/*/...).
  • 표준화된 요청/응답 형식 — POST/GET의 본문은 WebSocket과 동일합니다 command_data JSON 형식을 사용합니다. 한 전송 방식을 위해 작성된 코드는 다른 전송 방식에서도 작동합니다.
  • 옵트인 봉투 — 임의의 경로를 통해 ?format=json 을 지정합니다./settings* 그리고 GET /home_return 의 기본값은 {ok, error, data} 입니다. 원본 형식을 사용할 경우 ?format=plain 을 지정합니다.
  • 세션 선택자의 와일드카드 — 프로필 이름에서는,*(임의의 문자열)과 ?(임의의 1자)를 사용할 수 있습니다.
  • 퍼센트 디코딩된 선택자 — %2A、%3A 등은 라우팅 전에 디코딩됩니다.

이벤트​

  • communication/events/port 위의 전용 WebSocket 이벤트 스트림.
  • 장치의 수명 주기, 안전성(긴급 제동, 이물질 감지, 정지), 보정 실패, 배터리 경고, 세션 경고, 낮은/위험한 제어 속도, 입력 검증, 권장되지 않는 팁 등을 포함한 24가지 유형의 이벤트 범주.

관측 가능성​

  • 프로파일링 시, 로그 메시지는 수준에 따라 색상이 지정되어 Tracy로 전송됩니다.
  • 모든 HTTP 핸들러에 Tracy 영역을 설정합니다.
  • 메인 루프의 타이밍 통계 이벤트.
  • 로그 디렉터리와 서버 호스트 이름을 설정할 수 있습니다(Docker 지원).

3.6 버전에서 제공 예정​

  • SDF 촉각 효과(SDF HFX) — 3.5 버전에서 기반 기능이 도입되었습니다(모듈, 라이프사이클, 모듈이 제공하는 명령어/상태의 직렬화). 공개 API는 3.6 버전에서 완전한 문서와 함께 출시될 예정입니다.

개선 사항​

  • 힘 기반 진동 필터링 — 축별 진동 감지, 8단계 점진적 복구, 히스테리시스를 적용한 진입 투표, 비대칭 릴리스 윈도우.
  • 런타임 파워 게이트 필터 — configure.force_gate.gain(WebSocket 또는 HTTP를 통해) 설정할 수 있습니다. 영구적인 기본값이 있습니다.
  • 정밀 용도를 위해 메인 루프의 최대 주파수를 32 kHz로 높였습니다.
  • WebSocket 페이로드의 크기 축소 — 항등 변환을 기본값으로 하는 변환의 하위 필드(position = 0、rotation = identity、scale = 1)는 기본적으로 출력에서 생략됩니다. 이를 통해 페이로드 크기가 줄어들며, 구형 Unity 패키지의 4KB 메시지 제한과의 호환성이 회복됩니다. 두 가지 고급 설정(serialization/explicit_fields、serialization/force_complete_transforms）를 사용하면 필요한 소비자를 대상으로 모든 필드를 복원할 수 있습니다.
  • 메인 루프의 지터 감소 — JSON 파싱 및 네트워크 전송 중에도 WebSocket 메시지 처리가 메인 루프의 틱을 더 이상 차단하지 않게 되었습니다. 세션 틱의 스케줄링이 응답 직렬화 단계보다 앞당겨졌습니다.
  • 서버는 기본적으로 로컬 호스트만 허용합니다. — 네트워크 액세스를 활성화하려면,communication/bind_all_interfaces 설정에서 동의해 주세요.
  • 장치 선택기의 와일드카드에서 접두사 구문 사용(예:inverse* (Inverse 계열의 모든 기기와 호환됨).
  • 덤핑 명령어 를,force_gate 이와 더불어 configure 지도로 이동했습니다.
  • 로테이션 기능이 포함된 파일 로거가 기존 버전으로 대체되었으며, 이제 디렉터리를 설정할 수 있게 되었습니다.
  • 모듈이 제공하는 명령어 및 상태 — 모듈은 코어 스키마를 변경하지 않고도 고유한 명령어와 필드를 설정하고, 상태 출력 정보를 WebSocket 프레임에 포함시킬 수 있습니다.

수정​

1년 치의 버그 수정 사항입니다. 영향이 큰 사항들은 다음과 같습니다.

  • 특정 조건에서세션 속도가 불안정해지는문제.
  • 시뮬레이션이 실행되지 않을 경우, **GripHook(Verse Grip Stopper)**가 제대로 해제되지 않는 문제.
  • Inverse3의 타임아웃시간이 너무 짧아, 부팅 속도가 느린 기기에서 연결 끊김 루프가 발생하던 문제.
  • Windows에서 서비스가 완전히 종료되지 않는 문제 — 시스템을 종료할 때 HTTP 서버가 항상 정리되지는 않는 문제.
  • 서비스가 지원되지 않는 명령을 구형 펌웨어 버전에 전송했을 때 발생하는재연결 루프.
  • 블루투스 어댑터가 탑재된 시스템에서블루투스 장치 열거시 대량의 로그가 출력되는 문제.
  • 서비스를 연속으로 여러 번 재시작했을 때 발생하는 충돌.
  • Ubuntu 노트북에서 절전 모드에서 복귀한 후Wireless Verse Grip 동글이 멈추는 문제.
  • Linux 및 macOS에서 Wireless Verse Grip의 핸드셰이크 기능이, 첫 번째 탐지 시도가 실패할 경우 올바르게 대체 방식으로 전환되도록 개선되었습니다.
  • macOS 설정 파일의 위치 — 설정은 잘못된 경로가 아니라~/Library/Application Support/에 저장되게 되었습니다.
  • Linux 및 macOS에서의 SIGSEGV 신호 처리 — 멀티스레드 크래시 캡처가 활성화된 경우, 프로세스가 치명적인 신호로 인해 무한 루프에 빠지지 않게 되었습니다.
  • 세션 간 명령어 덮어쓰기 — 특정 세션의 설정 명령어가 다른 세션의 명령어에 의해 사용자에게 알리지 않은 채 덮어쓰어지는 문제가 있었으나, 현재는 올바르게 필터링 및 병합되도록 수정되었습니다.
  • 프로브 명령을 통한 설정 덮어쓰기 — probe_position모니터링 세션(예:Haply Hub)이 보류 중인 basis/preset/profile 변경 사항을 인식하지 못한 채 이를 덮어쓰지 않게 되었습니다.
  • 프로토타입 그립 표시 — 프로토타입 하드웨어가 사용자 지정 그립이 아닌 표준 그립으로 잘못 표시되던 문제.
  • 이전하지 않은 클라이언트를 위해,레거시의set_basis행렬의 성질이 다시 활성화되었습니다.
  • 세션이끊어질때 Inverse3의 포스 킥으로 인해잔류 포스 스파이크가 발생하지 않게 되었습니다.
  • 웹소켓연결이 빠르게 반복적으로 연결 및 끊어지는 과정에서 발생하는연결 손실 경합.
  • 일부 전송 페이로드에서 **WebSocket의session_id**가0시리얼라이즈되어 있던 문제.
  • Windows에서는,--dev와 함께 사용할 경우에도--log-level이 변경 사항이 반영되게 되었습니다(이전에는 모르는 사이에debug로 재설정되어 있었습니다).

권장하지 않음​

계속해서 작동하지만, 향후 메이저 버전 업데이트 시 제거될 예정입니다. 해당되는 경우, 응답에는deprecation_warning필드가 포함됩니다.

권장하지 않음대신
POST /force_scalePOST /settings/devices/inverse*/filters/force_scale/gain
POST /gravity_compensationPOST /{device}/{id}/config/gravity_compensation
POST /torque_scalingPOST /{device}/{id}/config/torque_scaling
POST /device_handednessPOST /{device}/{id}/config/handedness
POST /serial_enablePOST /settings/communication/serial/enabled
POST /experimental/features/grip_dropped_simulation_stopper설정 API
POST /experimental/features/screensaver_enable설정 API
웹소켓 command_data.valuesposition, vector, angles, torques
웹소켓 set_angular_torqueset_angular_torques
웹소켓 probe_cursor_positionprobe_position
웹소켓 set_coordinate_originconfigure.preset
WebSocket 세션 수준의set_basisconfigure.basis

호환성에 관한 주의사항​

3.4.19 버전부터는 호환성을 깨는 변경 사항이 없습니다. 기존 연동과 관련하여 주의해야 할 사소한 사항은 다음 두 가지입니다:

  1. 더 이상 권장되지 않는 HTTP 엔드포인트는 응답에deprecation_warning필드가 추가되었습니다. 응답 스키마를 엄격하게 검증하는 클라이언트는 이 추가 필드를 허용해야 합니다.
  2. WebSocket의command_data에 있는values이 필드는 더 이상 권장되지 않지만, 계속해서 분석 대상에 포함됩니다. 명명된 필드를 사용하는 것이 좋습니다.

튜토리얼 및 문서​

  • 새로운 튜토리얼: 05 위치 제어, 06 복합(Inverse3 + Verse Grip), 07 기초 및 장착, 08 HTTP 원격 구성기, 09 WebSocket 원격 제어, 10 이벤트 스트림 리스너.
  • 기존의 nlohmann/json 변형과 더불어, 모든 C++ 튜토리얼에 새로운 Glaze 변형(cpp-glz/)가 추가되었습니다.
  • 모든 튜토리얼을 다시 작성하기、v3.1 API를 지원하게 되었습니다(포트 10001,configure.preset、이름이 지정된 명령어 필드,print_state()(도우미).
  • 이전 ‘Verse Grip Stopper’ 튜토리얼을 삭제했습니다. 새로운 ‘Combined’ 튜토리얼로 대체되었습니다.
  • 공개 문서를업데이트했습니다. 업데이트 대상은 SDK 가이드, API 참조 문서, 그리고 하드웨어 페이지 전체입니다.