Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
이번 릴리스는 API 재작성 이후 1년 만에 나온 가장 대규모의 릴리스입니다. 3.5.0 버전에서는 통합 3D 수학 레이어, Minverse에 대한 전면 지원, 타입 지정 이벤트 스트림, 완전한 설정 API, 그리고 더욱 간결해진 HTTP 인터페이스가 도입되었습니다. 또한 지난 1년 동안의 버그 수정 및 사용성 개선 사항도 포함되어 있습니다.
주요 하이라이트 {#highlights}
통합 3D 수학 레이어 — 장치 기준(프레임), 마운트 변환, 작업 공간 변환, 탐색 변환을 1급 기본 요소로 제공하는 조합 가능한 변환 파이프라인이며, 로컬, 세션, 애플리케이션, 내부 공간 간의 명시적 변환도 지원합니다.버블 내비게이션 — 속도 매핑 기반 속도 제어, 히스테리시스를 고려한 충돌 감지, 선택적 커서 방향 드리프트 기능을 갖춘 형상 영역(SDF 프리미티브)을 통해 넓은 가상 작업 공간을 탐색합니다. HTTP 및 WebSocket를 통해 완전히 구성할 수 있으며, 앱 공간 왕복(round-trip)을 지원합니다.유형 지정 이벤트 스트림 — 장치 수명 주기, 안전 알림, 보정, 배터리, 제어 주기 경고, 지원 중단(deprecation) 안내를 위한 전용 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을 지정하십시오.세션 선택자 와일드카드 — 프로필 이름에서 *(임의의 문자열)과 ?(단일 문자)를 사용할 수 있습니다.퍼센트 디코딩된 선택자 — %2A, %3A 등은 라우팅 전에 디코딩됩니다.이벤트 {#events}
커뮤니케이션/행사/항구에서 제공되는 전용 WebSocket 이벤트 스트림입니다.장치 수명 주기, 안전(전자 브레이크, 이물질 감지, 정지(stall)), 보정 실패, 배터리 경고, 세션 경고, 낮은 제어 주기 및 임계 제어 주기, 입력 유효성 검사, 지원 중단 알림 등을 포함한 24가지 유형의 이벤트 범주를 제공합니다.관측성(Observability) {#observability}
프로파일링 시 로그 메시지가 레벨별 색상과 함께 Tracy로 전송됩니다.모든 HTTP 핸들러에 Tracy 영역(zone)이 적용됩니다.메인 루프 타이밍 통계 이벤트입니다.로그 디렉터리와 서버 호스트 이름을 구성할 수 있습니다(Docker 호환).3.6 버전에서 제공 예정 {#coming-in-36}
SDF Haptic Effects(SDF HFX) 기반 작업은 3.5 버전에 반영되었습니다(모듈, 수명 주기, 모듈이 제공하는 명령/상태 직렬화). 공개 API는 3.6 버전에서 전체 문서와 함께 제공될 예정입니다.개선 사항 {#improvements}
힘 진동 필터링 — 축별 진동 감지, 8단계 점진적 복구, 히스테리시스를 적용한 진입 투표, 비대칭 해제 구간을 포함합니다.런타임 강제 게이트 필터 — WebSocket 또는 HTTP를 통해 configure.force_gate.gain으로 구성할 수 있으며, 영구적인 기본값을 지원합니다.정밀 응용 분야를 위해 메인 루프의 최대 주파수가 32 kHz로 상향 조정되었습니다.더 작아진 WebSocket 페이로드 — 항등(identity) 기본값을 가진 transform 하위 필드(위치 = 0, 회전 = 신분 변환, 축척 = 1)는 기본적으로 출력에서 생략되어 페이로드 크기가 줄어들며, 구버전 Unity 패키지의 4KB 메시지 제한과의 호환성이 복원됩니다. 두 가지 고급 설정(직렬화/명시적 필드, 직렬화/변환 강제 완료)을 사용하면, 이 값이 필요한 사용자를 위해 모든 필드를 다시 포함시킬 수 있습니다.메인 루프 지터 감소 — JSON 파싱 및 네트워크 전송 중에도 WebSocket 메시지 처리가 메인 루프 틱을 차단하지 않습니다. 세션 틱 스케줄링이 응답 직렬화보다 앞당겨졌습니다.서버의 기본값은 localhost 전용입니다. — 통신/모든 인터페이스 바인딩 설정을 통해 네트워크 접근을 명시적으로 허용할 수 있습니다.장치 선택자 와일드카드는 접두사 구문을 사용합니다.(예: inverse(Inverse 계열의 모든 기기와 호환됩니다).댐핑 명령이 포스 게이트와 함께 설정 지도로 이동했습니다.로테이팅 파일 로거가기존 로거를 대체하며, 디렉터리를 구성할 수 있습니다.모듈이 제공하는 명령 및 상태 — 모듈은 핵심 스키마를 변경하지 않고도 자체 명령을 삽입하고, 필드를 구성하며, WebSocket 프레임에 상태 출력을 추가할 수 있습니다.수정 사항 {#fixes}
지난 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 명령어가 설정을 덮어쓰는 문제 — 모니터링 세션(예: Haply Hub)에서 탐침 위치 명령을 보내더라도 대기 중인 basis/preset/profile 변경 사항이 더 이상 자동으로 덮어쓰이지 않습니다.프로토타입 그립 표시 — 프로토타입 하드웨어가 사용자 지정 그립 대신 표준 그립으로 잘못 표시되었습니다.아직 마이그레이션을 완료하지 않은 클라이언트의 경우, 기존 `set_basis` 행렬 규칙이다시 적용되도록 수정되었습니다.세션 연결이 끊어질 때 ‘Inverse3 ’ 강제 퇴장 시잔류 힘 스파이크가 더 이상 발생하지 않습니다.빠른 연결/연결 해제 주기 중에 발생하던 WebSocket 연결 끊김(connection lost) 레이스 조건.일부 전송 페이로드에서 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 및 마운트, 08 HTTP 원격 설정기, 09 WebSocket 원격 제어, 10 이벤트 스트림 리스너.새로운 Glaze 버전: 기존 nlohmann/json 버전과 더불어, 모든 C++ 튜토리얼에 Glaze 버전(cpp-glz/)가 추가되었습니다.모든 튜토리얼 재작성: v3.1 API(포트 10001, configure.preset, 이름이 지정된 명령 필드, print_state() (헬퍼)에 맞춰 다시 작성되었습니다.기존 Verse Grip Stopper 튜토리얼을 삭제했습니다— 새로운 통합 튜토리얼로 대체되었습니다.SDK 가이드, API 참조, 하드웨어 페이지 등 공개 문서를전반적으로 새롭게 업데이트했습니다.
