独立Inverse

Haply 这是面向设备的服务运行时及运行时 SDK。它们被打包在一个便捷的安装程序中。也称为“外部”服务。

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 数学层——这是一个可组合的变换管道，将设备基准（帧）、安装变换、工作空间变换和导航变换作为一等基本元素提供，同时支持在本地、会话、应用程序和内部空间之间进行显式变换。

气泡导航——通过基于速度映射的速度控制、考虑滞后效应的碰撞检测，以及具有可选光标方向漂移功能的形状区域（SDF 基元），可在大型虚拟工作空间中进行导航。可通过 HTTP 和 WebSocket 进行完全配置，并支持应用空间往返（round-trip）。

类型指定事件流——这是专用于设备生命周期、安全通知、校准、电池、控制周期警报以及弃用提示的专用 WebSocket 事件通道。

设置 API— 这是一个支持 HTTP CRUD、类型提示、范围约束和说明的完整键值设置系统，可替代现有的嵌套配置文件。

一致的设备配置 — 提供一套适用于所有设备的通用 HTTP 路由集： 基础, 安装, 预设, 变, 过滤器, 惯用手, 扭矩缩放, 重力补偿, 首页_返回.

Minverse 及笔同步校准— 设备与笔现可同步进行校准，且在校准状态下，校准状态将保持锁定，直至握柄与设备物理连接为止。

改进 HTTP 的易用性 — 基于索引的设备选择器（不使用 ID，而是通过索引指定设备）、与 WebSocket 共享的统一请求/响应格式、可选使用的 {成功、错误、数据} 信封（?format=json)，提供了通配符会话选择器。

