独立Inverse

Haply 这是一款面向设备的服务运行时及运行时 SDK，已整合到一个便捷的安装程序中。它也被称为“external”服务。

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 接口。此外，该版本还包含了过去一年中积累的 bug 修复和用户体验改进。

亮点 {#highlights}

统一的 3D 数学层——这是一个可组合的变换管道，配备了用于设备基底（坐标系）、安装变换、工作空间变换和导航变换的一流基本元素。此外，还支持在本地、会话、应用程序和内部空间之间进行显式变换。

气泡导航——可通过具有形状的区域（SDF 基元）在大型虚拟工作区内移动。支持基于速度映射的速率控制、考虑滞后效应的碰撞检测，并可根据需要应对光标方向的漂移。可通过 HTTP 和 WebSocket 进行完全配置，并支持应用空间内的往返通信。

带类型的事件流——这是专用于设备生命周期、安全警报、校准、电池状态、控制速率警告以及不建议操作提示的专用 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）中进行选择，或发送显式转换。如果手动更改挂载，预设将自动 自定义 将切换至。

命名命令字段 — 通用的 价值观 代替数组，位置、向量、角度、扭矩 使用。

设置角扭矩 但 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 种类型化事件类别。

可观测性 {#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、旋转 = 单位矩阵、比例 = 1）现在默认不会包含在输出中。这样可以减小有效载荷大小，并恢复与旧版 Unity 包中 4 KB 消息上限的兼容性。对于希望将所有字段都包含在输出中的消费者，提供了两个高级设置（序列化/显式字段、序列化/强制完成转换）已准备就绪。

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

服务器默认仅支持 localhost — 网络访问是，通信/绑定所有接口 可以在设置中明确启用该功能。

设备选择器的通配符使用前缀匹配语法（例如： inverse （适用于 Inverse 系列的所有设备）。

倾销指令 ，force_gate 并列 配置 已跳转至地图。

现已替换为轮换式文件记录器，并支持设置目录。

模块提供的命令和状态— 模块可以在不更改核心模式的情况下，添加自定义命令、设置字段，并将状态输出嵌入到 WebSocket 帧中。

修正 {#fixes}

在过去一年中修复的漏洞中，影响尤为严重的如下：

会话速度不稳定（在特定条件下）。

GripHook（Verse Grip Stopper）在未运行模拟时无法正确释放。

Inverse3 由于超时时间过短，在启动较慢的设备上会发生断开连接的循环。

Windows 服务停止时未完全关闭— 关机时 HTTP 服务器并未始终被彻底清理。

重新连接循环（当服务向旧版固件发送其不支持的命令时）。

由于蓝牙设备枚举，在配备蓝牙适配器的系统上生成了大量日志。

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

Wireless Verse Grip 适配器卡死（发生在 Ubuntu 笔记本电脑进入睡眠模式后唤醒时）。

在 Linux 和 macOS 系统上，Wireless Verse Grip 的握手过程现在可以在首次检测尝试失败时正确地进行回退。

macOS 设置文件的位置 — 设置中并非路径有误，而是 ~/Library/Application Support/ 现已保存至该处。

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

会话间命令覆盖— 以前，某个会话的配置命令可能会被另一个会话的命令在用户不知情的情况下覆盖，但现在这些命令会得到正确的过滤和合并。

通过探针命令覆盖设置 — 探针位置 发送监控会话（例如：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++ 教程中（cpp-glz/）。

重写所有教程、已支持 v3.1 API（端口 10001、配置预设、带名称的命令字段、print_state() （助手）。

已删除— 旧版的 Verse Grip Stopper 教程已被删除，并替换为新的组合教程。

已更新公开文档（SDK 指南、API 参考、硬件页面）。

所有下载

此版本中可用的所有下载内容：

Inverse Installer 3.5.0Windows

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

下载

返回安装程序的发布页面