Standalone Inverse Service

面向 Haply 设备的 Service Runtime 和 Runtime SDK，已打包为便捷安装程序。也称为“external”Service。

v3.5.0

发布时间 2026年4月23日于下午4:57

...正在检测您的系统...

发布说明

Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}

这是自一年前 API 重写以来我们最大的一次版本更新。3.5.0 引入了统一的 3D 数学层、对 Minverse 的完整支持、带类型的事件流、完整的设置 API，以及更简洁的 HTTP 接口，同时还包含一年来的缺陷修复和体验改进。

亮点 {#highlights}

统一的 3D 数学层 — 可组合的变换管线，为设备基础坐标系（frame）、安装变换、工作空间变换和导航变换提供一等级的基础单元，并支持在本地、会话、应用和内部空间之间进行显式转换。

Bubble Navigation — 通过成形区域（SDF 图元）在大型虚拟工作空间中导航，支持速度映射的速率控制、感知滞后的碰撞检测，以及可选的朝光标漂移。可通过 HTTP 和 WebSocket 完全配置，并支持应用空间往返。

带类型的事件流 — 专用的 WebSocket 事件通道，用于设备生命周期、安全警报、校准、电池、控制速率警告和弃用提示。

设置 API — 完整的键值设置系统，支持 HTTP CRUD、类型提示、取值范围约束和描述信息，取代了旧的嵌套配置文件。

统一的设备配置 — 所有设备共用一套 HTTP 路由：basis、mount、preset、transform、filters、handedness、torque_scaling、gravity_compensation、home_return。

Minverse 与笔的同步校准 — 设备及其笔现在可一同校准；在握把实际连接之前，校准保持锁定。

HTTP 易用性改进 — 基于索引的设备选择器（无需 ID，按索引指定设备），与 WebSocket 共享统一的请求/响应结构，可选启用的 {ok, error, data} 封装（?format=json），以及通配符会话选择器。

新功能 {#new-features}

设备 {#devices}

Minverse — 本版本正式支持：设备检测、就绪流程、安全通知以及同步校准工作流。

Ruko 和 Kingfisher 已被认定为官方握把产品类型。

设备模拟器支持 — 可检测并与软件模拟设备通信，与真实硬件并存。

连接循环保护 — 行为异常的端口会被自动屏蔽；可通过 POST /ports/{port}/reset 重置。

笔连接心跳 — 带去抖动的可靠握把连接/断开检测。

会话、命令与 WebSocket {#sessions-commands-websocket}

会话配置文件的过滤与持久化 — 会话声明配置文件名称和所需的 SDK 版本，服务会在重新连接后记住这些信息；客户端和监控工具可按该配置文件过滤和定位会话。

按会话划分的命令缓冲区 — 一个运行缓慢的会话不再会阻塞其他会话。

用于一次性命令的显式 `configure` 映射 — 每个设备的 basis、preset、mount、force_gate、damping，以及每个会话的 profile 和 basis，现均位于 configure 中，与输出配置映射保持一致，因此发送的内容与读取的内容可以往返一致。

可自定义的设备安装方式 — 可选择内置的工作空间预设（defaults、arm_front、arm_front_centered、led_front、led_front_centered），也可发送显式的变换；手动修改安装方式时，预设会自动切换为 custom。

具名命令字段 — position、vector、angles、torques 取代了通用的 values 数组。

set_angular_torques 取代了 set_angular_torque（单数形式已弃用）。

会话帧扩展 — v3.0 和 v3.1 的会话帧现在包含可扩展的 config、state 和 status 对象；新增输出字段包括 current_cursor_force、current_cursor_position、current_angular_torques、current_angular_position、control_domain、control_mode、transform、transform_velocity、更丰富的 config.*，以及 status.safety（默认隐藏）。

部分变换更新 — 在安装方式、工作空间变换和导航形状上，只需发送要更改的子字段（position、rotation、scale）。

HTTP {#http}

GET / — 服务版本。

GET/POST/DELETE /settings 及 /settings/* — 完整的键值设置 API。

GET /sessions/{session} 及 GET/POST/DELETE /sessions/{session}/profile。

GET /devices?session=<selector> — 将设备坐标转换到指定会话的应用空间中。

基于索引的设备选择器 — 无需知道 ID 即可按索引定位任意设备（/inverse3/0/... 指向第一个 Inverse3；/inverse__ITALIC_italic-1__/... 指向所有 Inverse 系列设备）。

统一的请求/响应结构 — POST/GET 的请求体与 WebSocket 使用相同的 command_data JSON 结构；针对一种传输方式编写的代码也可用于另一种。

可选的封装结构 — 在任意路由上使用 ?format=json 即可启用；/settings* 和 GET /home_return 默认使用 {ok, error, data}。如需原始结构，请使用 ?format=plain。

会话选择器通配符 — 配置文件名称中的 *（任意字符序列）和 ?（单个字符）。

百分号解码的选择器 — %2A、%3A 等在路由前会被解码。

事件 {#events}

在 communication/events/port 上提供专用的 WebSocket 事件流。

共 24 类带类型的事件，包括设备生命周期、安全事件（急停、异物检测、失速）、校准失败、电池警报、会话警告、控制速率过低/严重过低、输入验证和弃用提示。

可观测性 {#observability}

启用性能分析时，日志消息会按级别着色后转发至 Tracy。

每个 HTTP 处理程序均设有 Tracy 区域。

主循环计时统计事件。

可配置日志目录和服务器主机名（便于 Docker 使用）。

3.6 版本即将推出 {#coming-in-36}

SDF 触觉效果（SDF HFX） — 基础工作已在 3.5 中完成（模块、生命周期、模块贡献的命令/状态序列化），公开 API 将随 3.6 发布并附完整文档。

改进 {#improvements}

力振荡滤波 — 按轴进行振荡检测、8 阶段渐进式恢复、带滞后的进入投票机制，以及非对称的释放窗口。

运行时力门滤波器 — 可通过 WebSocket 或 HTTP 使用 configure.force_gate.gain 进行配置，并带有持久化的默认值。

主循环最高频率提升至 32 kHz，面向精密应用。

更小的 WebSocket 负载 — 默认情况下，输出中会省略默认值为恒等变换的子字段（position = 0、rotation = identity、scale = 1），从而减小负载大小，并恢复与旧版 Unity 软件包 4 KB 消息长度限制的兼容性。两个高级设置（serialization/explicit_fields、serialization/force_complete_transforms）可为需要的使用方重新启用所有字段。

降低主循环抖动 — WebSocket 消息处理在 JSON 解析和网络发送期间不再阻塞主循环周期；会话周期调度已提前至响应序列化之前。

服务器默认仅监听 localhost — 如需开启网络访问，请启用 communication/bind_all_interfaces 设置。

设备选择器通配符采用前缀语法（例如 inverse* 匹配所有 Inverse 系列设备）。

阻尼命令 已与 force_gate 一起移入 configure 映射中。

轮转文件日志记录器 取代了原有的记录器，并支持可配置的目录。

模块贡献的命令与状态 — 模块可向 WebSocket 帧注入自定义命令、配置字段和状态输出，而无需修改核心 schema。

修复 {#fixes}

一年的缺陷修复；其中影响最大的列于下方。

会话速度不稳定，出现于特定条件下。

GripHook（Verse Grip Stopper） 在没有仿真运行时未能正常释放。

Inverse3 超时设置过短，导致启动较慢的设备陷入断连循环。

在 Windows 上停止服务时未彻底清理 — 关闭时 HTTP 服务器并非总能被清理。

重连循环，发生于服务向旧版固件发送不受支持的命令时。

蓝牙设备枚举在装有蓝牙适配器的系统上大量刷写日志。

连续多次重启服务时崩溃。

无线 Verse Grip 接收器卡死，发生于 Ubuntu 笔记本电脑睡眠/唤醒之后。

无线 Verse Grip 握手（Linux 和 macOS）在首次检测尝试失败时，现在能正确回退。

MacOS 配置文件位置 — 配置现在存储于 ~/Library/Application Support/ 中，而非错误的路径。

Linux 和 macOS 上的 SIGSEGV 信号处理 — 启用多线程崩溃捕获时，进程不再对致命信号陷入循环。

跨会话命令覆盖 — 一个会话中的配置命令可能会被另一会话的命令静默替换；现在会被正确过滤并合并。

探测命令覆盖配置 — 监控会话（例如 Haply Hub）发送 probe_position 时，不再静默覆盖待处理的 basis / preset / profile 变更。

原型握把显示问题 — 原型硬件被错误地显示为标准握把，而非自定义握把。

旧版 `set_basis` 矩阵约定重新生效，供尚未迁移的客户端使用。

Inverse3 force kick 在会话断开时不再产生残余力峰值。

WebSocket 连接丢失竞争条件出现在快速连接/断开循环期间。

WebSocket `session_id` 在部分外发负载中被序列化为 0。

在 Windows 上，--log-level 与 --dev 同时使用时现在会被遵循（此前会被静默重置为 debug）。

弃用项 {#deprecations}

仍可正常使用，但将在未来的主要版本中移除。在适用的情况下，响应中会包含 deprecation_warning 字段。

| 已弃用 | 替代项 |

|---|---|

| POST /force_scale | POST /settings/devices/inverse*/filters/force_scale/gain |

| POST /gravity_compensation | POST /{device}/{id}/config/gravity_compensation |

| POST /torque_scaling | POST /{device}/{id}/config/torque_scaling |

| POST /device_handedness | POST /{device}/{id}/config/handedness |

| POST /serial_enable | POST /settings/communication/serial/enabled |

| POST /experimental/features/grip_dropped_simulation_stopper | Settings API |

| POST /experimental/features/screensaver_enable | Settings API |

| WebSocket command_data.values | position, vector, angles, torques |

| WebSocket set_angular_torque | set_angular_torques |

| WebSocket probe_cursor_position | probe_position |

| WebSocket set_coordinate_origin | configure.preset |

| WebSocket 会话级 set_basis | configure.basis |

兼容性说明 {#compatibility-notes}

相较 3.4.19，没有硬性的破坏性变更。对现有集成有两点温和提示：

已弃用的 HTTP 端点现在会在响应中包含 deprecation_warning 字段——严格校验响应 schema 的客户端应允许该额外字段。

WebSocket command_data 中的 values 字段已弃用，但仍会被解析；建议优先使用具名字段。

教程与文档 {#tutorials-documentation}

新教程：05 Position Control、06 Combined（Inverse3 + Verse Grip）、07 Basis and Mount、08 HTTP Remote Configurator、09 WebSocket Remote Control、10 Event Stream Listener。

新增 Glaze 变体：为每个 C++ 教程新增 cpp-glz/ 变体，与现有的 nlohmann/json 变体并存。

所有教程已重写，以适配 v3.1 API（端口 10001、configure.preset、具名命令字段、print_state() 辅助函数）。

移除了旧的 Verse Grip Stopper 教程——已由新的 Combined 教程取代。

公开文档已更新，涵盖 SDK 指南、API 参考和硬件页面。

所有下载

此版本的所有可用下载:

Inverse Service 安装程序 3.5.0 Windows

Windows

制品: haply-inverse-service-windows-x64-3.5.0.exe

下载

Inverse Service 安装程序 3.5.0 Ubuntu 24.04

Ubuntu 24.04

制品: cpack/haply-inverse-service-ubuntu2404-amd64-3.5.0.deb

下载

Inverse Service 安装程序 3.5.0 Ubuntu 22.04

Ubuntu 22.04

制品: cpack/haply-inverse-service-ubuntu2204-amd64-3.5.0.deb

下载

Inverse Service 安装程序 3.5.0 Ubuntu 22.04 arm64

Ubuntu 22.04 arm64

制品: cpack/haply-inverse-service-ubuntu2204-arm64-3.5.0.deb

下载

Inverse Service 安装程序 3.5.0 Ubuntu 24.04 arm64

Ubuntu 24.04 arm64

制品: cpack/haply-inverse-service-ubuntu2404-arm64-3.5.0.deb

下载

Inverse Service 安装程序 3.5.0 Mac OS

Mac OS

制品: cpack/haply-inverse-service-macos-aarch64-3.5.0.dmg

下载

返回 installer 版本列表

加载中...