新功能 {#new-features}

设备 {#devices}

Minverse— 本次发布新增了以下官方支持功能：检测、准备流程、安全提醒以及同步校准工作流。

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

支持设备模拟器——能够检测并与软件模拟的设备（配合实际硬件）进行通信。

连接回路保护 — 出现故障的端口将被自动屏蔽， POST /ports/{port}/reset可以将其重置为。

笔连接心跳— 通过应用防弹跳功能，可稳定检测握笔的连接与断开。

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

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

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

用于一次性命令的显式 `configure` 映射 — 按设备分类 基础, 预设, 安装, force_gate, 阻尼按科目和课时 个人资料 以及 基础现在都 配置包含在内。它与输出配置映射相匹配，因此在后续读取传输的内容时，数据将以相同的形式返回。

自定义设备挂载 — 内置工作区预设(默认值, 前臂, 臂部前侧居中, 前大灯, led_front_centered) 您可以选择其中之一，或发送显式的变换参数。如果手动更改挂载方式，预设将自动 自定义将切换为。

命名命令字段 — 位置, 向量, 角度, 扭矩是通用的 价值观 替换数组。

设置角扭矩a set_angular_torque用于替代（单数形式已不再支持）。

会话帧扩展 — 可扩展至 v3.0 和 v3.1 会话帧 配置, 状态, 状态 包含该对象。新的输出字段中包含 current_cursor_force, 当前光标位置, 当前角扭矩, 当前角位置, 控制域, 控制模式, 变, transform_velocity, 更加丰富 config.*，以及 状态.安全（默认情况下为隐藏）包含在内。

部分变换更新 — 挂载、工作区变换、在要修改的子字段所在的探索几何体中（位置, 旋转, 比例尺)只能传输。

HTTP {#http}

GET / — 这是服务版本。

GET/POST/DELETE /settings 以及 /settings/* — 这是一个完整的键值配置 API。

GET /sessions/{session} 以及 GET/POST/DELETE /sessions/{session}/profile.

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

基于索引的设备选择器 — 即使不知道 ID，也可以通过索引指定任意设备（以第一个 Inverse3 为例） /inverse3/0/..., Inverse系列的所有设备 inverse...).

集成请求/响应格式 — POST/GET 请求体与 WebSocket 相同 command_data 由于采用了 JSON 格式，因此为一种传输方式编写的代码在其他传输方式下也能正常运行。

选择性包络 — 在所有路由中 ?format=json可以通过……来激活。 /设置* 以及 GET /home_return基本上是 {成功、错误、数据} 使用该格式。若要使用原始格式，请 ?format=plain请指定。

会话选择器通配符 — 来自个人资料名称 *（任意字符串）和 ?可以使用（单个字符）。

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

活动 {#events}

沟通/活动/港口这是由……提供的专用 WebSocket 事件流。

提供24种指定事件类别，包括设备生命周期、安全（电子制动、异物检测、停机（stall））、校准失败、电池警告、会话警告、低控制周期和临界控制周期、输入有效性验证以及支持终止提示。

可观测性（Observability） {#observability}

在性能分析过程中，日志消息会连同各级别的颜色标记一起传递给 Tracy。

所有 HTTP 处理程序都会应用 Tracy 区域（zone）。

这是主循环的定时统计事件。

可以配置日志目录和服务器主机名（支持 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 负载 — 具有恒等（identity）默认值的 transform 子字段（position = 0, 旋转 = 单位矩阵, 比例 = 1) 默认情况下会在输出中省略，从而减小有效载荷大小，并恢复与旧版 Unity 包中 4 KB 消息限制的兼容性。两项高级设置（序列化/显式字段, 序列化/强制完成转换) 时，可以重新包含所有字段，以满足需要该值的消费者的需求。

减少主循环抖动——即使在解析 JSON 和进行网络传输期间，WebSocket 消息的处理也不会阻塞主循环的 tick。会话 tick 的调度已被提前至响应序列化之前。

服务器默认仅限 localhost — 通信/绑定所有接口 您可以在“设置”中明确允许网络访问。

设备选择器的通配符使用前缀语法（例如： inverse（与 Inverse 系列的所有设备均兼容）。

阻尼指令这个 force_gate与……一起 配置 已跳转至地图。

轮换日志记录器将取代现有的日志记录器，并可配置目录。

模块提供的命令和状态— 模块无需修改核心模式，即可注入自定义命令、配置字段，并在 WebSocket 帧中添加状态输出。

修改内容 {#fixes}

这是过去一年中累计修复的错误，影响最大的项目如下。

在特定条件下曾出现会话速度不稳定的问题。

当模拟未运行时，GripHook（Verse Grip Stopper）无法正确解除的问题。

Inverse3 超时时间过短，导致在启动较慢的设备上反复出现连接中断的问题。

Windows 服务异常停止— 终止时，HTTP 服务器并未始终完成清理。

当服务发送旧版本固件不支持的命令时，会引发重连循环。

在配备蓝牙适配器的系统中，蓝牙设备枚举会导致日志被过度填满的问题。

在连续多次重启服务时发生的崩溃。

Ubuntu 笔记本电脑在从省电模式恢复后，Wireless Verse Grip 适配器会出现卡顿现象。

在 Linux 和 macOS 上，即使Wireless Verse Grip 的握手在首次检测尝试中失败，现在也能正确地进行回退处理。

macOS 设置文件的位置 — 设置现在不再使用错误的路径，而是 ~/Library/Application Support/将保存在……中。

在 Linux 和 macOS上处理 SIGSEGV 信号——如果启用了多线程崩溃捕获，进程在收到致命信号时将不再陷入循环。

会话间命令覆盖— 此前，一个会话的配置命令可能会被另一个会话的命令悄然替换，但现在这些命令会得到正确的过滤和合并。

Probe 命令覆盖设置的问题 — 在监控会话（例如：Haply Hub）中 探针位置 即使发送命令，待处理的basis/preset/profile更改也不会再被静默覆盖。

原型握把标识— 原型硬件被错误地标记为标准握把，而非定制握把。

已进行修改，以便对尚未完成迁移的客户端重新应用旧版 `set_basis` 矩阵规则。

断开会话时，Inverse3 的“强制击退”效果将不再产生残留力量峰值。

在快速连接/断开循环中发生的WebSocket 连接丢失竞态条件。

在某些传输有效载荷中 WebSocket `session_id` 值是 0此前在序列化时出现的问题。

在 Windows 中 --dev 与该选项配合使用时 --日志级别 该选项现在已正确应用（此前会静默 调试 已重置为该等级）。

已弃用的项目 {#deprecations}

虽然目前仍可正常使用，但计划在未来的重大版本中移除。如涉及此情况，请在回复中 弃用警告 包含字段。

| 已停用项目 | 替代项目 |

|---|---|

| POST /force_scale | POSTinverse |

| POST /重力补偿 | 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 | 设置 API |

| POST /experimental/features/screensaver_enable | 设置 API |

| WebSocket command_data.values | 位置, 向量, 角度, 扭矩 |

| WebSocket set_angular_torque | 设置角扭矩 |

| WebSocket 获取光标位置 | 探针位置 |

| WebSocket 设置坐标原点 | 配置预设 |

| WebSocket 会话级 set_basis | configure.basis |

兼容性注意事项 {#compatibility-notes}

3.4.19 版本中没有会导致兼容性问题的变更。关于现有集成的注意事项有两点：

已停用的 HTTP 端点的响应现在 弃用警告 包含该字段。严格验证响应模式的客户端必须允许此附加字段。

WebSocket command_data的 价值观 该字段虽已弃用，但仍会被解析。建议使用命名字段。

教程和文档 {#tutorials-documentation}

新教程：05 位置控制、06 集成（Inverse3 + Verse Grip）、07 Basis 和 Mount、08 HTTP 远程配置器、09 WebSocket 远程控制、10 事件流监听器。

Glaze 新版本: 除了现有的 nlohmann/json 版本外，所有 C++ 教程中还提供了 Glaze 版本（cpp-glz/)已添加。

重写所有教程: v3.1 API（端口 10001， 配置预设, 命名的命令字段, print_state() 已根据（Helper）的要求进行了重写。

已删除原有的 Verse Grip Stopper 教程——现已由新的综合教程取代。

我们已全面更新了SDK指南、API参考和硬件页面等公开文档。

全部下载

此版本的所有可用下载：

Inverse Service 安装程序 3.5.0Windows

Windows

Artifact： 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

下载

返回安装程序发布页面