跳至主要内容
版本：3.5.x

v3.5.0

这是自一年前重写 API 以来我们发布的最大规模更新。3.5.0 版本引入了统一的 3D 数学层、Minverse 全面Minverse 、带类型的事件流、完整的设置 API 以及更简洁的 HTTP 接口——此外还包含过去一年中修复的各类 bug 以及提升用户体验的改进。

亮点​

  • 统一的 3D 数学层——一个可组合的变换管道，包含用于设备基底（帧）、安装变换、工作空间变换和导航变换的一流基元，并支持本地、会话、应用程序和内部空间之间的显式转换。
  • 气泡导航——通过形状区域（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)，以及通配符会话选择器。

新功能​

设备​

  • Minverse — 本次发布中已包含官方支持：检测、就绪序列、安全通知以及同步校准工作流。
  • Ruko和Kingfisher已被认定为官方握把产品类型。
  • 设备模拟器支持——在检测和与真实硬件通信的同时，也能检测和与软件模拟的设备通信。
  • 连接回路保护 — 行为异常的端口将被自动封锁；使用以下命令重置： POST /ports/{port}/reset.
  • 笔身连接心跳检测——带防抖动的可靠握持连接/断开检测。

会话、命令与 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) 关于安装、工作区变换和导航形状。

超文本传输协定​

  • 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*/*/... （适用于所有 Inverse 系列设备）。
  • 统一的请求/响应模式 — POST/GET 请求体使用相同的 command_data JSON 作为 WebSocket 的载体；针对一种传输方式编写的代码同样适用于另一种。
  • 预付邮资信封 来源： ?format=json 在任何路线上； /settings* 和 GET /home_return 默认设置为 {ok, error, data}. 使用 ?format=plain 用于原始形状。
  • 会话选择器通配符 — * （任意序列）和 ? （单个字符）在个人资料名称中。
  • 百分比解码选择器 — %2A, %3A等在路由之前会被解码。

活动​

  • 已启用专用 WebSocket 事件流 communication/events/port.
  • 24 类预定义事件，包括设备生命周期、安全（电子刹车、异物检测、失速）、校准失败、电池警报、会话警告、控制速率过低/临界、输入验证以及弃用提示。

可观测性​

  • 在进行性能分析时，将日志消息转发至 Tracy，并根据级别显示不同颜色。
  • Tracy 会监听每个 HTTP 处理程序。
  • 主循环的定时统计事件。
  • 可配置日志目录和服务器主机名（支持 Docker）。

即将于3.6版本推出​

  • SDF 触觉效果（SDF HFX）——其基础功能已在 3.5 版本中实现（模块、生命周期、模块提供的命令/状态序列化），而公开 API 及完整文档将于 3.6 版本发布。

改进​

  • 带力振荡滤波功能——支持各轴振荡检测、8级渐进式恢复、带滞回的输入确认，以及非对称释放窗口。
  • 运行时强制门控滤波器 — 可通过 configure.force_gate.gain 通过 WebSocket 或 HTTP 传输，并默认保持连接。
  • 主循环最高频率已提升至 32 kHz，以满足高精度应用的需求。
  • 更小的 WebSocket 数据包 — identity-default 转换子字段 (position = 0, rotation = identity, scale = 1) 默认不会显示在输出中，这样既能缩小数据包大小，又能恢复与旧版 Unity 包 4 KB 消息限制的兼容性。两个高级设置（serialization/explicit_fields, serialization/force_complete_transforms) 为有需要的用户恢复所有字段。
  • 降低主循环抖动——WebSocket 消息处理在 JSON 解析和网络发送期间不再阻塞主循环的 tick；会话 tick 的调度被移至响应序列化之前。
  • 服务器默认仅限本地主机访问 — 通过以下方式启用网络访问： communication/bind_all_interfaces 设置。
  • 设备选择器的通配符使用前缀语法 （例如： inverse* （适用于所有 Inverse 系列设备）。
  • 阻尼指令 搬进了 configure 附图 force_gate.
  • 轮换文件记录器取代了之前的版本，并支持配置目录。
  • 模块提供的命令和状态— 模块可以在不修改核心模式的情况下，将自身的命令、配置字段和状态输出注入到 WebSocket 帧中。

修复​

过去一年中修复了诸多问题；最具影响力的修复如下。

  • 在某些情况下，会话速度不稳定。
  • 当未运行任何模拟时，GripHook（Verse Grip Stopper）无法顺利释放。
  • Inverse3 过于严格，导致启动缓慢的设备出现断连循环。
  • Windows 上的未清理服务停止— 关机时 HTTP 服务器并非总能被正确清理。
  • 当服务向旧版固件发送不支持的命令时，会触发重连循环。
  • 蓝牙设备枚举导致配备蓝牙适配器的系统日志被淹没。
  • 连续多次重启服务时发生崩溃。
  • 在 Ubuntu 笔记本电脑上，Wireless Verse Grip 适配器在睡眠/恢复后会卡死。
  • 在 Linux 和 macOS 上，当首次检测尝试失败时，Wireless Verse Grip 的握手过程现在会正确地进行回退。
  • MacOS 配置文件的位置 — 配置文件现存储于 ~/Library/Application Support/ 而不是走错路。
  • Linux 和 macOS 上的 SIGSEGV 信号处理——启用多线程崩溃捕获后，进程在收到致命信号时不再进入无限循环。
  • 跨会话命令覆盖— 来自一个会话的配置命令可能会被另一个会话的命令无提示地替换；现在这些命令会被正确过滤并合并。
  • 探针命令覆盖配置 — 监控会话（例如Haply ）的发送 probe_position 不再在后台静默覆盖待处理的基础设置/预设/配置文件更改。
  • 原型握把显示——原型硬件被错误地显示为标准握把，而非定制握把。
  • 传承 set_basis 矩阵约定 再次向尚未完成迁移的客户致以敬意。
  • 在会话断开时Inverse3 踢腿不再产生残余力突增。
  • 在快速连接/断开循环中，WebSocket 连接会因竞争条件而丢失。
  • WebSocket session_id 曾以连载形式发表于 0 在某些发出的有效载荷中。
  • 在 Windows 上， --log-level 现在，当与……结合使用时，该设置将被采纳 --dev （此前已静默重置为 debug).

折旧​

目前仍可正常使用，但将在未来的重大版本中移除。响应包括一个 deprecation_warning （如适用，请填写此处）。

已停用替换
POST /force_scalePOST /settings/devices/inverse*/filters/force_scale/gain
POST /gravity_compensationPOST /{device}/{id}/config/gravity_compensation
POST /torque_scalingPOST /{device}/{id}/config/torque_scaling
POST /device_handednessPOST /{device}/{id}/config/handedness
POST /serial_enablePOST /settings/communication/serial/enabled
POST /experimental/features/grip_dropped_simulation_stopper设置 API
POST /experimental/features/screensaver_enable设置 API
WebSocket command_data.valuesposition, vector, angles, torques
WebSocket set_angular_torqueset_angular_torques
WebSocket probe_cursor_positionprobe_position
WebSocket set_coordinate_originconfigure.preset
WebSocket 会话级 set_basisconfigure.basis

兼容性说明​

与 3.4.19 相比，没有重大兼容性变更。针对现有集成，有两点需注意：

  1. 已弃用的 HTTP 端点现在包含一个 deprecation_warning 响应中的字段——严格验证响应模式的客户端应允许该额外字段。
  2. "(《世界人权宣言》) values WebSocket 中的字段 command_data 该写法已弃用，但仍会被解析；建议使用命名字段。

教程与文档​

  • 新教程：05 位置控制，06 组合（Inverse3 Verse Grip），07 基座与安装，08 HTTP 远程配置器，09 WebSocket 远程控制，10 事件流监听器。
  • 新釉色款 在每个 C++ 教程中（cpp-glz/) 与现有的 nlohmann/json 变体并行使用。
  • 所有教程均已重写 适用于 v3.1 API（端口 10001， configure.preset，命名为命令字段， print_state() （助手）。
  • 已删除旧版的Verse Grip Stopper教程——现已由新版综合教程取代。
  • 已更新 SDK 指南、API 参考和硬件页面中的公开文档。