튜토리얼
각 튜토리얼은 Inverse Service의 한 가지 기능을 보여 주는 독립 실행형 프로그램입니다. 세 가지 언어 변형을 나란히 제공하므로, 관용적 표현을 비교하고 프로젝트에 맞는 기술 스택을 선택할 수 있습니다:
- Python — 가장 짧고 가장 쉽게 시작할 수 있는 진입점 (
websockets+json) - C++ (nlohmann/json) — 이식성이 뛰어난 C++11, 런타임 파싱 방식의 JSON
- C++ (Glaze) — 컴파일 타임 리플렉션과 메모리 할당 없는 파싱을 지원하는 최신 C++20, 실시간 햅틱 루프에 권장
소스 코드는 두 개의 공개 샘플 저장소에 게시되어 있습니다:
- haply-inverse-cpp-samples — 튜토리얼마다 디렉터리가 하나씩 있으며, nlohmann/json(C++11) 및 Glaze(C++20) 변형을 모두 포함합니다. 빌드 대상에는 Glaze 변형을 위한
-glz접미사가 붙습니다. - haply-inverse-python-samples — 튜토리얼마다 디렉터리가 하나씩 있습니다.
Inverse Service의 각 릴리스는 두 저장소에 일치하는 태그를 고정합니다. 이 문서와 일치하는 버전을 유지하려면 release/<version> 브랜치를 따르십시오.
사전 요구 사항
- 포트
10001에서 Inverse Service 서비스가 실행 중이어야 합니다 (Haply Hub 또는 독립 실행형 설치 프로그램으로 실행). - 최소 하나의 Haply 장치가 감지되어야 합니다. 각 튜토리얼은 특정 장치 계열을 대상으로 합니다. 아래 표를 참고하십시오.
- Python 튜토리얼:
pip install websockets(튜토리얼 04, 05, 06, 07, 08, 09에는 추가로keyboard가 필요하며, 이는 Linux에서 관리자 권한을 요구합니다. 튜토리얼 08과 09에는requests도 필요합니다.) - C++ 튜토리얼: nlohmann 변형에는 CMake 3.15 이상과 C++11 컴파일러가, Glaze(
-glz) 변형에는 C++20 컴파일러가 필요합니다. 샘플 저장소의 최상위CMakeLists.txt가 FetchContent를 통해libhv,nlohmann/json,glaze를 가져오므로 수동 의존성 설정은 필요하지 않습니다.
튜토리얼 목록
| # | 이름 | 장치 | 변형 | 학습 내용 |
|---|---|---|---|---|
| 00 | 장치 목록 | 모든 장치 | Py · C++ · C++ Glaze | HTTP 장치 검색, 세션 범위 쿼리 |
| 01 | Inverse3 출력 | Inverse3 | Py · C++ · C++ Glaze | WebSocket 상태 스트리밍, 제로 포스 킵얼라이브, 첫 메시지 핸드셰이크 |
| 02 | VerseGrip 출력 | 유선 VG | Py · C++ · C++ Glaze | 방향 스트리밍, probe_orientation 킵얼라이브, 쿼터니언 → 오일러 변환 |
| 03 | 무선 VG 출력 | WVG | Py · C++ · C++ Glaze | 버튼, 배터리, 홀 센서 |
| 04 | Hello Floor | Inverse3 | Py · C++ · C++ Glaze | 첫 번째 햅틱 효과 — set_cursor_force 페널티 스프링 |
| 05 | 위치 제어 | Inverse3 | Py · C++ · C++ Glaze | set_cursor_position 제어, 무작위 목표 지점(C++) 또는 WASD 누르기 이동(Python) |
| 06 | 결합 | Inverse3 + WVG | Py · C++ · C++ Glaze | 다중 장치 루프, 쿼터니언 방향 기반 커서 구동 |
| 07 | 기준 좌표계 & 마운트 | Inverse3 | Py · C++ · C++ Glaze | configure.basis, configure.preset, 런타임 configure.mount 재정의; 프리셋과 마운트 간 상호 배타성 |
| 08 | HTTP 원격 구성 | Inverse3 | Py · C++ · C++ Glaze | HTTP 전용 세션 간 구성기: 프로필로 세션을 찾은 뒤 REST를 통해 basis / preset / mount를 대화식으로 POST |
| 09 | WS 원격 제어 | Inverse3 | Py · C++ · C++ Glaze | 실시간 워크스페이스 내비게이터: HTTP 세션/장치 검색 후 WebSocket 경유로 틱마다 set_transform 스트리밍 |
| 10 | 이벤트 | — | Py · C++ · C++ Glaze | 포트 10020의 이벤트 스트림 리스너, 레벨/이름 필터링 |
팁 — 햅틱 루프 벤치마크
튜토리얼 10(이벤트)은 다른 튜토리얼과 함께 실행하도록 설계되어 있습니다. --no-hide-rate 옵션을 활성화하면 서비스의 system-rate-report 이벤트가 출력되며, 여기에는 실제 장치 틱 레이트가 포함됩니다. 같은 튜토리얼의 Python / C++(nlohmann) / C++(Glaze) 변형에서 레이트를 비교하면, 약 4 kHz 제어 루프에 미치는 직렬화 오버헤드의 영향을 관찰할 수 있습니다.
# Terminal 1 — pick a tutorial variant
./04-haply-inverse-hello-floor # C++ nlohmann
./04-haply-inverse-hello-floor-glz # C++ Glaze
python 04-haply-inverse-hello-floor.py # Python
# Terminal 2 — watch the rate
./10-haply-inverse-events --no-hide-rate