独立Inverse

Haply 设备的运行时服务和运行时SDK。整合到一个便捷的安装程序中。也称为“外部”服务。

v3.5.0

发布于 2026年4月23日下午4点57分

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

版本说明

Haply SDK 3.5.0

这是自一年前重写 API 以来规模最大的一次版本更新。3.5.0 版本引入了统一的 3D 数学层、对 Minverse 的全面支持、类型化的事件流、功能齐全的参数 API 以及更简洁的 HTTP 接口——此外还包含一年来的 bug 修复和易用性改进。

亮点

统一的3D数学层——一个可组合的变换管道，配备了一级基元，用于设备基座（帧）、编辑变换、工作空间变换和导航变换，并支持在局部空间、会话空间、应用程序空间和内部空间之间进行显式转换。

气泡导航——通过形状定义的区域（SDF 基本图形）在大型虚拟工作区中导航，具有与速度成比例的流速控制、考虑滞后效应的碰撞检测以及可选的向光标漂移功能。可通过 HTTP 和 WebSocket 进行完全配置，并支持在应用程序空间内双向通信。

类型化事件流——一个专用于设备生命周期、安全警报、校准、电池状态、检查频率提醒以及弃用通知的 WebSocket 事件通道。

参数 API——一个完整的键值参数系统，支持 HTTP CRUD 操作、类型提示、范围约束和描述，取代了旧版的嵌套配置文件。

设备配置的一致性 — 每台设备仅有一组 HTTP 路由： 基础, 安装, 预设, 变, 过滤器, 惯用手, 扭矩缩放, 重力补偿, 首页_返回.

Minverse 与触控笔的同步校准——设备及其触控笔现可同步校准；只要手柄未被物理固定，校准状态将保持锁定。

HTTP 的易用性改进 — 按索引选择设备（根据索引定位设备，无需 ID），与 WebSocket 共享的统一请求和响应结构，封装层 {成功、错误、数据} 需启用 (?format=json) 以及通配符会话选择器。

新功能

设备

Minverse——此版本已正式支持以下功能：检测、准备流程、安全通知以及同步校准流程。

Ruko和Kingfisher被认定为官方手柄产品类型。

设备模拟器的支持——在与真实硬件并行运行的同时，检测与由软件模拟的设备进行通信。

防止连接循环 — 故障端口会被自动封锁；重置时使用 POST /ports/{port}/reset.

笔尖固定状态信号——可靠检测笔柄的安装与拔出，并具有防反弹功能。

会话、命令和 WebSocket

会话配置文件的筛选与持久化——会话会声明一个配置文件名称和所需的 SDK 版本，服务会在两次连接之间记住这些信息；客户端和监控工具可以根据该配置文件对会话进行筛选和定位。

按会话分批处理命令——一个运行缓慢的会话不再会阻塞另一个会话。

针对特定命令的`configure`详解词典 — 基础, 预设, 安装, force_gate, 阻尼 按设备计算，以及 个人资料 et 基础 按会话，现已全部汇总至 配置 — 与输出配置词典保持一致，确保您发送的内容与读取到的内容相符。

可自定义的设备组装 — 选择一个内置的工作区预设（默认值, 前臂, 臂部前侧居中, 前大灯, led_front_centered) 或发送显式转换；对剪辑的任何手动修改都会自动将预设切换为 自定义.

命名控制字段 — 位置, 向量, 角度, 扭矩 替换通用表格 价值观.

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

会话帧扩展 — v3.0 和 v3.1 版本的会话帧现在包含可扩展对象 配置, 状态 et 状态; 新的输出字段包括 current_cursor_force, 当前光标位置, 当前角扭矩, 当前角位置, 控制域, 控制模式, 变, transform_velocity, des简体中文（大陆） config.* 丰富了并 状态.安全 （默认隐藏）。

变换的部分更新 — 请仅发送您想要修改的子字段（位置, 旋转, 比例尺) 用于剪辑、工作空间的调整以及导航方式。

HTTP

GET / — 服务版本。

