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/0/... 첫 번째 Inverse3로 연결됩니다. ;inverse... (모든 Inverse 시리즈 기기를 대상으로 함).일관된 요청/응답 구조 — POST/GET 요청 본문은 WebSocket과 동일한 명령 데이터 JSON 구조; 한 가지 전송 방식을 위해 작성된 코드는 다른 전송 방식에도 사용할 수 있습니다.선택 가능한 패키징 구조 — 모든 경로에서 사용 ?format=json 바로 활성화할 수 있습니다;/설정* 와 GET /home_return 기본 설정 {성공, 오류, 데이터}。원본 구조를 확인하시려면 다음을 사용하십시오. ?format=plain。세션 선택자 와일드카드 — 프로필 이름에 포함된 *(임의의 문자열) 및 ?(단일 문자).퍼센트 기호 디코딩 선택기 — %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 서버가 항상 정리되는 것은 아닙니다.재연결 루프는서비스가 구버전 펌웨어에 지원되지 않는 명령을 전송할 때 발생합니다.블루투스 장치를 열거할 때, 블루투스 어댑터가 장착된 시스템에서는 로그가 대량으로 기록됩니다.서비스를 연속으로 여러 번 재시작할 때 충돌이 발생합니다.Ubuntu 노트북에서 절전 모드 진입 및 복귀 후 무선 Verse Grip 수신기가 응답하지 않는 현상이발생합니다.무선 Verse Grip(Linux 및 macOS)은첫 번째 감지 시도가 실패할 경우 이제 올바르게 원래 상태로 되돌아갑니다.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 기초 및 마운트, 08 HTTP 원격 구성기, 09 WebSocket 원격 제어, 10 이벤트 스트림 리스너.Glaze 변형 추가: 각 C++ 튜토리얼에 새로 추가된 내용 cpp-glz/ 이 변형은 기존의 nlohmann/json 변형과 병행하여 사용됩니다.모든 튜토리얼이 새로 작성되었습니다.，v3.1 API(포트 10001,configure.preset、명명된 명령어 필드、print_state() (보조 함수).이전Verse Grip Stopper 튜토리얼을 삭제했습니다. 새로운 Combined 튜토리얼로 대체되었습니다.공개 문서가업데이트되었으며, 여기에는 SDK 가이드, API 참조 및 하드웨어 페이지가 포함됩니다.
