Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
1년 전 API 개편 이후 가장 큰 규모의 릴리스입니다. 3.5.0 버전에서는 통합된 3D 수학 레이어, Minverse에 대한 완전한 지원, 형이 지정된 이벤트 스트림, 완전한 설정 API, 그리고 더욱 체계적으로 정리된 HTTP 인터페이스를 도입합니다. 또한, 지난 1년 동안의 버그 수정 및 사용 편의성 개선 사항도 포함되어 있습니다.
하이라이트 {#highlights}
통합된 3D 수학 레이어 — 장치의 기준계(프레임), 마운트 변환, 작업 공간 변환, 내비게이션 변환을 위한 최상위 프리미티브를 갖춘, 조합 가능한 변환 파이프라인입니다. 또한 로컬, 세션, 애플리케이션, 내부 공간 간에 명시적인 변환이 가능합니다.버블 내비게이션 — 형태를 가진 영역(SDF 프리미티브)을 통해 대규모 가상 작업 공간 내에서 이동할 수 있습니다. 속도 매핑을 통한 속도 제어, 히스테리시스를 고려한 충돌 감지 기능을 지원하며, 필요에 따라 커서 방향으로의 드리프트도 처리합니다. HTTP 및 WebSocket을 통해 완벽하게 구성할 수 있으며, 앱 공간 내의 왕복 통신도 지원합니다.형식 지정 이벤트 스트림 — 장치 수명 주기, 안전 경고, 보정, 배터리, 제어 속도 경고 및 권장되지 않는 사항에 대한 팁을 위한 전용 WebSocket 이벤트 채널입니다.설정 API — HTTP를 통한 CRUD, 타입 힌트, 범위 제약 조건, 설명을 지원하는 완전한 키-값 설정 시스템입니다. 기존의 중첩된 설정 파일을 대체합니다.기기 설정의 통일 — 모든 기기에서 공통으로 사용할 수 있는 HTTP 경로 한 세트를 마련해 두었습니다: 기준、마운트、사전 설정、변환、필터、손잡이、토크 스케일링、중력 보정、홈으로 돌아가기。Minverse와 펜의 동기화 보정 — 이제 기기와 펜이 함께 보정됩니다. 그립이 물리적으로 장착될 때까지 보정 기능은 잠긴 상태로 유지됩니다.HTTP 사용 편의성 향상 — 인덱스 기반 장치 선택기(ID가 필요 없으며, 인덱스를 통해 장치를 지정할 수 있음), WebSocket과 동일한 요청/응답 형식, 옵트인 {성공, 오류, 데이터} 엔벨로프（?format=json), 그리고 와일드카드를 활용한 세션 선택기를 제공합니다.새로운 기능 {#new-features}
장치 {#devices}
Minverse — 이번 릴리스부터 정식 지원을 제공합니다. 여기에는 탐지, 준비 완료 시퀀스, 안전 알림, 동기화 보정 워크플로가 포함됩니다.이제 ‘Ruko ’와 ‘Kingfisher’ 를 공식 그립 제품 유형으로 인정하게 되었습니다.디바이스 시뮬레이터 지원 — 실제 기기와 병행하여 소프트웨어로 시뮬레이션된 디바이스를 감지하고 통신할 수 있습니다.연결 루프 보호 — 비정상적으로 작동하는 포트는 자동으로 차단됩니다.POST /ports/{port}/reset 에서 재설정할 수 있습니다.펜 장착 시의 하트비트 — 디바운스 처리를 통해 그립의 장착 및 분리 여부를 정확하게 감지합니다.세션, 명령어, WebSocket {#sessions-commands-websocket}
세션 프로필의 필터링 및 영구 저장 — 세션은 프로필 이름과 필요한 SDK 버전을 선언할 수 있으며, 서비스는 재연결 시에도 이를 기억합니다. 클라이언트나 모니터링 도구는 이 프로필을 사용하여 세션을 필터링하고 대상을 지정할 수 있습니다.세션별 명령어 버퍼 — 처리 속도가 느린 세션이 다른 세션을 중단시키는 일이 더 이상 발생하지 않습니다.일회성 명령어용 명시적 `configure` 맵 — 기기별 기준、사전 설정、마운트、포스 게이트、감쇠, 그리고 세션별 프로필 그리고 기준 하지만 모두 설정 에 포함되게 되었습니다. 출력 설정 맵과 일치하도록 되어 있으므로, 전송한 내용과 읽은 내용이 왕복 과정에서 일치합니다.사용자 정의가 가능한 기기 거치대 — 내장된 작업 공간 사전 설정 (기본값、팔 앞쪽、팔 앞쪽 중앙、전면 LED、led_front_centered) 중에서 선택하거나 명시적인 변환을 전송할 수 있습니다. 마운트를 수동으로 변경하면 프리셋은 자동으로 사용자 지정 로 전환됩니다.이름이 지정된 명령어 필드 — 범용의 가치 배열 대신,위치、벡터、각도、토크 를 사용합니다.각운동량 설정 하지만 각운동량 설정 로 대체합니다(단수형은 권장하지 않습니다).세션 프레임의 확장 — v3.0 및 v3.1 세션 프레임에 확장 가능한 설정、상태、상태 객체가 포함되게 되었습니다. 새로운 출력 필드에는,현재 커서 강제、현재 커서 위치、현재 각속도、현재 각도 위치、제어 도메인、제어 모드、변환、변환 속도, 보다 자세한 config.*, 그리고 상태.안전(기본적으로 숨김)이 있습니다.변환의 부분 업데이트 — 마운트, 작업 공간 변환, 탐색 도형을 사용하여 변경하려는 하위 필드(위치、회전、규모）만 전송할 수 있습니다.HTTP {#http}
GET / — 서비스 버전.GET/POST/DELETE /settings 그리고 /설정/* — 키와 값을 완벽하게 설정할 수 있는 API입니다.GET /sessions/{session} 그리고 GET/POST/DELETE /sessions/{session}/profile。GET /devices?session=<selector> — 장치의 좌표를 지정된 세션의 애플리케이션 공간으로 변환합니다.인덱스 기반 장치 선택기 — ID를 몰라도 인덱스를 통해 원하는 장치를 지정할 수 있습니다(첫 번째 Inverse3 에는 /inverse3/0/...、Inverse 제품군의 모든 기기에는 inverse...).요청/응답 형식의 통일 — POST/GET의 본문은 WebSocket과 동일합니다. 명령 데이터 JSON 형식을 사용합니다. 한 전송 방식을 위해 작성된 코드는 다른 전송 방식에서도 작동합니다.옵트인 봉투 — 임의의 경로로 ?format=json 을 지정하여 활성화합니다./설정* 그리고 GET /home_return 는 기본적으로 {성공, 오류, 데이터} 가 됩니다. 원본 형식을 사용할 경우 ?format=plain 을 지정합니다.세션 선택기의 와일드카드 — 프로필 이름에서는,*(임의의 문자열)과 ?(임의의 1자)를 사용할 수 있습니다.퍼센트 디코딩된 선택자 — %2A、%3A 등은 라우팅 전에 디코딩됩니다.이벤트 {#events}
커뮤니케이션/행사/항구 위의 전용 WebSocket 이벤트 스트림.장치의 수명 주기, 안전 기능(비상 제동, 이물질 감지, 정지), 보정 실패, 배터리 경고, 세션 경고, 제어 속도 저하 및 심각한 저하, 입력 검증, 권장되지 않는 팁 등을 포함한 24가지 유형의 이벤트 범주.관측 가능성 {#observability}
프로파일링 시, 로그 메시지는 레벨에 따라 다른 색상으로 Tracy로 전송됩니다.모든 HTTP 핸들러에 Tracy 영역을 설정하고 있습니다.메인 루프의 타이밍 통계 이벤트.로그 디렉터리와 서버 호스트 이름을 설정할 수 있습니다(Docker 지원).3.6 버전에서 제공될 예정인 기능 {#coming-in-36}
SDF 햅틱 이펙트(SDF HFX) — 기본 기능은 3.5 버전에 포함되어 있습니다(모듈, 라이프사이클, 모듈이 제공하는 명령어 및 상태의 직렬화). 공개 API는 3.6 버전에서 완전한 문서와 함께 제공될 예정입니다.개선 사항 {#improvements}
힘 진동 필터 — 축별 진동 감지, 8단계 점진적 복구, 히스테리시스가 적용된 진입 투표, 비대칭 해제 윈도우 기능을 갖추고 있습니다.런타임 포스 게이트 필터 — WebSocket 또는 HTTP를 통해 configure.force_gate.gain 을 사용하여 설정할 수 있습니다. 영구적인 기본값도 설정할 수 있습니다.메인 루프의 최대 주파수를 32 kHz로 높였습니다 — 고정밀도 애플리케이션용입니다.WebSocket 페이로드 축소 — 기본값이 항등값인 변환 하위 필드(위치 = 0、회전 = 신분 변환、축척 = 1)는 기본적으로 출력에서 제외되도록 변경되었습니다. 이로 인해 페이로드 크기가 줄어들고, 구형 Unity 패키지의 4KB 메시지 제한과의 호환성도 회복됩니다. 모든 필드를 출력에 포함하고자 하는 컨슈머를 위해, 두 가지 세부 설정(직렬화/명시적 필드、직렬화/변환 강제 완료)가 마련되어 있습니다.메인 루프의 지터 감소 — WebSocket 메시지 처리 시, JSON 파싱 및 네트워크 전송 과정에서도 메인 루프의 틱이 더 이상 차단되지 않습니다. 세션 틱 스케줄링이 응답 직렬화 단계보다 앞당겨졌습니다.서버는 기본적으로 localhost만 허용합니다. — 네트워크 액세스는,통신/모든 인터페이스 바인딩 설정에서 명시적으로 활성화할 수 있습니다.장치 선택기의 와일드카드는 선행 일치 구문을 사용합니다.(예: inverse (Inverse 제품군의 모든 기기와 호환됨).덤핑 명령어 를,포스 게이트 옆에 나란히 설정 지도로 이동했습니다.로테이션되는 파일 로거로 대체되어, 이제 디렉터리를 설정할 수 있게 되었습니다.모듈이 제공하는 명령어와 상태 — 모듈은 코어 스키마를 변경하지 않고도 고유한 명령어를 추가하거나, 필드를 설정하거나, 상태 출력을 WebSocket 프레임에 포함시킬 수 있습니다.수정 {#fixes}
1년 동안 수정된 버그 중 특히 영향이 큰 것은 다음과 같습니다.
세션 속도의 불안정화(특정 조건 하에서).GripHook(Verse Grip Stopper) 는 시뮬레이션이 실행되지 않을 때 제대로 해제되지 않았습니다.Inverse3 타임아웃 시간이너무 짧아서, 부팅 속도가 느린 기기에서 연결 끊김 현상이 반복되고 있었습니다.Windows 서비스 중지 시 불완전한 종료 — 시스템 종료 시 HTTP 서버가 항상 제대로 정리되지는 않았습니다.재연결 루프(서비스가 이전 펌웨어 버전에서 지원되지 않는 명령을 전송한 경우).블루투스 장치 열거로 인해블루투스 어댑터가 탑재된 시스템에서 대량의 로그가 출력되고 있었습니다.서비스를 연속으로 재시작했을 때 발생하는 충돌.Wireless Verse Grip 동글의 멈춤 현상(Ubuntu 노트북에서 절전 모드 진입 및 복귀 후 발생).Linux 및 macOS에서 Wireless Verse Grip의 핸드셰이크 기능이, 첫 번째 탐지 시도가 실패할 경우 올바르게 대체 방식으로 전환되도록 개선되었습니다.macOS 설정 파일의 위치 — 설정은 잘못된 경로가 아니라 ~/Library/Application Support/ 에 저장되게 되었습니다.Linux 및 macOS에서의 SIGSEGV 신호 처리 — 멀티스레드 크래시 캡처가 활성화된 경우, 치명적인 신호가 발생해도 프로세스가 더 이상 무한 루프에 빠지지 않습니다.세션 간 명령어 덮어쓰기 — 이전에는 특정 세션의 설정 명령어가 다른 세션의 명령어에 의해 별다른 알림 없이 덮어쓰이는 경우가 있었으나, 이제는 올바르게 필터링되어 병합됩니다.프로브 명령을 통한 설정 덮어쓰기 — 탐침 위치 전송되는 모니터링 세션(예: Haply Hub)이 보류 중인 basis/preset/profile 변경 사항을 더 이상 자동으로 덮어쓰지 않게 되었습니다.프로토타입 그립 표시 — 프로토타입 하드웨어가 사용자 지정 그립이 아닌 표준 그립으로 잘못 표시되었습니다.기존의 `set_basis` 행렬 규칙이아직 마이그레이션되지 않은 클라이언트에 대해 다시 적용되게 되었습니다.Inverse3 강제 킥이세션이 끊어질 때 잔류하는 힘의 급증을 더 이상 유발하지 않게 되었습니다.WebSocket 연결 끊김 현상(빠른 연결 및 끊김이 반복되는 상황).WebSocket의 `session_id` 하지만 일부 전송 페이로드에서는 0 로 시리얼라이즈되어 있었습니다.Windows 그럼,--dev ...와 조합하더라도 --로그 수준 이 존중받게 되었습니다(이전에는 디버그 (알고 보니 조용히 초기화되어 있었습니다).권장하지 않음 {#deprecations}
다음 기능들은 당분간 계속 작동하지만, 향후 주요 버전 업데이트에서 제거될 예정입니다. 해당되는 경우, 응답에는 사용 중단 경고 필드가 포함됩니다.
| 권장하지 않음 | 대체 대상 |
|---|---|
| POST /force_scale | POSTinverse |
| 게시물 /중력_보정 | POST /{device}/{id}/config/gravity_compensation |
| 게시물 /토크_스케일링 | 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 |
| WebSocket command_data.values | 위치, 벡터, 각도, 토크 |
| WebSocket 각운동량 설정 | 각운동량 설정 |
| WebSocket 포인터 위치 | 탐침 위치 |
| WebSocket 좌표 원점 설정 | configure.preset |
| WebSocket 세션 수준 기저 설정 | configure.basis |
호환성에 관한 주의사항 {#compatibility-notes}
3.4.19 버전부터는 호환성을 깨는 변경 사항이 없습니다. 기존 연동과 관련하여 주의해야 할 점이 두 가지 있습니다:
권장되지 않는 HTTP 엔드포인트의 응답에는,사용 중단 경고 필드가 추가되었습니다. 응답 스키마를 엄격하게 검증하는 클라이언트의 경우, 이 추가 필드를 허용하도록 설정해 주십시오.WebSocket의 명령 데이터 에 있는 가치 이 필드는 더 이상 권장되지 않지만, 계속해서 분석됩니다. 명명된 필드를 사용하는 것이 좋습니다.튜토리얼 및 문서 {#tutorials-documentation}
새로운 튜토리얼: 05 위치 제어, 06 조합(Inverse3 + Verse Grip), 07 Basis와 Mount, 08 HTTP 원격 구성 도구, 09 WebSocket 원격 제어, 10 이벤트 스트림 리스너.새로운 Glaze 버전: 기존의 nlohmann/json 버전과 함께 모든 C++ 튜토리얼에 추가되었습니다(cpp-glz/).모든 튜토리얼을 다시 작성하기、v3.1 API를 지원하도록 업데이트했습니다(포트 10001,configure.preset、이름이 지정된 명령어 필드,print_state() (도우미).삭제 — 기존 Verse Grip Stopper 튜토리얼은 삭제되었으며, 새로운 조합 튜토리얼로 대체되었습니다.공개 문서를업데이트했습니다(SDK 가이드, API 참조, 하드웨어 페이지).
