独立Inverse

Haply 设备的 Service Runtime 和 Runtime 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 进行完全配置，数据往返传输通过 App-Space 实现。

标准化事件流——专用于设备生命周期、安全警报、校准、电池状态、采样率警报以及过时功能提示的独立 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, 阻尼 每台设备以及 个人资料 und 基础 现在，每次会议中所有在 配置 已执行——根据输出配置映射进行调整，以确保发送的内容与读取到的内容一致。

可定制的设备安装 — 请选择一个集成的工作区预设（默认值, 前臂, 臂部前侧居中, 前大灯, led_front_centered) 或发送一个明确的变换；手动更改蒙太奇会自动将预设切换为 自定义 嗯。

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

设置角扭矩 替换 set_angular_torque （单数形式已过时）。

会话帧的扩展 — v3.0 和 v3.1 版本的会话帧现在包含可扩展对象 配置, 状态 und 状态; 新的输出字段包括 current_cursor_force, 当前光标位置, 当前角扭矩, 当前角位置, 控制域, 控制模式, 变, transform_velocity, 更全面的 config.*-菲尔德以及 状态.安全 （默认隐藏）。

部分转换更新 — 请仅发送您希望修改的子字段（位置, 旋转, 比例尺) 在组装、工作域转换和导航形式方面。

HTTP {#http}

GET / — 服务版本。

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

GET /sessions/{session} und GET/POST/DELETE /sessions/{session}/profile.

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

基于索引的设备选择器 — 通过索引访问每个设备，而无需知道其 ID（/inverse3/0/... 用于首台Inverse3 设备； inverse... （适用于所有 Inverse 系列设备）。

统一的询问和答复格式 — POST 和 GET 请求的请求体使用相同的 command_data-JSON结构，例如WebSocket；为一种传输方式编写的代码，在另一种传输方式下也能正常运行。

可选信封 — 可通过以下方式启用 ?format=json 在每条航线上； /设置* und GET /home_return 默认使用 {成功、错误、数据}. 请使用 ?format=plain 用于粗结构。

会话选择器中的通配符 — * （任意字符串）和 ? （单个字符）在用户名中。

带百分比编码的选择器 — %2A, %3A usw. 将在路由之前进行解码。

事件 {#events}

专用的 WebSocket 事件流位于 沟通/活动/港口.

24 类标准化事件，包括设备生命周期、安全（电子刹车、异物检测、卡滞）、校准错误、电池警告、会话警告、低速率和临界速率、输入验证以及过时功能提示。

可观测性 {#observability}

在性能分析过程中，日志消息会以与级别相关的颜色转发至 Tracy。

每个 HTTP 处理程序的 Tracy-Zonen。

包含主循环计时统计数据的事件。

可配置的日志目录和可配置的服务器主机名（支持 Docker）。

即将登陆 3.6 版本 {#coming-in-36}

SDF 触觉效果（SDF HFX）——其基础已在 3.5 版本中奠定（模块、生命周期、模块端提供的命令和状态数据的序列化）；公开 API 将于 3.6 版本中随完整文档一同发布。

改进 {#improvements}

动力振动滤波——按轴进行振动检测、八级渐进式恢复、带滞回的触发调谐以及非对称启用窗口。

运行时力门滤波器 — 可通过以下方式进行配置 configure.force_gate.gain，通过 WebSocket 或 HTTP，并采用持久的默认值。

将主环路最高频率提高至32 kHz，以满足精密应用的需求。

较小的 WebSocket 有效载荷 — 变换——具有恒等式默认值的子域 (position = 0, 旋转 = 单位矩阵, 比例 = 1) 默认情况下不会输出。这样可以减少有效载荷大小，并恢复与旧版 Unity 包 4 KB 消息限制的兼容性。两个高级设置（序列化/显式字段, 序列化/强制完成转换) 重新包含所有字段，供需要这些字段的客户端使用。

主循环的抖动更小——WebSocket 消息处理在 JSON 解析和网络发送期间不再阻塞主循环的时钟；会话的时钟调度已被移至响应序列化之前。

服务器默认仅在 localhost 上运行 — 您可通过设置启用网络访问 通信/绑定所有接口.

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

衰减指令 与……一起 force_gate 模内成型 配置- 分配已推迟。

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

模块提供的命令和状态— 模块可以在不影响核心架构的情况下，引入自定义命令、配置字段，并将状态输出插入到 WebSocket 帧中。

错误修复 {#fixes}

这是充满错误修复的一年；以下列出了其中最有效的修复措施。

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

当未运行任何仿真时，GripHook（Verse Grip Stopper）无法正常释放。

Inverse3-超时设置过于严格，导致在启动较慢的设备上出现连接中断循环。

Windows 上的服务未正常关闭——HTTP 服务器在关闭时并非总是被清理干净。

如果服务向旧版固件发送了不受支持的命令，则重新连接循环。

在配备蓝牙适配器的系统上，蓝牙设备列表导致日志被淹没。

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

在 Ubuntu 笔记本电脑上，Wireless-Verse-Grip 适配器在进入待机状态并恢复运行后会出现卡死现象。

在 Linux 和 macOS上，Wireless-Verse-Grip-Handshake现在会在首次检测尝试失败时正确地转而使用备用方案。

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

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

跨会话命令覆盖— 来自一个会话的配置命令可能会被另一个会话中的命令悄然覆盖；现在这些命令会被正确过滤并合并。

探针命令会覆盖配置 — 监控会话（例如Haply Hub），这些 探针位置 不再默认发送或覆盖对基础设置/预设/配置文件的待处理更改。

原型控件的显示— 原型硬件被错误地显示为标准控件，而非自定义控件。

对于尚未迁移的客户端，将重新采用较早的 `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 基础与安装、08 HTTP 远程配置器、09 WebSocket 远程控制、10 事件流监听器。

新型釉料 所有 C++ 教程 (cpp-glz/) 除现有的 nlohmann/json 变体之外。

所有教程均已修订 适用于 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 Installer 3.5.0 Ubuntu 24.04

Ubuntu 24.04

软件包： cpack/haply-inverse-service-ubuntu2404-amd64-3.5.0.deb

下载

Inverse Installer 3.5.0 Ubuntu 22.04

Ubuntu 22.04

软件包： cpack/haply-inverse-service-ubuntu2204-amd64-3.5.0.deb

下载

Inverse Installer 3.5.0 Ubuntu 22.04 arm64

Ubuntu 22.04 arm64

软件包： cpack/haply-inverse-service-ubuntu2204-arm64-3.5.0.deb

下载

Inverse Installer 3.5.0 Ubuntu 24.04 arm64

Ubuntu 24.04 arm64

软件包： cpack/haply-inverse-service-ubuntu2404-arm64-3.5.0.deb

下载

Inverse Installer 3.5.0 Mac OS

Mac OS

构建包： cpack/haply-inverse-service-macos-aarch64-3.5.0.dmg

下载

返回安装程序版本页面