v3.5.0

이번 릴리스는 1년 전 API 재구축 이후 가장 규모가 큰 릴리스입니다. 3.5.0 버전에서는 통합된 3D 수학 레이어, 완벽한 ‘ Minverse ’ 지원, 형식이 지정된 이벤트 스트림, 완벽한 설정 API, 더욱 간결해진 HTTP 인터페이스가 도입되었으며, 지난 1년 동안의 버그 수정 및 사용자 경험 개선 사항도 포함되어 있습니다.

하이라이트

• 통합된 3D 수학 계층 —— 조합 가능한 변환 파이프라인으로, 장치 기준 좌표계(basis/frame), 마운트 변환(mount transform), 작업 공간 변환(workspace transform) 및 내비게이션 변환(navigation transform)에 대한 1급 원시 연산을 제공하며, 로컬, 세션, 애플리케이션 및 내부 공간 간의 명시적 변환을 지원합니다.
• 버블 내비게이션(Bubble Navigation) —— 형성 영역(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。
• 명명된 명령 필드 —— position、vector、angles、torques 범용 제품을 대체하여 values 배열.
• 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。
• 세션 선택자 와일드카드 —— 프로필 이름 중 *(임의의 문자열) 및 ?(단일 문자).
• 퍼센트 기호 인코더 선택기 디코딩 —— %2A、%3A 등은 라우팅 전에 먼저 디코딩됩니다.

사건

• ~에 위치한 communication/events/port 의 전용 WebSocket 이벤트 스트림.
• 총 24가지 유형의 이벤트가 있으며, 여기에는 장치 수명 주기, 안전 이벤트(전자 브레이크(e-brake), 이물질 감지, 동력 차단), 보정 실패, 배터리 경보, 세션 경고, 제어 속도 저하/심각한 저하, 입력 검증 및 사용 중단 알림이 포함됩니다.

관측 가능성

• 성능 분석 시, 로그 메시지는 Tracy로 전달되며 로그 수준에 따라 색상이 지정됩니다.
• 각 HTTP 처리 함수에 Tracy 영역을 추가합니다.
• 메인 루프의 타이머 및 통계 이벤트.
• 로그 디렉터리와 서버 호스트 이름을 구성할 수 있습니다(Docker에서 사용하기 편리하도록).

3.6 버전이 곧 출시될 예정입니다

• SDF 촉각 효과(SDF HFX) —— 3.5 버전에서 기본 작업(모듈, 라이프사이클, 모듈이 제공하는 명령/상태 직렬화)이 완료되었으며, 공개 API 및 전체 문서는 3.6 버전과 함께 공개될 예정입니다.

개선

• 힘 진동 필터링 —— 축별 진동 감지, 8단계 점진적 복구, 히스테리시스를 적용한 진입 투표, 비대칭 릴리스 윈도우.
• 실행 시 전력 제어 필터 —— 다음을 통해 configure.force_gate.gain WebSocket 또는 HTTP에서 구성되며, 지속성이 있는 기본값이 제공됩니다.
• 메인 루프의 최대 주파수가 32 kHz로 향상되어고정밀도 응용 분야에 적합합니다.
• 더 작은 WebSocket 페이로드 —— 항등식(identity)의 기본값에 대한 변환 하위 필드(position = 0、rotation = identity、scale = 1) 더 이상 기본적으로 출력되지 않아, 부하 용량을 줄이고 이전 버전의 Unity 데이터 패킷 4KB 메시지 상한선과의 호환성을 복원합니다. 두 가지 고급 설정(serialization/explicit_fields、serialization/force_complete_transforms）필요한 사용자에게 모든 필드를 다시 활성화할 수 있습니다.
• 메인 루프 지터 감소 —— WebSocket 메시지 처리가 JSON 파싱 및 네트워크 전송 중에 메인 루프의 리듬을 더 이상 차단하지 않습니다. 세션 리듬 스케줄링이 응답 직렬화 단계 이전으로 이동되었습니다.
• 서버는 기본적으로 localhost에서만 연결 요청을 수신합니다. —— 인터넷 접속이 필요하신 경우, 다음을 통해 communication/bind_all_interfaces 설정을 켭니다.
• 장비 선택기의 와일드카드가 접두사 구문으로 변경됨(예를 들어 inverse* (모든 Inverse 시리즈 기기와 호환됩니다).
• 감쇠 명령 이동됨 configure 매핑 중, ~와 force_gate 한데 모아 두세요.
• 회전 파일 로거는 기존 로거를 대체하며, 구성 디렉터리를 지원합니다.
• 모듈이 제공하는 명령어와 상태 —— 모듈은 핵심 스키마를 수정할 필요 없이 자체 명령어와 구성 필드를 주입하고, 상태를 WebSocket 프레임에 기록할 수 있습니다.

수정

일 년 동안의 결함 수정 내역; 그중 가장 큰 영향을 미친 수정 사항은 아래에 나열되어 있습니다.

• 대화 속도가 비정상적이며, 특정 조건에서 발생합니다.
• **GripHook(Verse Grip Stopper)**는 시뮬레이션이 실행 중이지 않을 때 제대로 해제되지 않습니다.
• Inverse3 타임아웃설정이 지나치게 엄격하여, 시작 속도가 느린 기기가 연결 끊김 루프에 빠지게 됩니다.
• Windows에서 서비스가 제대로 종료되지 않습니다. 시스템을 종료할 때 HTTP 서버가 항상 정리되는 것은 아닙니다.
• 재연결 루프— 서비스가 구형 펌웨어 버전에 지원되지 않는 명령을 전송할 때 발생합니다.
• 블루투스어댑터가 장착된 시스템에서는 블루투스 장치 열거 과정에서대량의 로그가 기록됩니다.
• 서비스를 연속으로 여러 번 재시작할 때 충돌이 발생합니다.
• Ubuntu 노트북이 절전 모드에서 깨어나거나 다시 절전 모드로 들어갈 때 무선 Verse Grip 수신기가 응답하지 않습니다.
• Linux 및 macOS에서 무선 Verse Grip은첫 번째 감지 시도가 실패한 후 이제 올바르게 원래 상태로 되돌아갑니다.
• macOS 프로파일 위치——구성은 현재 다음 위치에 저장되어 있습니다. ~/Library/Application Support/ 이 과정에서 더 이상 잘못된 경로를 사용하지 않습니다.
• Linux 및 macOS에서의 SIGSEGV 신호 처리— 다중 스레드 크래시 캡처를 활성화하면 프로세스가 치명적인 신호로 인해 무한 루프에 빠지지 않게 됩니다.
• 세션 간 명령어 덮어쓰기— 한 세션의 구성 명령어가 다른 세션의 명령어에 의해 은밀하게 대체될 수 있었으나, 이제 올바르게 필터링되고 병합됩니다.
• 탐지 명령어 범위 구성——모니터링 세션(예: Haply Hub)에서 전송 probe_position 이때, 적용 대기 중인 basis/preset/profile 변경 사항을 더 이상 은밀하게 덮어쓰지 않습니다.
• 프로토타입 그립 표시 오류— 프로토타입 하드웨어가 사용자 지정 그립이 아닌 표준 그립으로 잘못 표시됩니다.
• 이전 버전 set_basis 행렬 규칙아직 마이그레이션되지 않은 클라이언트에 대해 다시 적용됩니다.
• Inverse3 '포스 킥'은 세션이 끊어질 때 더 이상 잔류 힘의 피크를 발생시키지 않습니다.
• WebSocket 연결 손실 경쟁 조건— 빠른 연결/단절 반복 과정에서 발생합니다.
• 웹소켓 session_id 일부 아웃바운드 트래픽에서 다음과 같이 시리얼라이즈됨 0。
• Windows에서 다음을 동시에 사용하려면 --dev 현재는 다음을 따릅니다 --log-level(이전에는 조용히 재설정되어 debug).

사용 중단 항목

여전히 정상적으로 사용할 수 있지만, 향후 주요 버전에서 제거될 예정입니다. 해당되는 경우, 응답에 다음 내용이 포함됩니다. deprecation_warning 필드.

사용 중단됨	대안
POST /force_scale	POST /settings/devices/inverse*/filters/force_scale/gain
POST /gravity_compensation	POST /{device}/{id}/config/gravity_compensation
POST /torque_scaling	POST /{device}/{id}/config/torque_scaling
POST /device_handedness	POST /{device}/{id}/config/handedness
POST /serial_enable	POST /settings/communication/serial/enabled
POST /experimental/features/grip_dropped_simulation_stopper	설정 API
POST /experimental/features/screensaver_enable	설정 API
웹소켓 command_data.values	position, vector, angles, torques
웹소켓 set_angular_torque	set_angular_torques
웹소켓 probe_cursor_position	probe_position
웹소켓 set_coordinate_origin	configure.preset
WebSocket 세션 수준 set_basis	configure.basis

호환성 안내

3.4.19 버전과 비교했을 때, 강제적이고 파괴적인 변경 사항은 없습니다. 기존 통합과 관련하여 두 가지 주의 사항이 있습니다:

1. 더 이상 사용되지 않는 HTTP 엔드포인트는 이제 응답에 다음을 포함합니다. deprecation_warning 필드——응답 스키마를 엄격하게 검증하는 클라이언트는 이 추가 필드를 허용해야 합니다.
2. 웹소켓 command_data 중의 values 이 필드는 더 이상 사용되지 않지만 여전히 파싱됩니다. 명명된 필드를 우선적으로 사용하는 것이 좋습니다.

튜토리얼 및 문서

• 새로 추가된 튜토리얼: 05 위치 제어, 06 조합(Inverse3 + Verse Grip), 07 기준점 및 설치, 08 HTTP 원격 구성기, 09 WebSocket 원격 제어, 10 이벤트 스트림 리스너.
• 각 C++ 튜토리얼에 Glaze 변형을 추가(cpp-glz/), 기존의 nlohmann/json 변형과 병행하여 사용됩니다.
• 모든 튜토리얼이 v3.1 API에 맞춰 재작성되었습니다.(포트 10001,configure.preset、명명된 명령어 필드、print_state() (보조 함수).
• 기존의Verse Grip Stopper 튜토리얼을 삭제하고, 새로운 통합 튜토리얼로 대체했습니다.
• 공개 문서가업데이트되었으며, 여기에는 SDK 가이드, API 참조 및 하드웨어 페이지가 포함되어 있습니다.