跳到主要内容

Haply Inverse Service

Inverse Service 以后台进程的形式运行在你的电脑上，实时将 Haply 触觉设备连接到你的应用程序。它负责你代码以下的所有工作：设备检测、串口通信、安全监控以及状态流传输，让你可以专注于打造体验。

运行要求与兼容性​

本服务可运行于主流桌面平台，并且可以通过任何带有 WebSocket 客户端和 JSON 解析器的语言进行调用：

  • 平台： Windows 10+（MSVC）、Linux（.deb 包）、macOS
  • 语言： Python、JavaScript / TypeScript、C++、C#、Rust、Go、Java……以及任何能够使用 WebSocket + JSON 通信的语言

官方支持的集成​

Haply 为以下产品维护了官方集成：Haply Inverse Unity Package、Toia、Geomagic Freeform 和 NVIDIA Isaac Lab。

除此之外，只要平台或运行时提供 WebSocket 客户端和 JSON 解析器，就可以使用本服务——我们已在 Unreal Engine、TouchDesigner 以及其他实时或仿真技术栈中与之一同运行过。只要你的环境能够打开 WebSocket，就可以驱动 Inverse 设备。

有关特定语言的示例，请参阅公开的示例仓库：C++ 和 Python。

通信接口​

本服务提供两个通信通道：

通道端口传输方式用途
仿真10001WebSocket实时命令／状态循环（1 条消息输入，1 个状态输出）
事件10020WebSocket（只读）系统事件：安全、电量、连接、速率警告
HTTP10001REST无状态的配置查询、设置、会话管理与设备检查

所有负载均为 JSON。有关标准信封、端口和内容类型规则，请参阅 JSON 约定。

使用场景​

目标起始位置
向触觉设备发送力或位置目标实时控制
配置 坐标基、挂载方式、预设或滤波器会话配置
导航 场景（速率控制式移动）导航模块
监听系统事件（安全、电量、连接）事件与监控
通过示例学习教程

坐标系​

Haply 的内部坐标系为右手系，Z 轴朝上（+X 向右，+Y 向前，+Z 向上）。你可以通过一次坐标基置换将其重映射到应用程序的坐标系——设置后，所有输入和输出都会自动完成转换。

有两种变换用于在场景中定位设备：

  • 挂载——设备的物理偏移量（通过预设设置，或显式设置）
  • 工作空间——用于相机／场景导航的运行时漂移（可手动设置，或通过导航模块设置）

完整的坐标处理流程请参阅挂载与工作空间。

运行服务​

Inverse Service 可以以两种模式运行：

  • 嵌入在 Haply Hub 中（推荐）——Haply Hub 会捆绑最新版本的服务，并在 Hub 打开时自动启动。无需手动设置，你总能获得最新的修复。
  • 独立运行——使用Inverse Installer将特定版本的服务安装为 Windows 服务或 Unix 守护进程。适用于 CI、无界面部署，或不运行 Hub 的机器。

管理独立服务​

Windows——打开服务应用：按下 Win+R，输入 services.msc，找到“Haply Inverse Service”，右键单击 → 启动／停止／重启。

Linux（systemd）：

systemctl start haply-inverse-service.service
systemctl stop haply-inverse-service.service
systemctl restart haply-inverse-service.service
systemctl enable haply-inverse-service.service   # auto-start on boot

完整 API 参考​

有关每个端点和消息的完整机器可读规范：