教程
每个教程都是一个独立程序，演示 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> 分支，以保持与本文档一致的版本。
前提条件
- Inverse Service 正在运行（通过 Haply Hub 或 独立安装程序 启动），监听端口为
10001。 - 至少检测到一台 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 | Basis 与 Mount | Inverse3 | Py · C++ · C++ Glaze | configure.basis、configure.preset，以及运行时的 configure.mount 覆盖；preset 与 mount 互斥 |
| 08 | HTTP 远程配置 | Inverse3 | Py · C++ · C++ Glaze | 仅限 HTTP 的跨会话配置器：按配置文件（profile）发现会话，通过 REST 交互式 POST basis / preset / mount |
| 09 | WS 远程控制 | Inverse3 | Py · C++ · C++ Glaze | 实时工作区导航器：先进行 HTTP 会话/设备发现，然后通过 WebSocket 按每个 tick 流式发送 set_transform |
| 10 | 事件 | — | Py · C++ · C++ Glaze | 监听 10020 端口的事件流，支持按级别/名称过滤 |
提示 — 触觉循环基准测试
教程 10（事件）设计为可与任意其他教程同时运行。启用 --no-hide-rate 后，它会输出服务的 system-rate-report 事件，其中包含有效的设备 tick 速率。比较同一教程在 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