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) 또는 명시적인 변환을 전송하십시오. 조립을 수동으로 변경하면 프리셋이 자동으로 사용자 지정 음.명명된 명령 필드 — 위치, 벡터, 각도, 토크 일반 배열을 대체합니다 가치.각운동량 설정 ersetzt 각운동량 설정 (단수형은 더 이상 사용되지 않습니다).세션 프레임의 확장 — 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 핸들러에 대한 트레이시-조넨.메인 루프의 타이밍 통계가 포함된 이벤트.설정 가능한 로그 디렉터리와 서버 호스트명 (Docker 호환).곧 3.6 버전에서 출시될 예정입니다 {#coming-in-36}
SDF 햅틱 효과(SDF HFX) — 3.5 버전에서 이미 그 기반이 마련되었습니다(모듈, 수명 주기, 모듈 측에서 제공하는 명령 및 상태 데이터의 직렬화); 공개 API는 3.6 버전에서 완전한 문서와 함께 제공될 예정입니다.개선 사항 {#improvements}
동력 진동 필터링 — 축별 진동 감지, 8단계 점진적 복구, 히스테리시스를 적용한 진입 조정 및 비대칭 허용 창.실행 시 Force-Gate-Filter — 다음을 통해 설정 가능 configure.force_gate.gain, WebSocket 또는 HTTP를 통해, 영구적인 기본값과 함께.정밀도 요구가 높은 응용 분야를 위해 메인 루프의 최대 주파수를 32 kHz로 높였습니다.더 작은 웹소켓 페이로드 — 변환-동일성 기본값을 갖는 하위 필드 (위치 = 0, 회전 = 신분 변환, 축척 = 1)는 기본적으로 출력되지 않습니다. 이로 인해 유효 부하 크기가 줄어들며, 구형 Unity 패키지의 4KB 메시지 제한과의 호환성이 다시 확보됩니다. 두 가지 고급 설정(직렬화/명시적 필드, 직렬화/변환 강제 완료)는 이를 필요로 하는 클라이언트를 위해 모든 필드를 다시 포함합니다.메인 루프의 지터 감소 — JSON 구문 분석 및 네트워크 전송 중에 WebSocket 메시지 처리가 더 이상 메인 루프의 클럭을 차단하지 않으며, 세션의 클럭 스케줄링이 응답 직렬화 단계보다 앞당겨졌습니다.서버는 기본적으로 localhost에서만 작동합니다. — 네트워크 액세스는 설정에서 활성화할 수 있습니다. 통신/모든 인터페이스 바인딩.장치 선택자에 와일드카드를 사용할 때는 접두사 구문을 사용합니다. (예: inverse (Inverse 제품군의 모든 기기에 적용됩니다).감쇠 명령어 다음과 함께 포스 게이트 인 다이 설정- 할당이 연기되었습니다.회전식 파일 로거가 기존 기능을 대체하며, 사용자 정의 가능한 디렉터리를 지원합니다.모듈에서 제공하는 명령 및 상태 — 모듈은 핵심 스키마를 변경하지 않고도 자체 명령을 추가하고, 필드를 구성하며, 상태 출력을 WebSocket 프레임에 삽입할 수 있습니다.오류 수정 {#fixes}
오류 수정으로 가득 찬 한 해였으며, 그중 가장 효과적인 수정 사항들은 다음과 같습니다.
특정 조건에서 세션 속도가 불규칙하게 나타납니다.시뮬레이션이 실행 중이지 않을 때 GripHook(Verse Grip Stopper)이 제대로 해제되지 않았습니다.Inverse3-타임아웃 설정이 너무 공격적이어서, 부팅 속도가 느린 기기에서는 연결 끊김 현상이 반복적으로 발생했습니다. Windows 에서 서비스가 비정상적으로 종료됨 — HTTP 서버가 종료될 때 항상 정리되지 않았습니다.서비스가 이전 펌웨어 버전에 지원되지 않는 명령을 전송한 경우 재연결 루프가 발생합니다.블루투스 어댑터가 장착된 시스템에서 블루투스 장치 목록이 로그를 넘쳐나게 했다.서비스를 연속으로 여러 번 재시작할 때 오류가 발생합니다.Ubuntu 노트북에서 대기 모드 후 재개 시 Wireless Verse Grip 동글이 멈추는 현상.이제 Linux 및 macOS에서 Wireless-Verse-Grip-Handshake는 첫 번째 인식 시도가 실패할 경우 올바르게 대체 방식을 활용합니다.macOS 구성 파일의 저장 위치 — 구성이 이제 ~/Library/Application Support/ 잘못된 경로가 아닌 곳에 저장되었습니다.SIGSEGV-리눅스 및 macOS에서의 신호 처리 — 여러 스레드에 대해 크래시 로깅이 활성화된 경우, 치명적인 신호가 발생해도 프로세스가 무한 루프에 빠지지 않습니다.세션 간 명령어 덮어쓰기 — 한 세션의 구성 명령어가 다른 세션의 명령어로 묵시적으로 대체될 수 있었으나, 이제 이러한 명령어가 올바르게 필터링되고 병합됩니다.프로브 명령은 구성을 덮어씁니다 — 모니터링 세션(예: Haply Hub)은, 탐침 위치 Basis / Preset / 프로필에 대한 미적용 변경 사항을 더 이상 묵시적으로 적용하거나 덮어쓰지 않습니다.프로토타입 핸들 표시 — 프로토타입 하드웨어가 사용자 정의 핸들이 아닌 표준 핸들로 잘못 표시되었습니다.아직 마이그레이션되지 않은 클라이언트의 경우, 기존의 `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 엔드포인트에 이제 필드가 포함됩니다. 사용 중단 경고 답변에서 – 답변 패턴을 엄격하게 검증하는 클라이언트는 이 추가 필드를 허용해야 합니다.Das Feld 가치 WebSocket에서 명령 데이터 이 방법은 구식이지만, 여전히 구문 분석됩니다. 가급적 명명된 필드를 사용하십시오.튜토리얼 및 문서 {#tutorials-documentation}
새로운 튜토리얼: 05 위치 제어, 06 복합 (Inverse3 + Verse Grip), 07 기본 및 마운트, 08 HTTP 원격 구성기, 09 WebSocket 원격 제어, 10 이벤트 스트림 리스너.새로운 유약 종류 모든 C++ 튜토리얼 (cpp-glz/) 기존의 nlohmann/json 방식과 병행하여.모든 튜토리얼을 수정했습니다 v3.1 API용 (포트 10001, configure.preset, 이름이 지정된 명령 필드, print_state()-보조 기능).삭제됨: 구 버전의 ‘Verse Grip Stopper’ 튜토리얼 – 새로운 통합 튜토리얼로 대체되었습니다.SDK 가이드, API 참조 및 하드웨어 페이지의 공개 문서가 업데이트되었습니다.
