跳转至正文

Haply 逆向服务

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（只读）系统事件：安全、电池、连接、周期性警告
超文本传输协定10001REST非持久化配置查询、设置、会话管理、设备检查

所有有效载荷均为 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 反向服务”，右键单击，然后选择“启动”、“停止”或“重启”。

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 参考​

所有端点和消息的完整机器可读规范如下：