튜토리얼
각 튜토리얼은 Inverse Service의 한 가지 기능을 보여주는 독립 실행형 프로그램입니다. 세 가지 언어 버전을 나란히 제공하므로, 관용적 표현을 비교하고 프로젝트에 적합한 기술 스택을 선택할 수 있습니다:
- 파이썬 — 가장 짧고 가장 쉽게 시작할 수 있는 진입점 (
websockets+json) - C++ (nlohmann/json) — 이식성이 뛰어난 C++11, 런타임 파싱 방식의 JSON
- C++ (Glaze) — 컴파일 타임 리플렉션과 메모리 할당 없는 파싱을 지원하는 최신 C++20, 실시간 햅틱 루프에 권장
소스 코드는 두 개의 공개 샘플 저장소에 게시되어 있습니다:
- haply — 각 튜토리얼마다 디렉터리가 하나씩 있으며, nlohmann/json(C++11) 및 Glaze(C++20) 변형 버전이 모두 포함되어 있습니다. 빌드 대상에는 Glaze 변형 버전을 위한
-glz접미사가 붙습니다. - haply-inverse-python-samples — 튜토리얼마다 디렉터리가 하나씩 있습니다.
Inverse Service의 각 릴리스는 두 저장소에 일치하는 태그를 고정합니다. 이 문서와 일치하는 버전을 유지하려면 release/<version> 브랜치를 따르십시오.
사전 요구 사항
- 포트
10001에서 역 서비스 서비스가 실행 중이어야 합니다 (Haply Hub 또는 독립 실행형 설치 프로그램(로 실행). - Haply 가 최소 한 대 이상 감지되어야 합니다. 각 튜토리얼은 특정 장치 시리즈를 대상으로 합니다. 아래 표를 참조하십시오.
- 파이썬 튜토리얼:
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.txtFetchContent를 통해libhv,nlohmann/json,glaze를 가져오기 때문에 수동으로 종속성을 설정할 필요가 없습니다.
튜토리얼 목록
| # | 이름 | 장치 | 변형 | 학습 내용 |
|---|---|---|---|---|
| 00 | 장치 목록 | 모든 기기 | 파이 · C++ · C++ 글레이즈 | HTTP 장치 검색, 세션 범위 쿼리 |
| 01 | Inverse3 출력 | Inverse3 | 파이 · C++ · C++ 글레이즈 | WebSocket 상태 스트리밍, 제로 포스 킵얼라이브, 첫 메시지 핸드셰이크 |
| 02 | VerseGrip 출력 | 유선 VG | 파이 · C++ · C++ 글레이즈 | 방향 스트리밍, probe_orientation 킵얼라이브, 쿼터니언 → 오일러 변환 |
| 03 | 무선 VG 출력 | WVG | 파이 · C++ · C++ 글레이즈 | 버튼, 배터리, 홀 센서 |
| 04 | 안녕하세요, 플로어 | Inverse3 | 파이 · C++ · C++ 글레이즈 | 첫 번째 햅틱 효과 — set_cursor_force 페널티 스프링 |
| 05 | 위치 제어 | Inverse3 | 파이 · C++ · C++ 글레이즈 | set_cursor_position 제어, 무작위 목표 지점(C++) 또는 WASD 키를 눌러 이동(Python) |
| 06 | 결합 | Inverse3 WVG | 파이 · C++ · C++ 글레이즈 | 다중 장치 루프, 쿼터니언 방향 기반 커서 제어 |
| 07 | 기준 좌표계 및 마운트 | Inverse3 | 파이 · C++ · C++ 글레이즈 | configure.basis, configure.preset, 런타임 configure.mount 재정의; 프리셋과 마운트 간의 상호 배타성 |
| 08 | HTTP 원격 구성 | Inverse3 | 파이 · C++ · C++ 글레이즈 | HTTP 전용 세션 간 구성기: 프로필에서 세션을 찾은 후 REST를 통해 basis / preset / mount를 대화형으로 POST |
| 09 | WS 원격 제어 | Inverse3 | 파이 · C++ · C++ 글레이즈 | 실시간 워크스페이스 내비게이터: HTTP 세션/기기 검색 후 WebSocket을 통해 틱마다 set_transform 스트리밍 |
| 10 | 이벤트 | — | 파이 · C++ · C++ 글레이즈 | 포트 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