跳转至主要内容

v3.5.0

这是自一年前API改版以来，我们迄今为止功能最全面的版本。3.5.0版本引入了统一的3D数学层、对Minverse 的全面支持、类型化的事件流、完整的设置API以及更清晰的HTTP接口——此外，过去一年中我们还进行了大量的错误修复和易用性改进。

亮点​

  • 统一的3D数学层——一个可组合的变换管道，包含用于设备基面（帧）、安装变换、工作空间变换和导航变换的完整基本元素，以及本地空间、会话空间、应用空间和内部空间之间的显式转换。
  • 气泡导航——在大型虚拟工作区中，通过形状区域（SDF 基元）进行导航，具备基于速度的速率控制、考虑滞后效应的碰撞检测以及可选的光标漂移功能。可通过 HTTP 和 WebSocket 进行完全配置，数据往返传输通过 App-Space 实现。
  • 标准化事件流——专用于设备生命周期、安全警报、校准、电池状态、采样率警报以及过时功能提示的独立 WebSocket 事件通道。
  • Settings-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现已被认定为 Griff 的官方产品类型。
  • 对设备模拟器的支持——除了真实硬件之外，还可以识别并调用软件模拟的设备。
  • 防止环路 – 存在问题的端口将被自动封锁；要重置它们，请使用 POST /ports/{port}/reset.
  • 用于把手检测的心跳检测——通过去抖动功能，可靠地检测把手何时被握住或松开。

会话、命令和 WebSocket​

  • 会话配置文件的过滤与持久化——会话会指定一个配置文件名称和所需的 SDK 版本；该服务会在多次重新连接后仍记住这两项信息。客户端和监控工具可以基于该配置文件对会话进行过滤并有针对性地进行操作。
  • 每个会话的命令缓冲区——一个运行缓慢的会话不再会拖慢其他会话的速度。
  • Explizite configure-一次性命令映射表 – basis, preset, mount, force_gate, damping 每台设备以及 profile und basis 现在，每个 pro Session 中的所有内容都将 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)，适用于 Mount、工作区转换和导航表单。

超文本传输协定​

  • 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；为一种传输方式编写的代码，在另一种传输方式下同样适用。
  • 可选的可启用包络 über ?format=json 在每条航线上； /settings* und GET /home_return 默认使用 {ok, error, data}. 请使用 ?format=plain 用于粗结构。
  • 会话选择器中的通配符 – * (任意字符串) 和 ? （单个字符）在用户名中。
  • 百分比编码的选择器 – %2A, %3A usw. 将在路由之前进行解码。

事件​

  • 在...上创建专属的 WebSocket 事件流 communication/events/port.
  • 24 类标准化事件，包括设备生命周期、安全（电子刹车、异物检测、卡滞）、校准错误、电池警告、会话警告、低速率和临界速率、输入验证以及过时功能提示等。

可观测性​

  • 在性能分析过程中，日志消息会以不同级别对应的颜色转发至 Tracy。
  • 每个 HTTP 处理程序的 Tracy-Zonen。
  • 包含主循环计时统计数据的事件。
  • 可配置的日志目录和可配置的服务器主机名（支持 Docker）。

3.6 版本展望​

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

改进​

  • 力振荡滤波——基于轴的振荡检测、八级渐进式恢复、带滞回的输入调谐以及非对称启用窗口。
  • 运行时力门滤波器 – 可通过以下方式进行配置 configure.force_gate.gain 通过 WebSocket 或 HTTP，并永久存储默认值。
  • 为主循环的最大频率提高至32kHz，以满足精密应用的需求。
  • 较小的 WebSocket 有效载荷 – 变换子域默认采用恒等值（position = 0, rotation = identity, scale = 1) 默认情况下不会输出。这样可以减少有效载荷大小，并恢复与旧版 Unity 包 4 KB 消息限制的兼容性。两个高级设置（serialization/explicit_fields, serialization/force_complete_transforms) 恢复所有字段，供需要这些字段的应用程序使用。
  • 主循环抖动更小——在解析 JSON 以及进行网络传输时，WebSocket 消息的处理不再阻塞主循环的时钟；会话的时钟调度已被移至响应序列化之前。
  • 默认情况下，仅可通过 localhost 访问服务器 – 若要启用网络访问，请启用该设置 communication/bind_all_interfaces.
  • 设备选择器中的通配符使用前缀语法 （例如： inverse* （适用于 Inverse 系列的所有设备）。
  • 衰减指令 与……一起 force_gate 模内成型 configure-地图已移动。
  • 轮转文件记录器取代了原有的记录器；目录可配置。
  • 模块提供的命令和状态——模块可以在 WebSocket 帧中引入自己的命令、配置字段和状态输出，而无需更改核心模式。

错误修复​

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

  • 在特定条件下，会话速度不稳定。
  • 当未运行任何仿真时，GripHook（Verse Grip Stopper）无法正常释放。
  • Inverse3-超时设置过于激进，导致启动较慢的设备出现连接循环。
  • Windows 服务未正常关闭——关机时 HTTP 服务器并非总能被正确清理。
  • 当服务向旧版固件发送不支持的命令时，会触发重连循环。
  • 在配备蓝牙适配器的系统上，蓝牙设备的枚举操作导致日志被淹没。
  • 连续多次重启服务时发生崩溃。
  • 在 Ubuntu 笔记本电脑上，Verse-Grip 无线适配器在进入休眠状态/唤醒后出现卡死现象。
  • 在 Linux 和 macOS上，无线 Verse Grip 的握手机制现在会在首次检测尝试失败时正确地回退到备用方案。
  • macOS 配置文件的位置 — 配置现已保存在 ~/Library/Application Support/ 却被保存在了错误的路径中。
  • Linux 和 macOS 上的 SIGSEGV 信号处理——当启用了多线程崩溃跟踪时，进程在遇到致命信号后将不再进入循环。
  • 跨会话覆盖命令——来自一个会话的配置命令可能会被另一个会话中的命令悄然替换；现在这些命令会被正确过滤并合并。
  • 探针命令会覆盖配置 — 监控会议（例如Haply Hub），这些 probe_position 不再默认发送或覆盖对基础设置/预设/配置文件的待处理更改。
  • 原型手柄的显示— 原型硬件被错误地显示为标准手柄，而非自定义手柄。
  • 过时的矩阵约定来自 set_basis 将再次将尚未迁移的客户端纳入考虑范围。
  • Inverse3在断开会话时产生的冲击力不再产生残余力峰值。
  • 在WebSocket连接丢失且连接与断开操作快速连续发生时，会出现竞态条件。
  • WebSocket session_id 在某些发出的有效载荷中被用作 0 已序列化。
  • 在 Windows 中， --log-level 现在还可与……搭配使用 --dev 已予以考虑（此前该值被默认设为 debug （已重置）。

过时的元素​

目前仍可正常使用，但将在未来的主版本中移除。回复中可能包含一个字段 deprecation_warning.

已过时Ersatz
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 参考和硬件页面中进行了更新。