GET/POST/DELETE /settings et /settings/* — API complète de paramètres clé-valeur.

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

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

按索引分类的设备选择器 — 只需用食指指向任意设备，无需知道其标识符（/inverse3/0/... 关于第一篇Inverse3 ； inverse... （适用于 Inverse 系列的所有设备）。

统一的请求和响应结构 — POST/GET 请求体使用相同的 JSON 结构 command_data 例如 WebSocket；为一种传输方式编写的代码在另一种传输方式上也能正常运行。

可选信封 通过 ?format=json 在任何道路上； /设置* et GET /home_return utilisent {成功、错误、数据} 默认情况下。请使用 ?format=plain 以获得原始结构。

会话选择器中的通配符 — * （任意字符序列）和 ? （仅一个字符）出现在个人资料名称中。

以百分比形式显示的选通器 — %2A, %3A, 等在路由之前会被解码。

活动

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

24 类典型事件，包括设备生命周期、安全（紧急制动、异物检测、失速）、校准失败、电池警报、会话警告、控制频率过低或处于临界状态、输入验证以及功能降级通知。

可观测性

在性能分析过程中，已将日志消息发送给Tracy，并根据严重程度进行了颜色标注。

每个HTTP管理器上的Tracy区域。

主循环的时间统计事件。

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

3.6 版本即将推出

SDF 触觉效果（SDF HFX）——其基础已在 3.5 版中奠定（包括模块、生命周期以及由模块提供的命令和状态序列化），公共 API 将在 3.6 版中随附完整的文档一并发布。

改进

力振荡滤波——按轴检测振荡、8步渐进恢复、带滞后效应的输入投票以及非对称释放窗口。

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

为主循环的最大频率提升至32kHz，以满足高精度应用的需求。

WebSocket 有效负载减少 — 默认值为恒等映射的变换子域（position = 0, 旋转 = 单位矩阵, 比例 = 1) 在默认输出中被省略，这既减小了有效载荷的大小，又恢复了与旧版 Unity 包中 4 KB 消息限制的兼容性。两个高级参数（序列化/显式字段, 序列化/强制完成转换) 为有需要的消费者重新添加所有字段。

主循环的代码精简——在解析 JSON 和进行网络传输期间，WebSocket 消息的处理不再阻塞主循环；会话周期的调度已被安排在响应序列化之前。

服务器默认仅限于 localhost — 使用该参数启用网络访问 通信/绑定所有接口.

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

减震控制 已被移至该对象中 配置, 紧邻 force_gate.

轮转文件日志记录取代了之前的方案，并配备了一个可配置的目录。

模块提供的命令和状态——模块可以在不修改基础模式的情况下，将自身的命令、配置字段和状态输出注入到 WebSocket 帧中。

更正

一年来的错误修复；最重要的修复内容如下。

在某些情况下，会话速度不稳定。

当没有进行任何模拟时，GripHook（Verse Grip Stopper）无法正常松开。

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

Windows 服务停止异常——停止时 HTTP 服务器并非总是被清理干净。

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

在配备蓝牙适配器的系统上，蓝牙设备枚举会使日志过载。

服务连续重启时发生死机。

在 Ubuntu 笔记本电脑上，Verse Grip 无线适配器在进入休眠状态并恢复后无法正常工作。

在 Linux 和 macOS 上，当首次检测尝试失败时，Verse Grip 无线手柄现在会正确切换到备用方案。

MacOS 系统中配置文件的位置 — 配置现已保存至 ~/Library/Application Support/ 而不是走错路。

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

会话间命令覆盖问题——一个会话的配置命令可能会被另一个会话的命令在后台静默覆盖；现在这些命令会经过过滤并正确合并。

覆盖配置的探头命令 — 监控会话（例如：Haply Hub）会发送 探针位置 不再悄无声息地覆盖待处理的基础、预设或配置文件修改。

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

对于尚未迁移的客户端，再次遵循了从 `set_basis` 继承的基类约定。

Inverse3在断开会话时产生的力脉冲不再产生残余力峰值。

在快速连接和断开循环过程中，发生连接丢失时的 WebSocket 并发条件。

WebSocket `session_id` 被分段为 0 在某些出站有效载荷中。

在Windows 上， --日志级别 现在，当与……结合使用时，该规则已得到遵守 --dev （此前它会被静默地重置为 调试).

折旧

这些功能目前仍可使用，但将在未来的一个主要版本中移除。答案包含一个字段 弃用警告 如有必要。

| 已弃用 | 替代方案 |

|---|---|

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

兼容性说明

与 3.4.19 相比，没有重大兼容性问题。针对现有集成有两点 minor 说明：

已弃用的 HTTP 端点现在包含一个字段 弃用警告 在响应中——严格验证响应模式的客户端必须接受此附加字段。

Le champ 价值观 WebSocket command_data 该方法已过时，但仍会被分析；请优先使用命名字段。

教程和文档

新教程：05 位置控制、06 组合（Inverse3 + Verse Grip）、07 基础与安装、08 远程 HTTP 配置器、09 WebSocket 远程控制、10 事件流监听器。

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

所有已重写的教程 对于 API v3.1（端口 10001， 配置预设, 命名命令字段、实用函数 print_state()).

已撤下旧版《Verse Grip Stopper》教程，并替换为新版《组合教程》。

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

所有下载

该版本的所有可用下载：

Inverse Service Installateur 3.5.0Windows

Windows

构建产物： haply-inverse-service-windows-x64-3.5.0.exe

下载

Inverse Service Installateur 3.5.0 Ubuntu 24.04

Ubuntu 24.04

构建产物： cpack/haply-inverse-service-ubuntu2404-amd64-3.5.0.deb

下载

Inverse Service Installateur 3.5.0 Ubuntu 22.04

Ubuntu 22.04

构建产物： cpack/haply-inverse-service-ubuntu2204-amd64-3.5.0.deb

下载

Inverse Service Installateur 3.5.0 Ubuntu 22.04 arm64

Ubuntu 22.04 arm64

构建产物： cpack/haply-inverse-service-ubuntu2204-arm64-3.5.0.deb

下载

Inverse Service Installateur 3.5.0 Ubuntu 24.04 arm64

Ubuntu 24.04 arm64

构建产物： cpack/haply-inverse-service-ubuntu2404-arm64-3.5.0.deb

下载

Inverse Service Installateur 3.5.0 Mac OS

Mac OS

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

下载

返回安装程序版本列表