跳转至正文

v3.5.0

这是自一年前重写 API 以来规模最大的版本发布。3.5.0 引入了统一的 3D 数学层、对Minverse 的全面支持、类型化的事件流、完整的配置 API 以及更加简洁的 HTTP 接口。此外，该版本还包含了过去一年中修复的各项错误以及对易用性的改进。

主要内容​

  • 集成 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 — 本次发布正式支持以下功能：设备检测、就绪（ready）序列、安全提示以及同步校准工作流。
  • Ruko和Kingfisher被认定为官方握把产品类型。
  • 支持设备模拟器——能够检测并与软件模拟的设备（配合实际硬件）进行通信。
  • 连接回路保护 — 运行异常的端口将被自动封锁， POST /ports/{port}/reset将其重置为。
  • 笔身安装心跳监测——通过应用Dibounce算法，可稳定检测笔握的安装与拆卸。

会话、命令和 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_torquesa 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 为例） /inverse3/0/..., 对于 Inverse 系列的所有设备 /inverse*/*/...).
  • 集成请求/响应格式 — POST/GET 请求体与 WebSocket 中使用的相同 command_data 使用 JSON 格式。基于一种传输方式编写的代码在其他传输方式下也能正常运行。
  • 选择性包络 — 在所有路由中 ?format=json可以通过……来激活， /settings* 以及 GET /home_return默认情况下 {ok, error, data}使用。如果需要原始格式，请 ?format=plain使用。
  • 会话选择器通配符 — 来自个人资料名称 *将任意字符串， ?表示单个字符。
  • 百分比解码的选择器 — %2A, %3A 等在路由之前会被解码。

活动​

  • communication/events/port这是其专用的 WebSocket 事件流。
  • 共有 24 种指定类型的事件类别，包括设备生命周期、安全（电子制动、异物检测、失速）、校准失败、电池提醒、会话警告、控制周期过低/临界、输入验证以及支持终止提示。

观测性​

  • 在性能分析过程中，日志消息会连同各级别对应的颜色一起传递到 Tracy。
  • 所有 HTTP 处理程序都已配置了 Tracy 区域。
  • 主循环定时统计事件。
  • 可以配置日志目录和服务器主机名（支持 Docker）。

3.6 计划中的功能​

  • 基于SDF 触觉效果（SDF HFX）的功能已纳入 3.5 版本（模块、生命周期以及模块提供的命令/状态序列化）。公开 API 预计将随完整文档一同在 3.6 版本中发布。

改进内容​

  • 力振动滤波——包括按轴检测振动、8级渐进式恢复、采用滞后效应的进入投票，以及非对称解除区间。
  • 运行时强制门控滤波器 — 来自 WebSocket 或 HTTP configure.force_gate.gain可以由……组成，并提供持久存储的默认值。
  • 将主循环的最大频率提高至 32 kHz（适用于精密应用领域）。
  • 更小的 WebSocket 负载 — 默认的恒等（identity）变换子域（position = 0, rotation = identity, scale = 1) 通常会在输出中省略。这样可以减小有效载荷大小，并恢复与具有 4 KB 消息限制的旧版 Unity 包的兼容性。有两项高级设置（serialization/explicit_fields, serialization/force_complete_transforms) 的话，就可以为有此需求的消费者重新包含所有字段。
  • 减少主循环抖动——即使在解析 JSON 和进行网络传输期间，WebSocket 消息的处理也不会阻塞主循环的 tick，并且会话 tick 的调度已被提前至响应序列化之前。
  • 服务器默认仅限 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 信号处理——当启用了多线程冲突捕获时，进程将不再因致命信号而陷入无限循环。
  • 会话间命令覆盖— 此前，一个会话的配置命令可能会被另一个会话的命令悄然替换，但现在这些命令会得到正确的过滤和合并。
  • 覆盖 Probe 命令的设置 — probe_position传输监控会话（例如：Haply Hub）将不再默默覆盖待处理的 basis / preset / profile 更改。
  • 原型握把显示— 原型硬件被错误地显示为标准握把，而非自定义握把的问题。
  • 针对尚未迁移的客户端 Legacy set_basis 行列规则此功能现已恢复支持。
  • 断开会话连接后，Inverse3 的强力踢击将不再触发剩余力量激增。
  • 在反复快速建立和断开连接的过程中出现的WebSocket 连接丢失竞争状态。
  • 在某些发送有效载荷中，**WebSocket session_id**A 0此前在序列化时出现的问题。
  • 在 Windows 中 --dev现在与……配合使用时 --log-level此规则适用（此前为 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. WebSocket command_data的 values 该字段虽已停止支持，但仍会被解析。建议使用命名字段。

教程和文档​

  • 新教程：05 位置控制（Position Control）、06 集成（Inverse3 + Verse Grip）、07 基座与安装（Basis and Mount）、08 HTTP 远程配置器（Remote Configurator）、09 WebSocket 远程控制（Remote Control）、10 事件流监听器（Event Stream Listener）。
  • 新的 Glaze 变体: 除了现有的 nlohmann/json 变体外，所有 C++ 教程都新增了 Glaze 变体（cpp-glz/)已添加。
  • 重写所有教程: 已根据 v3.1 API 进行了重写（端口 10001， configure.preset, 命名的命令字段, print_state() 助手）。
  • 已删除：原有的 Verse Grip Stopper 教程已被删除，并由新的综合教程取代。
  • 公开文档更新：SDK 指南、API 参考和硬件页面均已全面更新。